UPGRADE.md

Upgrade Notices

This file contains a descriptive enumeration of important changes that may require manual intervention in your application code or are otherwise particularly noteworthy. Reference our full changelog for a complete list of all changes for a given release.

2.3.0 - 2.7.0

• [Deprecated] As doctrine/cache has been deprecated, the Liip\ImagineBundle\Imagine\Resolver\CacheResolver class and the corresponding service prototype - liip_imagine.cache.resolver.prototype.cache have been deprecated. Please use the new PSR-6 compatible resolver PsrCacheResolver and the prototype liip_imagine.cache.resolver.prototype.psr_cache instead.

• [BC BREAK] Symfony 5.0 did a BC break with its mime type / extension guesser. We had to adjust dependency injection. Usually this should not affect you, unless you overwrote liip_imagine.mime_type_guesser or liip_imagine.extension_guesser. If you did, please have a look at liip#1379

• [Deprecated] The watermark and paste filters were deprecated and will immediately not work in Symfony 5.0 or higher. Use watermark_image and paste_image instead. The corresponding services - the services liip_imagine.filter.loader.paste and liip_imagine.filter.loader.image are also deprecated, but not marked as such. These are both unavailable in Symfony 5.0.

• [Composer] Allow league/flysystem version 2.0. You can use league/flysystem either v1 or v2, but if you're using v1 and want to upgrade to v2 you can simply run composer require -W liip/imagine-bundle:^2.5 league/flysystem:^2.0. You should upgrade flysystem v2 related packages that you're using as well.

2.2.0

Released on 2019-04-10 and assigned 2.2.0 tag (view verbose changelog).

• Until this version, it was possible to pass any URL with domain to the ImagineController and, if the StreamLoader was used, have your application download images from anywhere and store them locally. In 2.2.0, this security issue has been fixed. If you relied on this, you need to download images to a location that can be accessed by your configured loader. If everything comes from the same domain, you could use the StreamLoader with that domain configured as prefix.

• [Deprecated] Constructing FileSystemLoader, FlysystemLoader, SimpleMimeTypeGuesser and DataManager with \Symfony\Component\HttpFoundation\File\MimeType\MimeTypeGuesserInterface and \Symfony\Component\HttpFoundation\File\MimeType\ExtensionGuesserInterface have been deprecated for Symfony 4.3+ in favor of the new interfaces.

• [Utility] [BC BREAK] The SymfonyFramework class marked as internal has been declared as final.

2.0.0

Released on 2018-04-06 and assigned 2.0.0 tag (view verbose changelog).

• [Post Processor] [BC BREAK] The PostProcessorConfigurablePostProcessorInterface interface has been completely removed and the PostProcessorInterface interface has been updated to allow passing the configuration array to its process method as the second parameter. The PostProcessorInterface::process() now implements the following signature: process(BinaryInterface $binary, array $options = []): BinaryInterface. All custom post processors in your project must be updated to match this new signature.

• [Dependencies] The imagine/Imagine dependency has been updated from the 0.6.x series to require 0.7.1 or greater. If you project has a hard dependency on any prior version, you will need to update your dependencies.

• [Form] The legacy setDefaultOptions() and getName() methods on Form/Type/ImageType have been removed, as these methods are no longer required for Symfony. If using them, you will need to update your implementation.

• [Dependency Injection] The DependencyInjection/Factory/ChildDefinitionTrait trait has been removed, as it handled logic to support legacy Symfony versions no longer targeted.

• [Dependency Injection] The compiler pass log method signature has changed to log(ContainerBuilder $container, string $message, ...$replacements): void. If you are extending AbstractCompilerPass and using this protected method, you must update your usage.

• [Dependency Injection] The default values for the liip_imagine.loaders.<name>.filesystem.data_root and liip_imagine.resolvers.<name>.web_path.web_root configuration options are now variable based on the Symfony version. For Symfony 4.0.0 and later, the value is %kernel.project_dir%/public, and for prior releases (such as the Symfony 3.x), the value is %kernel.project_dir%/web. This should automatically provide a suitable default for the different directory structures of the 4.x and 3.x Symfony releases.

