DOC Document upgrading intervention/image

Author: GuySartorelli

en/02_Developer_Guides/14_Files/02_Images.md

@@ -318,16 +318,19 @@ SilverStripe\Assets\Image:
   lazy_loading_enabled: false
 ```
 
-## Changing the manipulation driver to imagick
+## Changing the manipulation driver {#intervention-image-driver}
 
-If you want to change the image manipulation driver to use Imagick instead of GD, you'll need to change your config so
-that the `Intervention\Image\ImageManager` is instantiated with the `imagick` driver instead of GD:
+If you have the [imagick PHP extension](https://www.php.net/manual/en/book.imagick.php) installed, it will be used as the driver for `intervention/image` by default. If you don't, the assumption is that you have the [GD PHP extension](https://www.php.net/manual/en/book.image.php) installed, and it will be used instead.
+
+If you want to change the image manipulation driver to something else (either a third-party driver, or else use GD even when imagick is installed), you need to configure that via the injector:
 
 ```yml
+---
+After: '#assetsimage-imagick'
+---
 SilverStripe\Core\Injector\Injector:
-  Intervention\Image\ImageManager:
-    constructor:
-      - { driver: imagick }
+  InterventionImageDriver:
+    class: 'Intervention\Image\Drivers\Gd\Driver'
 ```
 
 ## Storage

en/02_Developer_Guides/14_Files/05_File_Manipulation.md

@@ -209,7 +209,7 @@ This can be very useful if you want to convert a file to a different format for
 
 #### Making our own `FileConverter`
 
-Converting between image formats is the easiest example, because we can let [Intervention Image](https://image.intervention.io/v2) do the heavy lifting for us. Note that there is a built in [`InterventionImageFileConverter`](api:SilverStripe\Assets\Conversion\InterventionImageFileConverter) class which does this already, but we'll use this as an example for how to create our own `FileConverter`.
+Converting between image formats is the easiest example, because we can let [Intervention Image](https://image.intervention.io/v3) do the heavy lifting for us. Note that there is a built in [`InterventionImageFileConverter`](api:SilverStripe\Assets\Conversion\InterventionImageFileConverter) class which does this already, but we'll use this as an example for how to create our own `FileConverter`.
 
 The `FileConverter` interface requires us to implement two methods:
 
@@ -219,7 +219,7 @@ The `FileConverter` interface requires us to implement two methods:
 ```php
 namespace App\Conversion;
 
-use Intervention\Image\Exception\ImageException;
+use Intervention\Image\Exceptions\RuntimeException;
 use SilverStripe\Assets\Conversion\FileConverter;
 use SilverStripe\Assets\Conversion\FileConverterException;
 use SilverStripe\Assets\File;
@@ -248,7 +248,7 @@ class ImageFileConverter implements FileConverter
                     return [$tuple, $backend];
                 }
             );
-        } catch (ImageException $e) {
+        } catch (RuntimeException $e) {
             throw new FileConverterException('Failed to convert: ' . $e->getMessage(), $e->getCode(), $e);
         }
     }
@@ -320,7 +320,7 @@ Our callback returns both the information about the variant file and the `Image_
 ```php
 try {
     // ...
-} catch (ImageException $e) {
+} catch (RuntimeException $e) {
     throw new FileConverterException('Failed to convert: ' . $e->getMessage(), $e->getCode(), $e);
 }
 ```

en/08_Changelogs/6.0.0.md

@@ -10,6 +10,8 @@ title: 6.0.0 (unreleased)
   - [Run `CanonicalURLMiddleware` in all environments by default](#url-middleware)
   - [Changes to scaffolded form fields](#scaffolded-fields)
   - [Other new features](#other-new-features)
+- [Dependency changes](#dependency-changes)
+  - [`intervention/image` has been upgraded from v2 to v3](#intervention-image)
 - [Bug fixes](#bug-fixes)
 - [API changes](#api-changes)
   - [Most extension hook methods are now protected](#hooks-protected)
@@ -58,6 +60,57 @@ All other models used `SearchableDropdownField` for `has_one` relations and `Gri
 - Native indexed PHP arrays can now be passed into templates and iterated over with `<% loop $MyArray %>`. Under the hood they are wrapped in [`ArrayList`](api:SilverStripe\View\ViewableData), so you can get the count using `$Count` and use `<% if $ArrayList %>` as a shortcut for `<% if $ArrayList.Count %>`. Other functionality from `ArrayList` such as filtering and sorting cannot be used on arrays since they don't have keys to filter or sort against.
 - Modules no longer need to have a root level `_config.php` or `_config` directory to be recognised as a Silverstripe CMS module. They will now be recognised as a module if they have a `composer.json` file with a `type` of `silverstripe-vendormodule` or `silverstripe-theme`.
 
