基本用法

编辑此页

通常，此扩展包通过将过滤器集应用于模板内部的图像来工作。您的过滤器集在应用程序的配置文件（通常是 app/config/config.yml）中定义，并且由过滤器、后处理器和其他可选参数的集合组成。

我们稍后将了解更多关于后处理器和其他可用参数的信息，但现在让我们关注如何定义一个由几个过滤器组成的小型过滤器集。

创建缩略图

在我们开始之前，需要少量配置以确保我们的数据加载器和缓存解析器正常运行。使用以下配置样板。

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
        # app/config/config.yml

liip_imagine:

    # configure resolvers
    resolvers:

        # setup the default resolver
        default:

            # use the default web path
            web_path: ~

    # your filter sets are defined here
    filter_sets:

        # use the default cache configuration
        cache: ~
    

有了基本配置，我们将从一个满足常见用例的示例开始：创建缩略图。假设我们希望将以下转换应用于生成的缩略图

缩放和裁剪图像到 120x90 像素。
向缩放后的图像添加 2 像素黑色边框。
将图像质量调整为 75。

在我们上面的样板基础上，我们需要定义一个过滤器集（我们将其命名为 my_thumb），其中配置了两个过滤器：thumbnail 和 background 过滤器。

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
        # app/config/config.yml

liip_imagine:
    resolvers:
        default:
            web_path: ~

    filter_sets:
        cache: ~

        # the name of the "filter set"
        my_thumb:

            # adjust the image quality to 75%
            quality: 75

            # list of transformations to apply (the "filters")
            filters:

                # create a thumbnail: set size to 120x90 and use the "outbound" mode
                # to crop the image when the size ratio of the input differs
                thumbnail: { size: [120, 90], mode: outbound }

                # create a 2px black border: center the thumbnail on a black background
                # 4px larger to create a 2px border around the final image
                background: { size: [124, 94], position: center, color: '#000000' }
    

您现在创建了一个名为 my_thumb 的过滤器集，它执行缩略图转换。thumbnail 过滤器将图像大小调整为所需的宽度和高度（120x90 像素），并且它的 mode: outbound 选项使生成的图像在输入比例不同时被裁剪。background 过滤器通过创建一个 124x94 像素大小的黑色画布并将缩略图定位在其中心，从而产生 2 像素黑色边框。

注意

一个过滤器集可以为其定义任意数量的过滤器。简单的转换可能只需要一个过滤器，而更复杂的转换可以为其定义任意数量的过滤器。

还有许多其他的过滤器，但现在您可以立即在模板中使用新定义的 my_thumb 过滤器集。

        1
        <img src="{{ asset('/relative/path/to/image.jpg') | imagine_filter('my_thumb') }}" />
    

在幕后，当第一个页面请求被服务时，扩展包会将过滤器应用于图像。然后，转换后的图像将被缓存以供后续请求使用。最终缓存的图像路径将类似于 /media/cache/my_thumb/relative/path/to/image.jpg。

提示

您可以预先准备缓存，可以使用命令或消息队列，或者使用 Web 服务器配置处理丢失的文件。当您这样做时，您可以使用 imagine_filter_cache 过滤器来始终返回最终缓存图像的链接。

注意

当您使用 asset 函数来解析图像路径并配置了 asset 版本控制时，imagine_filter 尝试处理版本查询字符串。有关更多信息，请参阅 asset 版本控制。

注意

在使用 dev 环境时，您可能会发现图像未通过模板助手正确呈现。这通常是由于在您的应用程序配置中启用了 intercept_redirect。为了确保图像被呈现，强烈建议禁用此选项

        1
2
3
4
        # app/config/config_dev.yml

web_profiler:
    intercept_redirects: false
    

运行时选项

有时，您可能定义了一个过滤器，它可以满足您 99% 的使用场景。您可以选择在运行时通过向模板助手传递选项数组来更改过滤器的行为，而不是为错误的 1% 的情况定义新过滤器。

        1
2
3
        {% set runtimeConfig = {"thumbnail": {"size": [50, 50] }} %}

<img src="{{ asset('/relative/path/to/image.jpg') | imagine_filter('my_thumb', runtimeConfig) }}" />
    

路径解析

有时您需要解析此扩展包为过滤后的图像返回的图像路径。这可以使用 Symfony 的控制台二进制文件或以编程方式从控制器或其他代码片段中实现。

使用控制台解析

您可以使用控制台命令 liip:imagine:cache:resolve 解析图像 URL。唯一必需的参数是一个或多个相对图像路径（必须用空格分隔）。

        1
        $ php bin/console liip:imagine:cache:resolve relative/path/to/image1.jpg relative/path/to/image2.jpg
    