• [Dependency Injection] [Filter] A new filter service abstraction is available as liip_imagine.service.filter with a createFilteredBinary($path, $filter, array $runtimeFilters = []) method to quickly get the filtered binary image and a getUrlOfFilteredImage($path, $filter, $resolver = null) method to quickly resolve and get the filtered image URL.

• [Data Loader] The FileSystemLoader::__construct() method signature has changed in accordance with the prior deprecation notice; the third parameter must be of signature \Liip\ImagineBundle\Binary\Locator\LocatorInterface $locator and the fourth parameter must be of signature array $dataRoots.

• [Data Loader] The GridFSLoader data loader has been removed as the required mongo extension has been deprecated and will not be ported to PHP 7.x.

• [Dependency Injection] A new interface \Liip\ImagineBundle\DependencyInjection/Factory/FactoryInterface has been introduced and is shared between the loaders (LoaderFactoryInterface) and resolvers (ResolverFactoryInterface).

• [Dependency Injection] All class name parameters have been removed from the service definitions. Instead of overwriting the class name parameters to provide your own implementation, use service decoration.

• [Data Transformer] The data transformer interface (\Liip\ImagineBundle\Imagine\Data\Transforme\TransformerInterface) was deprecated in version 1.x and has been removed.

• [Templating] The imagine extension \Liip\ImagineBundle\Templating\ImagineExtension has been renamed to FilterExtension. Similarly, the template helper \Liip\ImagineBundle\Templating\Helper\ImagineHelper has been renamed to FilterHelper.

• [Utility] The \Liip\ImagineBundle\Utility/Framework/SymfonyFramework::hasDefinitionSharing() method has been removed due to our higher Symfony requirements rending it unnecessary.

• [General] The use of fully-qualified class name strings is no longer supported and the ::class compile-time class constant is now used.

• [Enqueue] Enqueue's producer send() method has been deprecated and will be removed, use sendCommand() instead. When interacting with the producer to resolve images in the background you must make the following changes to your code:

  <?php
  
    // 1.0
    $producer->send(\Liip\ImagineBundle\Async\Topics::RESOLVE_CACHE /* ... */);
  
    // 2.0
    $producer->sendCommand(\Liip\ImagineBundle\Async\Commands::RESOLVE_CACHE /* ... */);

• [Routing] The Resources/config/routing.xml file has been removed. Use the new Resources/config/routing.yaml YAML file instead.

1.9.1

Released on 2017-09-08 and assigned 1.9.1 tag (view verbose changelog).

• [Console] [BC BREAK] The resolve command's --as-script/-s option/shortcut renamed to --machine-readable/-m (fixes #988), its output updated to aligned with the resolve command, and the "--machine-readable/-m" option added. #991 (robfrawley)

1.9.0

Released on 2017-08-30 and assigned 1.9.0 tag (view verbose changelog).

• [Tests] Fix filesystem loader deprecation message in tests. #982 (robfrawley)
• [Filter] Add "centerright" and "centerleft" positions to background filter. #974 (cmodijk)
• [Config] Allow to configure the HTTP response code for redirects. #970 (lstrojny)
• [Console] Added --force option, renamed --filters to --filter, and made resolve command output pretty. #967 (robfrawley)
• [CS] Fix two docblock annotations. #965 (imanalopher)
• [Data Loader] [Deprecation] The FileSystemLoader no longer accepts an array of data root paths; instead pass a FileSystemLocator, which should instead be passed said paths. #963 (robfrawley, rpkamp)
• [Composer] Allow avalanche123/Imagine version 0.7.0. #958 (robfrawley)
• [Data Loader] [Documentation] Add chain loader documentation. #957 (robfrawley)
• [Data Loader] Add chain loader implementation. #953 (robfrawley)
• [CS] Fix templating extension method return type. #951 (imanalopher)
• [Dependency Injection] Fix compiler pass log message typo. #947 (you-ser)
• [Travis] Default to trusty container image (with precise image for php 5.3). #945 (robfrawley)
• [Enqueue] Use simplified transport configuration. #942 (makasim)
• [Filter] Add resolution loader implementation. #941 (robfrawley)
• [Travis] Remove Symfony 3.3 from allowed failures. #940 (robfrawley)
• [Utility] Use simplified Symfony kernel version comparison operation. #939 (robfrawley)

