README

此包为Symfony2提供易于使用的图像处理支持。例如，使用此包，可以进行以下操作

<img src="{{ '/relative/path/to/image.jpg' | apply_filter('thumbnail') }}" />

这将执行名为thumbnail的转换，您可以定义它执行多种不同的操作，如调整大小、裁剪、绘图、遮罩等。

此包集成了独立的PHP "Imagine库"。

安装

安装是一个简单的3步过程

使用Composer下载AvalancheImagineBundle
启用Bundle
配置您的应用配置文件config.yml

步骤1：使用Composer下载AvalancheImagineBundle

在您的composer.json中添加AvalancheImagineBundle

{
    "require": {
        "avalanche123/imagine-bundle": "v2.1"
    }
}

现在运行以下命令让Composer下载包

$ php composer.phar update avalanche123/imagine-bundle

Composer会将包安装到项目的vendor/avalanche123/imagine-bundle目录。

步骤2：启用Bundle

在kernel中启用Bundle

<?php
// app/AppKernel.php

public function registerBundles()
{
    $bundles = array(
        // ...
        new Avalanche\Bundle\ImagineBundle\AvalancheImagineBundle(),
    );
}

步骤3：注册Bundle的路由

最后，将以下内容添加到您的路由文件中

# app/config/routing.yml

_imagine:
    resource: .
    type:     imagine

恭喜！您已经准备好摇滚您的图像了！

基本用法

此包通过配置一系列过滤器并将这些过滤器应用于模板中的图像来工作。因此，首先创建您需要在应用中某处应用的过滤器。例如，假设您想将图像缩略到120x90像素大小

# app/config/config.yml

avalanche_imagine:
    filters:
        my_thumb:
            type:    thumbnail
            options: { size: [120, 90], mode: outbound }

您还可以更改保存图像时使用的质量和格式

# app/config/config.yml

avalanche_imagine:
    filters:
        my_thumb:
            type:    thumbnail
            options: { size: [120, 90], mode: outbound, quality: 100, format: png }

您现在已定义了一个名为my_thumb的过滤器，该过滤器执行缩略转换。我们将在稍后学习可用的转换，但到目前为止，这个新过滤器可以立即在模板中使用

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

或者如果您使用PHP模板

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

幕后，该包在第一次请求时将过滤器应用于图像，并将图像缓存到类似路径。在下一次请求时，缓存的图像将直接从文件系统提供服务。

在此示例中，最终渲染的路径可能类似于/media/cache/my_thumb/relative/path/to/image.jpg。这是Imagine将保存过滤后的图像文件的地方。

HTTP缓存头

cache_type - 三个值之一：false、public或private。将false设置为禁用缓存，即设置Cache-Control: no-cache。

默认：false
cache_expires - 设置缓存过期的时间。使用DateTime解析器理解的格式。表达式将以前缀+开头，因此表达式应类似于2 weeks。仅在cache_type等于public或private时使用。

默认：1 day

配置示例

# app/config/config.yml

avalanche_imagine:
    filters:
        my_thumb:
            type:    thumbnail
            options: { size: [120, 90], mode: outbound, cache_type: public, cache_expires: 2 weeks }

缓存头只在生成图像时设置一次。为了解决这个问题，您应该为您的Web服务器添加额外的配置。以下为Apache Web服务器的示例

<IfModule mod_expires.c>
    <Directory "/path/to/web/media/cache">
        ExpiresActive On
        ExpiresDefault "access plus 2 weeks"
    </Directory>
</IfModule>

配置

此包的默认配置看起来如下

avalanche_imagine:
    source_root:  %kernel.root_dir%/../web
    web_root:     %kernel.root_dir%/../web
    cache_prefix: media/cache
    driver:       gd
    filters:      []

有多个配置选项可供选择

source_root - 可以设置为原始图像目录的绝对路径。此选项允许您将原始图像存储在Web根目录之外的不同位置。在此根目录下，将按照在apply_filter模板过滤器中指定的相同相对路径搜索图像。

默认：%kernel.root_dir%/../web
web_root - 必须是应用程序的根目录的绝对路径。这用于确定生成图像文件的位置，以便 Apache 在下次请求时能够先抓取它们，然后再将请求交给 Symfony2。

默认：%kernel.root_dir%/../web
cache_prefix - 这也用于图像生成的路径，以避免将缓存图像散布在您的 web 根目录中。例如，默认情况下，图像将被写入 web/media/cache/ 目录。

默认: media/cache
driver - 三个驱动器之一：gd、imagick、gmagick