此外，您可以使用 --filters 选项来指定您要解析的过滤器（如果省略 --filters 选项，将解析所有可用的过滤器）。

        1
        $ php bin/console liip:imagine:cache:resolve relative/path/to/image1.jpg --filters=my_thumb
    

以编程方式解析

您可以使用 Liip\ImagineBundle\Imagine\Cache\CacheManager 服务的 getBrowserPath 方法在代码中解析图像 URL。假设您已将该服务分配给名为 $imagineCacheManager 的变量，您将运行

        1
        $imagineCacheManager->getBrowserPath('/relative/path/to/image.jpg', 'my_thumb');
    

通常，您需要在控制器中执行此操作。

在控制器中，这可以如下所示

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
        <?php

namespace App\Controller;

use Liip\ImagineBundle\Imagine\Cache\CacheManager;

class YourController
{
    public function yourControllerMethod(CacheManager $imagineCacheManager)
    {
        /** @var string */
        $resolvedPath = $imagineCacheManager->getBrowserPath('/relative/path/to/image.jpg', 'my_thumb');

        // ...
    }
}
    

WebP 图片格式

与 JPEG 和 PNG 相比，WebP 格式更好地优化了压缩图像的质量和大小。Google 强烈建议使用此格式。

所有都使用 WebP

如果您可以忽略不支持 WebP 格式的旧浏览器，那么您可以配置以 WebP 格式生成所有图像。

        1
2
3
4
5
        # app/config/config.yml

liip_imagine:
    default_filter_set_settings:
        format: webp
    

如果支持则使用 WebP

但是，并非所有浏览器都支持 WebP 格式，为了与所有浏览器兼容，建议对于不支持 WebP 的浏览器，以其原始格式返回图像。这意味着您需要存储 2 个版本的图像。一个 WebP 格式，另一个原始格式。请记住，这几乎使服务器上用于存储过滤图像的空间量翻倍。

        1
2
3
4
5
6
7
8
9
10
11
12
        # app/config/config.yml

liip_imagine:
    # configure webp
    webp:
        generate: true

    # example filter
    filter_sets:
        thumbnail_web_path:
            filters:
                thumbnail: { size: [223, 223], mode: inset }
    

如果浏览器支持 WebP，则请求 https://127.0.0.1/media/cache/resolve/thumbnail_web_path/images/cats.jpeg 将重定向到 https://127.0.0.1/media/cache/thumbnail_web_path/images/cats.jpeg.webp，否则重定向到 https://127.0.0.1/media/cache/thumbnail_web_path/images/cats.jpeg

优化防火墙配置

对于大多数应用程序，对过滤器控制器（/media/cache/resolve 路径）的请求不需要 Symfony 从会话加载经过身份验证的用户数据。为了优化性能，您可以通过使用以下代码片段为这些控制器定义防火墙来禁用身份验证系统

        1
2
3
4
5
6
7
        # app/config/security.yml

security:
    firewalls:
        image_resolver:
            pattern: ^/media/cache/resolve
            security: false
    

注意

在您的网站上使用不安全的连接（非 HTTPS）可能会导致缓存用户的已解析路径出现问题，这可能会导致浏览器不支持 WebP 的用户收到 WebP 格式的图片。您可以通过将重定向代码从 301 (永久移动) 更改为 302 (临时移动) 来解决此问题。

        1
2
3
4
5
        # app/config/config.yml

liip_imagine:
    controller:
        redirect_response_code: 302
    

客户端解析

为了获得更好的性能，您可以使用 <picture> 标签在浏览器中的客户端解析支持的图像格式。这将使 HTML 代码复杂化，并且需要注册两个相同的过滤器，以生成不同格式的图像。

        1
2
3
4
5
6
7
8
9
10
11
12
13
14
        # app/config/config.yml

liip_imagine:
    filter_sets:
        my_thumb_jpeg:
            format: jpeg
            quality: 80
            filters:
                thumbnail: { size: [223, 223], mode: inset }
        my_thumb_webp:
            format: webp
            quality: 100
            filters:
                thumbnail: { size: [223, 223], mode: inset }
    

        1
2
3
4
5
        <picture>
  <source srcset="{{ '/relative/path/to/image.jpg' | imagine_filter('my_thumb_webp') }}" type="image/webp">
  <source srcset="{{ '/relative/path/to/image.jpg' | imagine_filter('my_thumb_jpeg') }}" type="image/jpeg">
  <img src="{{ '/relative/path/to/image.jpg' | imagine_filter('my_thumb_jpeg') }}" alt="Alt Text!">
</picture>
    

这项工作，包括代码示例，根据 Creative Commons BY-SA 3.0 许可协议获得许可。

版本