Resolve cache images in background
==================================

Overview
--------

By default the LiipImagineBundle processes the image on demand.
It does in resolve controller and saves the result, does a 301 redirect to the processed static image.
The approach has its benefits.
The most notable is simplicity.
Though there are some disadvantages:

* It takes huge amount of time during the first request since we have to do a lot of things.
* The images are processed by web servers. It increases the overall load on them and may affect the site performance.
* The resolve controller url is different from the cached image one.
  If there is nothing in the cache the page will contain the url to resolve controller.
  The varnish may cache the page with those links to the resolve controller.
  A browser keeps sending requests to it though there is no need for it after the first call.

The bundle provides a solution. It utilize messaging pattern and works on top of `enqueue library`_.

Step 1: Install EnqueueBundle
-----------------------------

First, we have to `install EnqueueBundle`_. You have to basically use composer to install the bundle,
register it to AppKernel and adjust settings. Here's the most simplest configuration without any extra dependencies.
It is based on `filesystem transport`_.

.. code-block:: yaml

    # app/config/config.yml

    enqueue:
        transport:
            # you could set other available transports
            default: 'file://%kernel.root_dir%/../var/enqueue'
        client: ~

Step 2: Configure LiipImagineBundle
-----------------------------------

At this step we instruct LiipImagineBundle to load some extra stuff required to process images in background.

.. code-block:: yaml

    # app/config/config.yml

    liip_imagine:
        enqueue: true

Step 3: Run consumers
---------------------

Before we can start using it we need a pool of consumers (at least one) to be working in background.
Here's how you can run it:

.. code-block:: bash

    $ ./app/console enqueue:consume --setup-broker -vvv

Step 4: Send resolve cache message
----------------------------------

You have to send a message in order to process images in background.
The message must contain the original image path (in terms of LiipImagineBundle).
If you do not define filters the background process will resolve cache for all available filters.
If the cache already exist the background process does recreate it by default
You can force cache to be recreated and in this case the cached image is removed and a new one replaces it.

.. code-block:: php

    <?php

    use Enqueue\Client\ProducerInterface;
    use Liip\ImagineBundle\Async\Topics;
    use Liip\ImagineBundle\Async\ResolveCache;
    use Symfony\Component\DependencyInjection\ContainerInterface;

    /**
     * @var ContainerInterface $container
     * @var ProducerInterface $producer
     */
    $producer = $container->get('enqueue.producer');

    // resolve all caches
    $producer->send(Topics::RESOLVE_CACHE, new ResolveCache('the/path/img.png'));

    // resolve specific cache
    $producer->send(Topics::RESOLVE_CACHE, new ResolveCache('the/path/img.png', array('fooFilter')));

    // force resolve (removes the cache if exists)
    $producer->send(Topics::RESOLVE_CACHE, new ResolveCache('the/path/img.png', null, true));


.. _`enqueue library`: https://github.com/php-enqueue/enqueue-dev
.. _`install EnqueueBundle`: https://github.com/php-enqueue/enqueue-dev/blob/master/docs/bundle/quick_tour.md
.. _`filesystem transport`: https://github.com/php-enqueue/enqueue-dev/blob/master/docs/transport/filesystem.md