Add v7 docs

Author: Rias

.gitignore

@@ -1,5 +1,4 @@
 build
-docs
 vendor
 tests/Support/temp
 tests/temp

docs/_index.md

@@ -0,0 +1,6 @@
+---
+title: v7
+slogan: Associate files with Eloquent models.
+githubUrl: https://github.com/spatie/laravel-medialibrary
+branch: v7
+---

docs/about-us.md

@@ -0,0 +1,10 @@
+---
+title: About us
+---
+
+[Spatie](https://spatie.be) is a webdesign agency based in Antwerp, Belgium.
+
+Open source software is used in all projects we deliver. Laravel, Nginx, Ubuntu are just a few 
+of the free pieces of software we use every single day. For this, we are very grateful. 
+When we feel we have solved a problem in a way that can help other developers, 
+we release our code as open source software [on GitHub](https://spatie.be/opensource).

docs/advanced-usage/_index.md

@@ -0,0 +1,4 @@
+---
+title: Advanced usage
+weight: 7
+---

docs/advanced-usage/consuming-events.md

@@ -0,0 +1,66 @@
+---
+title: Consuming events
+weight: 8
+---
+
+The medialibrary will fire the following events that your handlers can listen for:
+
+### MediaHasBeenAdded
+This event is fired after the a file has been saved to disk.
+
+The event has a property `media` that holds the `\Spatie\MediaLibrary\Models\Media`-object of which the file has been stored.
+
+### ConversionWillStart
+This event is fired right before a conversion will start.
+
+The event has two public properties:
+
+- `media`: the `\Spatie\MediaLibrary\Models\Media`-object of which a conversion will be started
+- `conversion`: the conversion (an instance of `\Spatie\MediaLibrary\Conversion\Conversion`) that will start
+
+### ConversionHasBeenCompleted
+This event is fired when a conversion has been completed.
+
+The event has two public properties:
+
+- `media`: the `\Spatie\MediaLibrary\Models\Media`-object of which a conversion has been completed
+- `conversion`: the conversion (an instance of `\Spatie\MediaLibrary\Conversion\Conversion`) that has just been completed
+
+### CollectionHasBeenCleared
+This event will be fired after a collection has been cleared.
+
+The event has two public properties:
+
+- `model`:  the object that conforms to `\Spatie\MediaLibrary\HasMedia\Interfaces\HasMedia` of which a collection has just been cleared.
+- `collectionName`: the name of the collection that has just been cleared
+
+## Sample usage
+
+First you must created a listener class. Here's one that will log the paths of added media.
+
+```php
+namespace App\Listeners;
+
+use Log;
+use Spatie\MediaLibrary\Events\MediaHasBeenAdded;
+
+class MediaLogger
+{
+    public function handle(MediaHasBeenAdded $event)
+    {
+        $media = $event->media;
+        $path = $media->getPath();
+        Log::info("file {$path} has been saved for media {$media->id}");
+    }
+}
+```
+
+Hook it up in `app/Providers/EventServiceProvider.php` to let Laravel know that your handler should be called when the event is fired:
+
+```php
+protected $listen = [
+    'Spatie\MediaLibrary\Events\MediaHasBeenAdded' => [
+        'App\Listeners\MediaLogger'
+    ],
+];
+```

docs/advanced-usage/generating-custom-urls.md

@@ -0,0 +1,55 @@
+---
+title: Generating custom urls
+weight: 9
+---
+
+When `getUrl` is called, the task of generating that url is passed to an implementation of `Spatie\MediaLibrary\UrlGenerator`.
+
+The package contains a `LocalUrlGenerator` that can generate urls for a media library that is stored inside the public path. An `S3UrlGenerator` is also included for when you're using S3 to store your files.
+
+If you are storing your media files in a private directory or are using a different filesystem, you can write your own `UrlGenerator`. Your generator must adhere to the `Spatie\MediaLibrary\UrlGenerator` interface. If you'd extend `Spatie\MediaLibrary\UrlGenerator\BaseUrlGenerator` you only need to implement the methods: `getUrl`, `getTemporaryUrl` and `getResponsiveImagesDirectoryUrl`. You can call `getPathRelativeToRoot` to get the relative path to the root of your disk.
+
+The code of the included `S3UrlGenerator` should help make things more clear:
+
+```php
+namespace Spatie\MediaLibrary\UrlGenerator;
+
+class S3UrlGenerator extends BaseUrlGenerator
+{
+    /**
+     * Get the url for the profile of a media item.
+     *
+     * @return string
+     */
+    public function getUrl() : string
+    {
+        return config('medialibrary.s3.domain').'/'.$this->getPathRelativeToRoot();
+    }
+    
+    /**
+     * Get the temporary url for a media item.
+     *
+     * @param \DateTimeInterface $expiration
+     * @param array $options
+     *
+     * @return string
+     */
+    public function getTemporaryUrl(DateTimeInterface $expiration, array $options = []): string
+    {
+        return $this
+            ->filesystemManager
+            ->disk($this->media->disk)
+            ->temporaryUrl($this->getPath(), $expiration, $options);
+    }
+    
+    /**
+     * Get the url to the directory containing responsive images.
+     *
+     * @return string
+     */
+    public function getResponsiveImagesDirectoryUrl(): string
+    {
+        return config('medialibrary.s3.domain').'/'.$this->pathGenerator->getPathForResponsiveImages($this->media);
+    }
+}
+```

docs/advanced-usage/moving-media.md

@@ -0,0 +1,14 @@
+---
+title: Moving media
+weight: 7
+---
+
+You can move media from one model to another with the `move` method.
+
+```php
+$mediaItem = $model->getMedia()->first();
+
+$movedMediaItem = $mediaItem->move($anotherModel);
+```
+
+Any conversions defined on `$anotherModel` will be performed. The `name` and the `custom_properties` will be transferred as well.

docs/advanced-usage/ordering-media.md

@@ -0,0 +1,28 @@
+---
+title: Ordering media
+weight: 6
+---
+
+Laravel medialibrary has a built in feature to help you order the media in your project. By default all inserted media items are ordered by their creation order (from the oldest to the newest) using the `order_column` column of the `media` table.
+
+You can easily reorder a list of media by calling  ̀Media::setNewOrder`:
+
+```php
+ /**
+  * This function reorders the records: the record with the first id in the array
+  * will get order 1, the record with the second id will get order 2, ...
+  *
+  * A starting order number can be optionally supplied (defaults to 1).
+  *
+  * @param array $ids
+  * @param int $startOrder
+  */
+Media::setNewOrder([11, 2, 26]);
+```
+
+Of course you can also manually change the value of the `order_column`.
+
+```php
+$media->order_column = 10;
+$media->save();
+```

docs/advanced-usage/overriding-the-default-filesystem-behaviour.md

@@ -0,0 +1,24 @@
+---
+title: Overriding default filesystem behavior
+weight: 10
+---
+
+The `Spatie\MediaLibrary\Filesystem\Filesystem` class contains the behavior for actions like adding files, renaming files and deleting files. It applies these actions to the disks (local, S3, etc) that you configured.
+
+If you want to override the default behavior you can create your own  implementation by extending `Spatie\MediaLibrary\Filesystem\Filesystem`. You then bind your own class to the service container in the `AppServiceProvider`:
+
+```php
+use App\CustomFilesystem;
+use Spatie\MediaLibrary\Filesystem\Filesystem;
+ 
+class AppServiceProvider extends ServiceProvider
+{
+    ...
+    public function register()
+    {
+        $this->app->bind(Filesystem::class, CustomFilesystem::class);
+    }
+}
+```
+
+Generally speaking you do not want to mess with this class, so only override it if you know what you're doing.

docs/advanced-usage/storing-media-specific-manipulations.md

@@ -0,0 +1,71 @@
+---
+title: Storing media specific manipulations
+weight: 3
+---
+
+Imagine you need to apply a 90 degree rotation to a single image. So the rotation should be applied to one specific `Media` and not to all media linked to the given `$newsItem`.
+
+When adding an image to the medialibrary, you can use `withManipulations` to set any media specific manipulations.
+
+Here's a quick example:
+
+```php
+$newsItem
+   ->addMedia($pathToFile)
+   ->withManipulations([
+      'thumb' => ['orientation' => '90'],
+   ]);
+```
+
+The package will regenerate all files (conversions) using the saved manipulation as the first manipulation when creating each derived image.
+
+You can also apply media specific manipulations to an existing `Media` instance.
+
+```php
+$mediaItems = $newsItem->getMedia('images');
+$mediaItems[0]->manipulations = [
+   'thumb' => ['orientation' => '90'],
+];
+
+// This will cause the thumb conversions to be regenerated.
+$mediaItems[0]->save();
+```
+
+First the rotation will be applied for this specific `$mediaItem`, then the other manipulations you specified in the `thumb` conversion.
+
+Of course you can also set media specific manipulations for multiple conversions in one go:
+
+```php
+$newsItem
+   ->addMedia($pathToFile)
+   ->withManipulations([
+      'thumb' => ['orientation' => '90'],
+      'otherConversion' => ['orientation' => '90'],
+   ]);
+```
+
+Lets take the example again of this one image `$mediaItem` that needs to be rotated and was linked to `$newsItem`. Imagine we have a lot of conversions for all the media: `thumb`, `small` for web, `cmyk` for print in full resolution.
+Having to add all these manipulation keys with `orientation 90` would be a pain. 
+
+You can avoid this pain by using a wildcard. Manipulations of the wildcard will be added to each conversion of the media.
+
+Here's an example:
+
+```php
+$newsItem
+   ->addMedia($pathToFile)
+   ->withManipulations([
+      '*' => ['orientation' => '90'],
+   ]);
+```
+
+You can also combine wildcard manipulations with one for a specific collection. The wildcard manipulations will always be performed before the collection specific ones.
+
+```php
+$newsItem
+   ->addMedia($pathToFile)
+   ->withManipulations([
+      '*' => ['orientation' => '90'],
+      'thumb' => ['filter' => 'greyscale'],
+   ]);
+```

docs/advanced-usage/using-a-custom-directory-structure.md

@@ -0,0 +1,70 @@
+---
+title: Using a custom directory structure
+weight: 5
+---
+
+By default, files will be stored inside a directory that uses the `id` of its `Media`-object as a name. Converted images will be stored inside a directory named `conversions`.
+
+```
+media
+---- 1
+------ file.jpg
+------ conversions
+--------- small.jpg
+--------- medium.jpg
+--------- big.jpg
+---- 2
+------ file.jpg
+------ conversions
+--------- small.jpg
+--------- medium.jpg
+--------- big.jpg
+...
+```
+
+Putting files inside their own folders guarantees that files with the same name can be added without any problems.
+
+To override this default folder structure, a class that conforms to the `PathGenerator`-interface can be specified as the `path_generator` in the config file.
+
+Let's take a look at the interface:
+
+```php
+namespace Spatie\MediaLibrary\PathGenerator;
+
+use Spatie\MediaLibrary\Models\Media;
+
+interface PathGenerator
+{
+    /**
+     * Get the path for the given media, relative to the root storage path.
+     *
+     * @param \Spatie\MediaLibrary\Models\Media $media
+     *
+     * @return string
+     */
+    public function getPath(Media $media): string;
+
+    /**
+     * Get the path for conversions of the given media, relative to the root storage path.
+     *
+     * @param \Spatie\MediaLibrary\Models\Media $media
+     *
+     * @return string
+     */
+    public function getPathForConversions(Media $media): string;
+
+    /*
+     * Get the path for responsive images of the given media, relative to the root storage path.
+     *
+     * @param \Spatie\MediaLibrary\Models\Media $media
+     *
+     * @return string
+     */
+    public function getPathForResponsiveImages(Media $media): string;
+}
+```
+
+[This example from the tests](https://github.com/spatie/laravel-medialibrary/blob/7.0.0/tests/Unit/PathGenerator/CustomPathGenerator.php) uses
+the md5 value of media-id to name directories. The directories where conversions are stored will be named `c` instead of the default `conversions`.
+
+There aren't any restrictions on how the directories can be named. When a `Media`-object gets deleted the package will delete its entire associated directory. To avoid tears or worse, make sure that every media gets stored its own unique directory.