+## Dependency changes
+
+### `intervention/image` has been upgraded from v2 to v3 {#intervention-image}
+
+We've upgraded from `intervention/image` v2 to v3. One of the main improvements included in this upgrade is full support for animated GIFs.
+
+If you are directly interacting with APIs from `intervention/image` in your project or module you should check out [their upgrade guide](https://image.intervention.io/v3/introduction/upgrade).
+
+#### Animated vs still images {#intervention-image-animations}
+
+Manipulating animated images takes longer, and results in a larger filesize.
+
+Because of this, the [`ThumbnailGenerator`](api:SilverStripe\AssetAdmin\Model\ThumbnailGenerator) will provide still images as thumbnails for animated gifs by default. You can change that for a given instance of `ThumbnailGenerator` by passing `true` to the [`setAllowsAnimation()`](api:SilverStripe\AssetAdmin\Model\ThumbnailGenerator::setAllowsAnimation()) method. For example, to allow animated thumbnails for `UploadField`:
+
+```yml
+---
+After: '#assetadminthumbnails'
+---
+SilverStripe\Core\Injector\Injector:
+  SilverStripe\AssetAdmin\Model\ThumbnailGenerator.assetadmin:
+    properties:
+      AllowsAnimation: true
+```
+
+When manipulating images yourself, you can use the new [`RemoveAnimation()`](api:SilverStripe\Assets\ImageManipulation::RemoveAnimation()) method before your resizing methods:
+
+```ss
+$MyImage.RemoveAnimation.FitMax(300, 200)
+```
+
+If the image isn't animated `RemoveAnimation()` will just return the original image without generating a variant, so it's safe to use without first checking if the image is animated.
+
+#### Using GD or Imagick {#intervention-image-driver}
+
+One of the changes that comes as a result of this upgrade is a change in how you configure which manipulation driver (GD or Imagick) to use.
+
+To facilitate upgrades and to ensure we are providing optimal defaults out of the box, if you have the [imagick PHP extension](https://www.php.net/manual/en/book.imagick.php) installed, it will be used as the driver for `intervention/image` by default. If you don't, the assumption is that you have the [GD PHP extension](https://www.php.net/manual/en/book.image.php) installed, and it will be used instead.
+
+See [changing the manipulation driver](/developer_guides/files/images/#intervention-image-driver) for the new configuration for swapping the driver used by `intervention/image`.
+
+#### New API {#intervention-image-new-api}
+
+The following new methods have been added to facilitate this upgrade:
+
+|Method name|Where the method was added|
+|---|---|
+|`getIsAnimated()`|[`AssetContainer::getIsAnimated()`](api:SilverStripe\Assets\Storage\AssetContainer::getIsAnimated()), [`ImageManipulation::getIsAnimated()`](api:SilverStripe\Assets\ImageManipulation::getIsAnimated()) (and therefore `DBFile`, `File`, and their subclasses), [`Image_Backend::getIsAnimated()`](api:SilverStripe\Assets\Image_Backend::getIsAnimated()), [`InterventionBackend::getIsAnimated()`](api:SilverStripe\Assets\InterventionBackend::getIsAnimated())|
+|`RemoveAnimation()`|[`ImageManipulation::RemoveAnimation()`](api:SilverStripe\Assets\ImageManipulation::RemoveAnimation()) (and therefore `DBFile`, `File`, and their subclasses), [`Image_Backend::removeAnimation()`](api:SilverStripe\Assets\Image_Backend::removeAnimation()), [`InterventionBackend::removeAnimation()`](api:SilverStripe\Assets\InterventionBackend::removeAnimation())|
+|`getAllowsAnimation()`|[`ThumbnailGenerator::getAllowsAnimation()`](api:SilverStripe\AssetAdmin\Model\ThumbnailGenerator::getAllowsAnimation())|
+|`setAllowsAnimation()`|[`ThumbnailGenerator::setAllowsAnimation()`](api:SilverStripe\AssetAdmin\Model\ThumbnailGenerator::setAllowsAnimation())|
+
 ## Bug fixes
 
 This release includes a number of bug fixes to improve a broad range of areas. Check the change logs for full details of these fixes split by module. Thank you to the community members that helped contribute these fixes as part of the release!