File System Loader

Configuration

To set this loader for a specific context called profile_photos, use:

1
2
3
4
5
6

# app/config/config.yml

liip_imagine:
    loaders:
        profile_photos:
            filesystem: ~

By default, Symfony's web/ directory is registered as a data root to load assets from. For many installations this will be sufficient, but sometime you may need to load images from other locations. To do this, you must set the data_root parameter.

1
2
3
4
5
6
7

# app/config/config.yml

liip_imagine:
    loaders:
        default:
            filesystem:
                data_root: /path/to/source/images/dir

As of version 1.7.2 you can register multiple data roots and the file locator will search each for the requested file.

1
2
3
4
5
6
7
8
9

# app/config/config.yml

liip_imagine:
    loaders:
        default:
            filesystem:
                data_root:
                    - /path/foo
                    - /path/bar

As of version 2.1.0 you can allow invalid data roots (which are removed at runtime) in your configuration (normally invalid data roots will cause an exception to be thrown). This allows you to configure your data roots for production and development environments without relying on multiple configurations.

1
2
3
4
5
6
7
8
9
10
11

# app/config/config.yml

liip_imagine:
    loaders:
        default:
            filesystem:
                data_root:
                    - /path/foo
                    - /path/bar
                    - /invalid/path/will/be/removed/at/runtime
                allow_unresolvable_data_roots: true

As of version 1.7.3 you ask for the public resource paths from all registered bundles to be auto-registered as data roots. This allows you to load assets from the Resources/public folders that reside within the loaded bundles. To enable this feature, set the bundle_resources.enabled configuration option to true.

1
2
3
4
5
6
7
8

# app/config/config.yml

liip_imagine:
    loaders:
        default:
            filesystem:
                bundle_resources:
                    enabled: true

If you want to register some of the Resource/public folders, but not all, you can do so by blacklisting the bundles you don't want registered or whitelisting the bundles you do want registered. For example, to blacklist (not register) the bundles "FooBundle" and "BarBundle", you would use the following configuration.

1
2
3
4
5
6
7
8
9
10
11
12

# app/config/config.yml

liip_imagine:
    loaders:
        default:
            filesystem:
                bundle_resources:
                    enabled: true
                    access_control_type: blacklist
                    access_control_list:
                        - FooBundle
                        - BarBundle

Alternatively, if you want to whitelist (only register) the bundles "FooBundle" and "BarBundle", you would use the following configuration.

1
2
3
4
5
6
7
8
9
10
11
12

# app/config/config.yml

liip_imagine:
    loaders:
        default:
            filesystem:
                bundle_resources:
                    enabled: true
                    access_control_type: whitelist
                    access_control_list:
                        - FooBundle
                        - BarBundle

Lastly, as of version `1.7.3`, you can name your data roots and reference them when calling resources. This can be useful for a number of reasons, such as wanting to be explicit, but it most useful when you have multiple data roots paths that both contain a file of the same name. In this situation, you can name your data root paths by providing an index in the `data_root` configuration array (note that auto-registered bundle resource paths have indices defined of the bundle's short class name).

1
2
3
4
5
6
7
8
9

# app/config/config.yml

liip_imagine:
    loaders:
        default:
            filesystem:
                data_root:
                    foo: /a/foo/path
                    bar: /a/bar/path

Given the above configuration, you can explicitly request a root path using the format @index:path/to/file.ext. For example, to request the file /a/foo/path/with/file.ext you can pass @foo:with/file.ext as the filename.