默认: gd
filters - 指定您想要定义和使用哪些过滤器

您指定的每个过滤器都有以下选项

type - 确定要使用的过滤器类型，有关更多信息，请参阅 过滤器 部分
options - 应传递给特定过滤器类型的选项
path - 覆盖全局 cache_prefix 并用此路径替换它

内置过滤器

目前，此捆绑包仅提供一种内置过滤器：thumbnail。

缩略图

如名称所示，thumbnail 过滤器会对您的图像执行缩略图转换。配置如下

filters:
    my_thumb:
        type:    thumbnail
        options: { size: [120, 90], mode: outbound }

mode 可以是 outbound 或 inset。

调整大小

resize 过滤器可以用来简单地改变图像的宽度和高度，而不考虑其比例。

以下是一个配置示例，它定义了两个过滤器，将图像调整为确切的屏幕分辨率

avalanche_imagine:
    filters:
        cga:
            type:    resize
            options: { size: [320, 200] }
        wuxga:
            type:    resize
            options: { size: [1920, 1200] }

相对调整大小

relative_resize 过滤器可以用来 heighten、widen、increase 或 scale 图像，相对于其现有尺寸。这些选项直接对应于 Imagine 的 BoxInterface 上的方法。

给定一个大小为 50x40（宽度，高度）的输入图像，考虑以下带注释的配置示例

avalanche_imagine:
    filters:
        heighten:
            type:    relative_resize
            options: { heighten: 60 } # Transforms 50x40 to 75x60
        widen:
            type:    relative_resize
            options: { widen: 32 }    # Transforms 50x40 to 40x32
        increase:
            type:    relative_resize
            options: { increase: 10 } # Transforms 50x40 to 60x50
        scale:
            type:    relative_resize
            options: { scale: 2.5 }   # Transforms 50x40 to 125x100

如果您喜欢在没有过滤器配置的情况下使用 Imagine，可以直接使用 RelativeResize 类。

粘贴

paste 过滤器可以将图像粘贴到您的图像中。

avalanche_imagine:
    filters:
        paste:
            type:        paste
            options:
                image:   %kernel.root_dir%/Resources/image.png  # path to image
                x:       right                                  # [left|right|center] or integer
                y:       bottom                                 # [top|bottom|middle] or integer

链式

使用 chain 过滤器可以在您的图像上应用一些过滤器。您可以非常简单地创建一个 watermark 过滤器

avalanche_imagine:
    filters:
        watermark:
            type:                chain
            options:
                filters:
                    thumbnail:                                          # filter type
                        size:    [100, 100]                             # filter options
                        mode:    outbound
                    paste:
                        image:   %kernel.root_dir%/Resources/image.png
                        x:       right
                        y:       bottom

加载您的自定义过滤器

ImagineBundle 允许您加载自己的自定义过滤器类。唯一的要求是每个过滤器加载器实现以下接口

Avalanche\Bundle\ImagineBundle\Imagine\Filter\Loader\LoaderInterface

要告知捆绑包关于您的新过滤器加载器，将其注册到服务容器中，并应用以下标签（以下为 XML 中的示例）

<tag name="imagine.filter.loader" filter="my_custom_filter" />

有关服务容器的更多信息，请参阅 Symfony2 服务容器文档。

现在您可以在定义要应用的配置中的过滤器时引用和使用您的自定义过滤器

filters:
    my_special_filter:
        type:    my_custom_filter
        options: { }

有关过滤器加载器实现的示例，请参阅 Avalanche\Bundle\ImagineBundle\Imagine\Filter\Loader\ThumbnailFilterLoader。

注意事项

如果您在 Twig 模板中从多个部分生成图像名称，请注意，Twig 在连接之前应用过滤器之前，因此

<img src="{{ '/relative/path/to/' ~ some_variable ~ '.jpg' | apply_filter('my_thumb') }}" />

将应用过滤器到 '.jpg'，然后将结果连接到 '/relative/path/to/' 和 some_variable。因此，正确的调用方式应该是

<img src="{{ ('/relative/path/to/' ~ some_variable ~ '.jpg') | apply_filter('my_thumb') }}" />

作为服务使用

您还可以将 ImagineBundle 作为服务使用，并在控制器中创建缓存图像。

$avalancheService = $this->get('imagine.cache.path.resolver');

然后，调用 getBrowserPath 并传递原始图像的 web 路径和您想要使用的过滤器

$cachedImage = $avalancheService->getBrowserPath($object->getWebPath(), 'my_thumb');

socloz / imagine-bundle

维护者

详细信息