1.8.0

• [Routing] The Resources/config/routing.xml file has been deprecated and will be removed in 2.0. Use the new YAML variant moving forward Resources/config/routing.yaml.

1.7.3

• [Data Loader] The FileSystemLoader now allows you to assign keys to data roots, and directly reference them when requesting resources.

    # provide index for data roots
    liip_imagine:
      loaders:
        default:
          filesystem:
            data_root:
              foo: /path/to/foo
              bar: /path/to/bar
  

  Assume you have a file name file.ext in both data root paths. Given the above configuration, you can specifically request the file from the /path/to/foo root using the following file syntax: @foo:file.ext. Similarly, you can request the same file from /path/to/bar using @bar:file.ext. Note, that the auto-registered bundles (detailed below) are given indexes of their short bundle name (for example, given the bundle FooBundle, you can request a file from its public resources path via @FooBundle:path/to/file.ext).

• [Data Loader] The FileSystemLoader now supports automatically registering the Resources/public folders within all loaded bundles. This can be enabled via the following configuration.

    # enable bundle auto-registration
    liip_imagine:
      loaders:
        default:
          filesystem:
            bundle_resources:
              enabled: true
  

  Additionally, you can whitelist or blacklist specific bundles from the auto-registration routine.

    # blacklist "FooBundle" from auto-registration
    liip_imagine:
      loaders:
        default:
          filesystem:
            bundle_resources:
              enabled: true
              access_control_type: blacklist
              access_control_list
                - FooBundle
  
    # whitelist "BarBundle" from auto-registration
    liip_imagine:
      loaders:
        default:
          filesystem:
            bundle_resources:
              enabled: true
              access_control_type: whitelist
              access_control_list
                - BarBundle
  

• [Data Locator] The *Locator services passed to FileSystemLoader are now marked as "non-shared" or "prototype" within the DI container, resulting in new instances being passed every time the services are requested.

1.7.2

• [Data Loader] The FileSystemLoader's resource locator has been abstracted out into FileSystemLocator (provides the same realpath-based locator algorithm introduced in the 1.7.0 release) and FileSystemInsecureLocator (provides the old locator algorithm from version 1.6.x and prior).

  The latter implementation can present security concerns, as it will blindly following symbolic links, including those that point outside your configured data_root directory(ies). It is not recommended unless your deployment process relies heavily on multi-level symbolic links that renders the new locator difficult (and sometime impossible) to setup.

• [Deprecation] [Data Loader] Instantiating FileSystemLoader without providing a forth constructor argument of signature \Liip\ImagineBundle\Binary\Locator\LocatorInterface $locator is deprecated and the ability to do so will be removed in the next major release, 2.0.

• [Configuration] The liip_imagine.loaders.default.filesystem.locator bundle configuration option has been introduced and allows the following enum values: filesystem and filesystem_insecure. These correspond to the aforementioned FileSystemLocator and FileSystemInsecureLocator resource locator implementations that affect the behavior of FileSystemLoader. This option defaults to filesystem.

    # use the current, default locator algorithm
    liip_imagine:
      loaders:
        default:
          filesystem:
            locator: filesystem
  
    # use the old (pre 0.7.x) locator algorithm
    liip_imagine:
      loaders:
        default:
          filesystem:
            locator: filesystem_insecure
  

