1.7.1 Patch Release: Adds Support for Multiple Filesystem Data Roots

Changelog

Full Changelog

• Allow multiple root paths for FileSystemLoader #851 (robfrawley)
• Fix strange wording in readme #847 (svenluijten)

Upgrade

• [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 that this change creates a BC break for those relying on the protected class property FileSystemLoader::$dataRoot, whose type has changed to string[] and has been renamed to $dataRoots (plural).

• [Configuration] The liip_imagine.loaders.default.filesystem.data_root configuration option now accepts an array of paths (as strings), or a single string path (to preserve BC). This change allows the filesystem data loader to check multiple data root paths for the requested image resource. The following YML configuration provides examples using both a string and an array for the value.

    # 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 FileSystemLoader data loader in conjunction with symbolic links that point outside the data_root (which defaults to %kernel.root_dir%/../web) then you are required to set all outside resource paths under the data_root option.

  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"

  The full option key for data_root is

    liip_imagine.loaders.default.filesystem.data_root