Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Misc. fixes and improvements to the docs #667

Merged
merged 1 commit into from
Nov 26, 2015
Merged

Misc. fixes and improvements to the docs #667

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 13 additions & 13 deletions Resources/doc/basic-usage.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,11 +21,11 @@ you want to thumbnail an image to a size of 120x90 pixels:
filters:
thumbnail: { size: [120, 90], mode: outbound }

You've now defined a filter set called `my_thumb` that performs a thumbnail
transformation. We'll learn more about available transformations later, but
You've now defined a filter set called ``my_thumb`` that performs a thumbnail
transformation. We'll learn more about available transformations later, but
for now, this new filter can be used immediately in a template:

.. configuration-block:
.. configuration-block::

.. code-block:: html+jinja

Expand All @@ -35,17 +35,17 @@ for now, this new filter can be used immediately in a template:

<img src="<?php echo $this['imagine']->filter('/relative/path/to/image.jpg', 'my_thumb') ?>" />

Behind the scenes, the bundles applies the filter(s) to the image on the
Behind the scenes, the bundles applies the filter(s) to the image on the
first request and then caches the image to a similar path. On the next request,
the cached image would be served directly from the file system.

In this example, the final rendered path would be something like
`/media/cache/my_thumb/relative/path/to/image.jpg`. This is where Imagine
``/media/cache/my_thumb/relative/path/to/image.jpg``. This is where Imagine
would save the filtered image file.

You can also pass some options at runtime:

.. configuration-block:
.. configuration-block::

.. code-block:: html+jinja

Expand Down Expand Up @@ -76,21 +76,21 @@ omit filters option will be applied all available filters.
If you need to access filtered image URL in your controller:

.. code-block:: php

$this->get('liip_imagine.cache.manager')->getBrowserPath('/relative/path/to/image.jpg', 'my_thumb', true),

In this case, the final rendered path would contain some random data in the
path ``/media/cache/my_thumb/S8rrlhhQ/relative/path/to/image.jpg``. This is where
In this case, the final rendered path would contain some random data in the
path ``/media/cache/my_thumb/S8rrlhhQ/relative/path/to/image.jpg``. This is where
Imagine would save the filtered image file.

.. note::

Using the ``dev`` environment you might find that the images are not properly
rendered when using the template helper. This is likely caused by having
``intercept_redirect`` enabled in your application configuration. To ensure
Using the ``dev`` environment you might find that the images are not properly
rendered when using the template helper. This is likely caused by having
``intercept_redirect`` enabled in your application configuration. To ensure
that the images are rendered disable this option:

.. code-block:: yaml

web_profiler:
intercept_redirects: false
108 changes: 71 additions & 37 deletions Resources/doc/filters.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ Built-in Filters
----------------

The ``thumbnail`` filter
~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~

The thumbnail filter, as the name implies, performs a thumbnail transformation
on your image.
Expand All @@ -24,10 +24,12 @@ annotated configuration examples:
filter_sets:
my_thumb_out:
filters:
thumbnail: { size: [32, 32], mode: outbound } # Transforms 50x40 to 32x32, while cropping the width
# Transforms 50x40 to 32x32, while cropping the width
thumbnail: { size: [32, 32], mode: outbound }
my_thumb_in:
filters:
thumbnail: { size: [32, 32], mode: inset } # Transforms 50x40 to 32x26, no cropping
# Transforms 50x40 to 32x26, no cropping
thumbnail: { size: [32, 32], mode: inset }


There is also an option ``allow_upscale`` (default: ``false``). By setting
Expand Down Expand Up @@ -67,8 +69,8 @@ annotated configuration examples:
The ``upscale`` filter
~~~~~~~~~~~~~~~~~~~~~~

The upscale filter, as the name implies, performs a upscale transformation
on your image. Configuration looks like this:
It performs an upscale transformation on your image to increase its size to the
given dimensions:

.. code-block:: yaml

Expand All @@ -79,10 +81,10 @@ on your image. Configuration looks like this:
upscale: { min: [800, 600] }

The ``downscale`` filter
~~~~~~~~~~~~~~~~~~~~~~
~~~~~~~~~~~~~~~~~~~~~~~~

The downscale filter, as the name implies, performs a downscale transformation
on your image. Configuration looks like this:
It performs a downscale transformation on your image to reduce its size to the
given dimensions:

.. code-block:: yaml

Expand All @@ -95,8 +97,11 @@ on your image. Configuration looks like this:
The ``crop`` filter
~~~~~~~~~~~~~~~~~~~

The crop filter, as the name implies, performs a crop transformation on your
image. Configuration looks like this:
It performs a crop transformation on your image. The ``start`` option defines
the coordinates of the left-top pixel where the crop begins (the ``[0, 0]``
coordinates correspond to the top leftmost pixel of the original image). The
``size`` option defines in pixels the width and height (in this order) of the
area cropped:

.. code-block:: yaml

Expand All @@ -109,8 +114,9 @@ image. Configuration looks like this:
The ``strip`` filter
~~~~~~~~~~~~~~~~~~~~

The strip filter removes all profiles and comments from your image.
Configuration looks like this:
It removes all profiles and comments from your image to reduce its file size
without degrading its quality. This filter provides no configuration options,
so you just need to enable it as follows:

.. code-block:: yaml

Expand All @@ -123,8 +129,7 @@ Configuration looks like this:
The ``background`` filter
~~~~~~~~~~~~~~~~~~~~~~~~~