• [Dependency Injection] All compiler passes (filters, post-processors, data loaders, cache resolvers, etc) have been updated to log their behavior, allowing you to easily debug tagged services, including both core-provided and custom services defined by your application). In Symfony >= 3.2 this output is located in the var/cache/[dev|prod|env]/app*ProjectContainerCompiler.log file. Output will be similar to the following example on a fresh install.

  
    LoadersCompilerPass: Registered imagine-bimdle binary loader: liip_imagine.binary.loader.default
    FiltersCompilerPass: Registered imagine-bimdle filter loader: liip_imagine.filter.loader.relative_resize
    FiltersCompilerPass: Registered imagine-bimdle filter loader: liip_imagine.filter.loader.resize
    FiltersCompilerPass: Registered imagine-bimdle filter loader: liip_imagine.filter.loader.thumbnail
    FiltersCompilerPass: Registered imagine-bimdle filter loader: liip_imagine.filter.loader.crop
    FiltersCompilerPass: Registered imagine-bimdle filter loader: liip_imagine.filter.loader.grayscale
    FiltersCompilerPass: Registered imagine-bimdle filter loader: liip_imagine.filter.loader.paste
    FiltersCompilerPass: Registered imagine-bimdle filter loader: liip_imagine.filter.loader.watermark
    FiltersCompilerPass: Registered imagine-bimdle filter loader: liip_imagine.filter.loader.background
    FiltersCompilerPass: Registered imagine-bimdle filter loader: liip_imagine.filter.loader.strip
    FiltersCompilerPass: Registered imagine-bimdle filter loader: liip_imagine.filter.loader.scale
    FiltersCompilerPass: Registered imagine-bimdle filter loader: liip_imagine.filter.loader.upscale
    FiltersCompilerPass: Registered imagine-bimdle filter loader: liip_imagine.filter.loader.downscale
    FiltersCompilerPass: Registered imagine-bimdle filter loader: liip_imagine.filter.loader.auto_rotate
    FiltersCompilerPass: Registered imagine-bimdle filter loader: liip_imagine.filter.loader.rotate
    FiltersCompilerPass: Registered imagine-bimdle filter loader: liip_imagine.filter.loader.interlace
    PostProcessorsCompilerPass: Registered imagine-bimdle filter post-processor: liip_imagine.filter.post_processor.jpegoptim
    PostProcessorsCompilerPass: Registered imagine-bimdle filter post-processor: liip_imagine.filter.post_processor.optipng
    PostProcessorsCompilerPass: Registered imagine-bimdle filter post-processor: liip_imagine.filter.post_processor.pngquant
    PostProcessorsCompilerPass: Registered imagine-bimdle filter post-processor: liip_imagine.filter.post_processor.mozjpeg
    ResolversCompilerPass: Registered imagine-bimdle cache resolver: liip_imagine.cache.resolver.default
    ResolversCompilerPass: Registered imagine-bimdle cache resolver: liip_imagine.cache.resolver.no_cache_web_path
  
  

1.7.1

• [Data Loader] The FileSystemLoader data loader performs a more robust security check against image resource paths to ensure they reside within the defined data root path(s). If utilizing symbolic links, you should reference the troubleshooting guide at the end of this upgrade notice.

• [Data Loader] The FileSystemLoader data loader now accepts an array of paths (as strings) for its third constructor argument, enabling the loader to check multiple paths for the requested image resource. Note: this change breaks those extending this class and relying on the protected property $dataRoot, which has been renamed to $dataRoots and is now of the type string[] instead of the prior type of string.

• [Configuration] The liip_imagine.loaders.default.filesystem.data_root bundle configuration option now accepts an array of paths (as strings) or a single scalar path ()if only one is required for your configuration), allowing the filesystem data loader to check multiple data root paths for the requested image resource. The following YML configuration shows examples for all allowed value types.

    # provide an array of scalar paths
    liip_imagine:
      loaders:
        default:
          filesystem:
            data_root:
              - /multiple/root/paths/foo
              - /multiple/root/paths/bar
  
    # provide an single scalar path
    liip_imagine:
      loaders:
        default:
          filesystem:
            data_root: /single/root/path
  

• [Troubleshooting] If you are using the filesystem data loader and have symbolic links within the data_root that point outside this path (the data_root option defaults to %kernel.root_dir%/../web) then you are required to configure all outside resource paths as additional data_root paths using the following option key in your application's configuration: liip_imagine.loaders.default.filesystem.data_root.

  The following is a list of the most common exception error messages encountered when the data_root option is not correctly configured:

  • Source image not resolvable "%s" in root path(s) "%s"

  • Source image invalid "%s" as it is outside of the defined root path(s) "%s"

