DOC Document upgrading intervention/image (#547)

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

@@ -103,6 +103,61 @@ Please refer to the [`ImageManipulation`](api:SilverStripe\Assets\ImageManipulat
 
 See [file manipulation](./file_manipulation/) for more general ways that all files can be manipulated.
 
+### Animated images
+
+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
+```
+
+The [`Image::PreviewLink()`](api:SilverStripe\Assets\Image::PreviewLink()) method also doesn't allow an animated result by default. This is used in the "Files" admin section, and anywhere you can choose an existing image such as `UploadField` and the WYSIWYG file modals.
+
+You can allow animated previews by setting [`Image.allow_animated_preview`](api:SilverStripe\Assets\Image->allow_animated_preview) configuration property to `true`:
+
+```yml
+SilverStripe\Assets\Image:
+  allow_animated_preview: true
+```
+
+You can disable the ability to create animated variants globally by setting `decodeAnimation` to `false` in the `Intervention\Image\ImageManager`'s constructor:
+
+```yml
+SilverStripe\Core\Injector\Injector:
+  Intervention\Image\ImageManager:
+    constructor:
+      decodeAnimation: false
+```
+
+This affects *all* scenarios where variants are created, both on the front-end and in the backend.
+
+> [!TIP]
+> Disabling animation globally is more performant than using `RemoveAnimation()` as described below, because it tells `intervention/image` to always only look at the first frame of any animated image - it doesn't even decode the remaining frames.
+
+When manipulating images yourself in templates, you can use the new [`RemoveAnimation()`](api:SilverStripe\Assets\ImageManipulation::RemoveAnimation()) method before your resizing methods:
+
+```ss
+$MyImage.RemoveAnimation.FitMax(300, 200)
+```
+
+`RemoveAnimation()` takes an optional parameter which you can use to determine which frame of animation is used as the still image. You can either pass in an exact frame number (0-indexed), or a percentage as a string (e.g. `$MyImage.RemoveAnimation('50%')` will use a frame halfway through the animation).
+
+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.
+
+You can also use the [`setAllowsAnimationInManipulations()`](api:SilverStripe\Assets\Image_Backend::setAllowsAnimationInManipulations()) method to toggle the `decodeAnimation` configuration setting for a given image. This is useful if you intend to make many manipulations to an image, and you want some to include animation and others to not include animation - you can simply toggle animation usage on and off using this method.
+
+```php
+$myImage->getImageBackend()->setAllowsAnimationInManipulations(false);
+```
+
 ### Creating custom image functions
 
 You can also create your own functions by decorating the `Image` class.
@@ -318,18 +373,32 @@ SilverStripe\Assets\Image:
   lazy_loading_enabled: false
 ```
 
-## Changing the manipulation driver to imagick
+## Changing the manipulation driver {#intervention-image-driver}
+
+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 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 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:
+  InterventionImageDriver:
+    class: 'Intervention\Image\Drivers\Gd\Driver'
+```
+
+You can also set various configuration options for the driver to use by setting them in the constructor for `Intervention\Image\ImageManager`, for example:
 
 ```yml
 SilverStripe\Core\Injector\Injector:
   Intervention\Image\ImageManager:
     constructor:
-      - { driver: imagick }
+      decodeAnimation: false
 ```
 
+The options available are detailed in the [intervention/image documentation](https://image.intervention.io/v3/basics/image-manager#configuration-options).
+
 ## Storage
 
 Manipulated images are stored as "file variants" in the same folder structure as the original image. The storage mechanism is described in the ["File Storage" guide](file_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

@@ -11,6 +11,8 @@ title: 6.0.0 (unreleased)
   - [Changes to default cache adapters](#caching)
   - [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)
@@ -74,6 +76,71 @@ 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
+```
+
+The [`Image::PreviewLink()`](api:SilverStripe\Assets\Image::PreviewLink()) method also doesn't allow an animated result by default. This is used in the "Files" admin section, and anywhere you can choose an existing image such as `UploadField` and the WYSIWYG file modals.
+
+You can allow animated previews by setting [`Image.allow_animated_preview`](api:SilverStripe\Assets\Image->allow_animated_preview) configuration property to `true`:
+
+```yml
+SilverStripe\Assets\Image:
+  allow_animated_preview: true
+```
+
+You can disable the ability to create animated variants globally by setting `decodeAnimation` to `false` in the `Intervention\Image\ImageManager`'s constructor:
+
+```yml
+SilverStripe\Core\Injector\Injector:
+  Intervention\Image\ImageManager:
+    constructor:
+      decodeAnimation: false
+```
+
+You can also toggle that configuration setting on and off for a given image instance, or create a variant from your image which uses a specific frame of animation - see [animated images](/developer_guides/files/images/#animated-images) for details.
+
+#### 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())|
+|`getAllowsAnimationInManipulations()`|[`Image_Backend::getAllowsAnimationInManipulations()`](api:SilverStripe\Assets\Image_Backend::getAllowsAnimationInManipulations()), [`InterventionBackend::getAllowsAnimationInManipulations()`](api:SilverStripe\Assets\InterventionBackend::getAllowsAnimationInManipulations())|
+|`setAllowsAnimationInManipulations()`|[`Image_Backend::setAllowsAnimationInManipulations()`](api:SilverStripe\Assets\Image_Backend::setAllowsAnimationInManipulations()), [`InterventionBackend::setAllowsAnimationInManipulations()`](api:SilverStripe\Assets\InterventionBackend::setAllowsAnimationInManipulations())|
+|`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!