The background filter sets a background color for your image, default is white
(#FFF). Configuration looks like this:
It sets a background color for the image. The default color is white (``#FFF``):

.. code-block:: yaml

Expand All @@ -134,8 +139,9 @@ The background filter sets a background color for your image, default is white
filters:
background: { color: '#00FFFF' }

If you provide a ``size`` it will create a new image (this size and given
color), and apply the original image on top:
By default, the background color is only visible through the transparent sections
of the image (if any). However, if you provide a ``size`` option, a new image is
created (with the given size and color) and the original image is placed on top:

.. code-block:: yaml

Expand Down Expand Up @@ -174,8 +180,10 @@ ratio. Configuration looks like this:
The ``auto_rotate`` filter
~~~~~~~~~~~~~~~~~~~~~~~~~~

The auto_rotate filter rotates the image based on its EXIF data. **(this filter
should be called as early as possible)** Configuration looks like this:
It rotates the image automatically to display it as correctly as possible. The
rotation to apply is obtained through the metadata stored in the EXIF data of
the original image. This filter provides no configuration options, so you just
need to enable it as follows:

.. code-block:: yaml

Expand All @@ -185,11 +193,15 @@ should be called as early as possible)** Configuration looks like this:
filters:
auto_rotate: ~

.. note::

This filter should be called as early as possible to get better results.

The ``rotate`` filter
~~~~~~~~~~~~~~~~~~~~~

The rotate filter rotates the image based on specified angle (in degrees).
Configuration looks like this:
It rotates the image based on specified angle (in degrees). The value of the
``angle`` configuration option must be a positive integer or float number:

.. code-block:: yaml

Expand All @@ -202,7 +214,7 @@ Configuration looks like this:
The ``interlace`` filter
~~~~~~~~~~~~~~~~~~~~~~~~

Set progressive loading on the image. Configuration looks like this:
It modifies the way the image is loaded progressively:

.. code-block:: yaml

Expand All @@ -211,25 +223,36 @@ Set progressive loading on the image. Configuration looks like this:
my_thumb:
filters:
interlace:
# mode can be one of none,line,plane,partition
# mode can be one of: 'none', 'line', 'plane' and 'partition'
mode: line

Load your Custom Filters
------------------------

The ImagineBundle allows you to load your own custom filter classes. The only
requirement is that each filter loader implement the following interface:
requirement is that each filter loader implements the following interface:
``Liip\ImagineBundle\Imagine\Filter\Loader\LoaderInterface``.

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

.. code-block:: xml
.. contiguration-block::

<service id="liip_imagine.filter.loader.my_custom_filter" class="Acme\ImagineBundle\Imagine\Filter\Loader\MyCustomFilterLoader">
<tag name="liip_imagine.filter.loader" loader="my_custom_filter" />
</service>
.. code-block:: yaml

# app/config/services.yml
app.filter.my_custom_filter:
class: AppBundle\Imagine\Filter\Loader\MyCustomFilterLoader
tags:
- { name: 'liip_imagine.filter.loader', loader: 'my_custom_filter' }

.. code-block:: xml

<!-- app/config/services.xml -->
<service id="app.filter.my_custom_filter" class="AppBundle\Imagine\Filter\Loader\MyCustomFilterLoader">
<tag name="liip_imagine.filter.loader" loader="my_custom_filter" />
</service>

For more information on the service container, see the `Symfony Service Container`_
documentation.
Expand Down Expand Up @@ -282,28 +305,39 @@ A simple example showing how to change the filter configuration dynamically.

.. note::

The constant ``Response::HTTP_MOVED_PERMANENTLY`` was introduced in version 2.4. Developers using older versions of Symfony, please replace the constant by ``301``.
The constant ``Response::HTTP_MOVED_PERMANENTLY`` was introduced in Symfony 2.4.
Developers using older versions of Symfony, please replace the constant by ``301``.

Post-Processors
---------------

Filters allow modifying the image, but in order to modify the resulting binary
file created by filters, you can use post-processors Post-processors should
file created by filters, you can use post-processors. Post-processors must
implement ``Liip\ImagineBundle\Imagine\Filter\PostProcessor\PostProcessorInterface``.

``PostProcessorInterface::process`` method receives ``BinaryInterface`` -
basically, the file containing an image after all filters have been applied. It
should return the ``BinaryInterface`` as well.

To tell the bundle about your post-processor, register it in the service
container and apply the ``liip_imagine.filter.post_processor`` tag to it
(example here in XML):
container and apply the ``liip_imagine.filter.post_processor`` tag to it:

.. contiguration-block::

.. code-block:: yaml

# app/config/services.yml
app.post_processor.my_custom_post_processor:
class: AppBundle\Imagine\Filter\PostProcessor\MyCustomPostProcessor
tags:
- { name: 'liip_imagine.filter.post_processor', post_processor: 'my_custom_post_processor' }

.. code-block:: xml
.. code-block:: xml

<service id="liip_imagine.filter.post_processor.my_custom_post_processor" class="Acme\ImagineBundle\Imagine\Filter\PostProcessor\MyCustomPostProcessor">
<tag name="liip_imagine.filter.post_processor" post_processor="my_custom_post_processor" />
</service>
<!-- app/config/services.xml -->
<service id="app.post_processor.my_custom_post_processor" class="AppBundle\Imagine\Filter\PostProcessor\MyCustomPostProcessor">
<tag name="liip_imagine.filter.post_processor" post_processor="my_custom_post_processor" />
</service>

For more information on the service container, see the `Symfony Service Container`_
documentation.
Expand All @@ -322,9 +356,9 @@ like to apply in your configuration:
For an example of a post processor implementation, refer to
``Liip\ImagineBundle\Imagine\Filter\PostProcessor\JpegOptimPostProcessor``.

The ``JpegOptimPostProcessor`` can be used to provide lossless jpeg
The ``JpegOptimPostProcessor`` can be used to provide lossless JPEG
optimization, which is good for you website loading speed. In order to add
lossless jpeg optimization to your filters, use the following configuration:
lossless JPEG optimization to your filters, use the following configuration:

.. code-block:: yaml

Expand Down