1.0.0-alpha7

• [Configuration] liip_imagine.controller_action option was removed in favour of an array of actions. See liip_imagine.controller config

    -liip_imagine:
    -    controller_action: AcmeDemoBundle:Default:filterAction
    +liip_imagine:
    +    controller:
    +       filter_action: AcmeDemoBundle:Default:filterAction
  

1.0.0-alpha6

• [Route] ImagineLoader was removed. Please adjust your app/config/routing.yml file.

    -_imagine:
    -    resource: .
    -    type:     imagine
    +_liip_imagine:
    +    resource: "@LiipImagineBundle/Resources/config/routing.xml"
  

• [Configuration] liip_imagine.filter_sets.route option and sub options were removed.

• [Configuration] liip_imagine.cache_prefix option was removed.

1.0.0-alpha5

• [Symfony] Required minimum symfony version was updated to 2.3.

• [Logger] Symfony LoggerInterface was replaced with PSR-3 one.

• [Cache] New isStored method was added.

• [Cache] The method ResolverInterface::getBrowserPath was removed.

• [Cache] The method ResolverInterface::store accept BinaryInterface as first argument.

• [Cache] The method ResolverInterface::store return nothing.

• [Cache] The method ResolverInterface::remove return nothing.

• [Cache] The method ResolverInterface::remove takes required array of filter as first argument.

• [Cache] The method ResolverInterface::remove takes optional path as second argument.

• [Cache] The method ResolverInterface::clean was removed.

• [Cache] The method ResolverInterface::resolve takes path and filter as arguments.

• [Cache] The method ResolverInterface::resolve return absolute url of the cached image.

• [Cache] The method CacheManager::resolve may throw OutOfBoundsException if required resolver does not exist.

• [Cache] The method CacheManager::resolve return absolute url of the cached image.

• [Cache] The method CacheManager::store accept BinaryInterface as first argument.

• [Cache] The method CacheManager::store return nothing.

• [Cache] The method CacheManager::clearResolversCache was removed.

• [Cache] The method CacheManager::getWebRoot was removed.

• [Cache] The method CacheManager::getBrowserPath third argument was changed, now it is runtimeConfig.

• [Cache] The method CacheManager::generateUrl third argument was changed, now it is runtimeConfig.

• [Cache] NoCacheResolver renamed to NoCacheWebPathResolver.

• [Cache] AbstractFilesystemResolver was removed.

• [Data Loader] LoaderInterface::find now can return string or BinaryInterface instance.

• [Data Loader] DataManager::find now can return BinaryInterface instance only.

• [Data Loader] All data loaders moved to Binary/Loader folder.

• [Data Loader] Tag name liip_imagine.data.loader changed to liip_imagine.binary.loader

• [Data Loader] Parameter key liip_imagine.data.loader.filesystem.class changed to liip_imagine.binary.loader.filesystem.class

• [Data Loader] Parameter key liip_imagine.data.loader.stream.class changed to liip_imagine.binary.loader.stream.class

• [Data Loader] Service id liip_imagine.data.loader.prototype.filesystem changed to liip_imagine.binary.loader.prototype.filesystem

• [Data Loader] Service id liip_imagine.data.loader.prototype.stream changed to liip_imagine.binary.loader.prototype.stream

• [Filter] FilterManager::applyFilter now return instance of BinaryInterface.

• [Filter] FilterManager::applyFilter first argument was changed from Image instance to BinaryInterface one.

• [Filter] FilterManager::get was removed.

• [Configuration] liip_imagine.filter_sets.path option was removed.

• [Configuration] liip_imagine.filter_sets.format option was removed.

• [Configuration] liip_imagine.cache_mkdir_mode option was removed.

• [Configuration] liip_imagine.web_root option was removed.

• [Configuration] liip_imagine.cache default value was changed from web_pathto default.

• [Configuration] liip_imagine.formats option was removed.

• [Configuration] liip_imagine.data_root option was removed.