# Built-In CacheResolver

* [Web path](cache-resolver/web_path.md)
* [AmazonS3](cache-resolver/amazons3.md)
* [AwsS3](cache-resolver/aws_s3.md) - for SDK version 2
* [CacheResolver](cache-resolver/cache.md)
* [ProxyResolver](cache-resolver/proxy.md)

# Changing the default cache resolver

The default cache is a web path cache that caches images under `{web}/media/cache/`.
You can specify the cache to use per individual filter_sets. To change the defaults,
you can either change the top level `cache` option to the name of the cache resolver
you want to use by default, or redefine the default cache resolver by explicitly
defining a resolver called `default`:

 ```yaml
liip_imagine:
    resolvers:
        default:
            web_path:
                cache_prefix: custom_path
 ```

# Custom cache resolver

The ImagineBundle allows you to add your custom cache resolver classes. The only
requirement is that each cache resolver loader implement the following interface:

    Liip\ImagineBundle\Imagine\Cache\Resolver\ResolverInterface

To tell the bundle about your new cache resolver, register it in the service
container and apply the `liip_imagine.cache.resolver` tag to it (example here in XML):

``` xml
<service id="acme_imagine.cache.resolver.my_custom" class="Acme\ImagineBundle\Imagine\Cache\Resolver\MyCustomCacheResolver">
    <tag name="liip_imagine.cache.resolver" resolver="my_custom_cache" />
    <argument type="service" id="filesystem" />
    <argument type="service" id="router" />
</service>
```

For more information on the service container, see the Symfony2
[Service Container](http://symfony.com/doc/current/book/service_container.html) documentation.

You can set your custom cache reslover by adding it to the your configuration as the new
default resolver as follows:

``` yaml
liip_imagine:
    cache: my_custom_cache
```

Alternatively you can only set the custom cache resolver for just a specific filter set:

``` yaml
liip_imagine:
    filter_sets:
        my_special_style:
            cache: my_custom_cache
            filters:
                my_custom_filter: { }
```

For an example of a cache resolver implementation, refer to
`Liip\ImagineBundle\Imagine\Cache\Resolver\WebPathResolver`.

[Back to the index](index.md)
                                                                                                                                                                                                                                                                                                       # LiipImagineBundle

## Basic Data Flow

The core feature of this bundle is to provide a way to alter images in certain ways and cache the altered versions.
There are several components involved to get this done.

### Retrieving the original image

The first step is to retrieve the original image, the one you address.

In order to retrieve such an image, there are so-called `DataLoader` those implement the `Liip\ImagineBundle\Binary\Loader\LoaderInterface`.
Those loaders are typically managed by the `DataManager` and automatically wired with it, using dependency injection.

How a specific `DataLoader` retrieves the image, is up to the loader. The most simple way is to read a file from the local filesystem. This is implemented by the `Liip\ImagineBundle\Binary\Loader\FileSystemLoader`, which is set by default.
You could also create a random image on the fly using drawing utilities, or read a binary stream from any stream registered.

The most important parts about those `DataLoader`:

1. They `find` a single image based on a given identifier.
2. They return a ready-to-use `Imagine\Image\ImageInterface`.

For more details on `DataLoader` see [their documentation](data-loaders.md).

### Apply filters on the original image

Now, that we fetched an image, we can alter the image in any way. You can create a resized version, a thumbnail, add a watermark, convert it to gray-scale, resample the image, change its resolution .. you get the idea.
Any alteration is called a `Filter`, derived from the naming within the Imagine library.

The responsibility of applying such a filter as bound to a `FilterLoader`, which are typically managed by the `FilterManager`. Those `FilterLoader` implement the `Liip\ImagineBundle\Imagine\Filter\Loader\LoaderInterface`.
The `FilterManager` is aware of so-called `filter_sets`. A filter set may define multiple filters to be applied on the result of each predecessor.

The filter has one objective: Apply itself on the provided image (loaded by the `DataLoader`).
It receives options to configure the actual result of it, to customize the outcome.

For more details on `FilterLoader` see [the documentation about filters](filters.md).

### Cache the filtered image

The filtered - to be cached - image is the image which results after applying all filters within a filter set.

In order to not apply each filter again on the same image, which will by most means result in the same filtered image, this result will be cached.
This caching is managed by the `CacheManager` which manages all so-called `CacheResolver`.

The default `CacheResolver` is the `WebPathResolver`, which will cache the image in the web directory as a static file, so the web server won't call the application stack anymore on those images.
The images will be created upon first request and will remain in their static cached version until removed.

A `CacheResolver` implements the `Liip\ImagineBundle\Imagine\Cache\Resolver\ResolverInterface`.

It handles the so-called `path`, which is the identifier you use, when addressing the original image, e.g. in your template. This path relates to the path used in the `DataLoader`.

The responsibilities of the `CacheResolver` are:

1. to resolve a given `path` into a `Response`, if possible,
2. store given content under a given `path` to be resolved later,
3. generate an URI to address the cached image directly,
4. remove a cached image.

For more details on `CacheResolver` see [the documentation about them](cache-resolvers.md).

[Back to the index](index.md)