README

注意：这是一个简单的原始仓库分支，唯一的不同之处在于这个扩展包生成的是相对URL而不是绝对URL。（原始扩展包不提供这种选项）。

欢迎提出PR来使它更动态。

LiipImagineBundle

Travis-CI	Style-CI	覆盖率	下载	发布

此扩展包为基于 Symfony 的项目提供了一个图像处理抽象工具包。

概述

过滤器集：使用任何Symfony支持的配置语言（如YML和XML），可以创建指定转换过程的过滤器集定义。这些定义包括一组过滤器和后处理器，以及其他可选参数。
过滤器：通过过滤器应用图像转换。该扩展包提供了一组内置过滤器，实现了最常见的转换；例如，缩略图、缩放、裁剪、翻转、去除和水印。对于更高级的转换，可以轻松创建自己的自定义过滤器。
后处理器：对由过滤器生成的结果二进制图像文件（例如，JPEG）的修改由后处理器处理。例如，包括JPEG Optim、Moz JPEG、Opti PNG和PNG Quant。就像过滤器一样，可以轻松创建自己的自定义后处理器。

示例

假设您定义了一个名为my_thumb的过滤器集，可以配置以执行任何数量的不同转换。最简单的调用是将图像路径传递给提供的imagine_filter Twig过滤器。

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

归属

感谢众多贡献者投入时间和代码到这个项目中。
这个包使用了独立的PHP Imagine Library 来进行图像转换。
该包是从AvalancheImagineBundle 分支出来的，旨在使代码更加可扩展。有关分叉的理由，请参考 AvalancheImagineBundle#25。

设置

安装

使用这个包与所有Symfony包类似。必须执行以下步骤

详细的安装说明可以在文档的安装章节中找到。

配置

有关所有可用配置选项的详细信息，请参阅文档的配置章节。

使用指南

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

我们将在以后学习更多关于后处理器和其他可用参数的内容，但在此我们先关注如何定义一个简单的由几个过滤器组成的过滤器集。

创建缩略图

在开始之前，我们需要进行一些小的配置，以确保我们的数据加载器和缓存解析器能够正确运行。在您的配置文件中使用以下模板。

# 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 过滤器。

# 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 过滤器集。

对于基于Twig的模板，使用

<img src="{{ asset('/relative/path/to/image.jpg') | imagine_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。

注意： *在dev环境中，您可能会发现模板助手无法正确渲染图像。这通常是由于在应用程序配置中启用了intercept_redirect。为了确保图像被渲染，强烈建议禁用此选项

# app/config/config_dev.yml

web_profiler :
    intercept_redirects : false

运行时选项

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

对于基于Twig的模板，使用

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

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

或者，对于基于PHP的模板，使用

<?php
$runtimeConfig = array(
    "thumbnail" => array(
        "size" => array(50, 50)
    )
);
?>

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

路径解析

有时您需要解析此组件返回的过滤图像的图像路径。这可以通过使用Symfony的console二进制文件或从控制器或其他代码中程序化地轻松实现。

使用控制台解析

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

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

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

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

程序化解析

您可以使用liip_imagine.cache.manager服务的getBrowserPath方法在您的代码中解析图像URL。假设您已经将服务分配给一个名为$imagineCacheManager的变量，您将执行

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

通常，您需要在控制器中执行此操作。假设您的控制器继承自基础Symfony控制器，您可以利用继承的get方法来请求liip_imagine.cache.manager服务，然后可以在相对图像路径上调用getBrowserPath以获取其解析位置。

/** @var CacheManager */
$imagineCacheManager = $this->get('liip_imagine.cache.manager');

/** @var string */
$resolvedPath = $imagineCacheManager->getBrowserPath('/relative/path/to/image.jpg', 'my_thumb');

过滤器

此组件提供了一套内置过滤器，并且您可以轻松定义自己的过滤器。请参阅我们的文档中的过滤器章节。

作为服务使用

如果您需要在控制器中使用您定义的“过滤器集”，您可以从服务容器中获取此组件的控制器并自行处理响应。

<?php

class MyController extends Controller
{
    public function indexAction()
    {
        /** @var ImagineController */
        $imagine = $this
            ->container
            ->get('liip_imagine.controller');

        /** @var RedirectResponse */
        $imagemanagerResponse = $imagine
            ->filterAction(
                $this->request,         // http request
                'uploads/foo.jpg',      // original image you want to apply a filter to
                'my_thumb'              // filter defined in config.yml
            );

        /** @var CacheManager */
        $cacheManager = $this
            ->container
            ->get('liip_imagine.cache.manager');

        /** @var string */
        $sourcePath = $cacheManager
            ->getBrowserPath(
                'uploads/foo.jpg',
                'my_thumb'
            );

        // ..
    }
}

?>

如果您需要添加更多逻辑，建议的解决方案是扩展ImagineController.php或将其用作您自己实现的依据。

要使用控制器在其他服务中，您必须模拟一个新的请求。

<?php

/** @var ImagineController */
$imagine = $this
    ->container
    ->get('liip_imagine.controller');

/** @var Response */
$response = $imagine
    ->filterAction(
        new Symfony\Component\HttpFoundation\Request(),
        'uploads/foo.jpg',
        'my_thumb'
    );

?>

数据根

默认情况下，Symfony的web/目录被注册为数据根，用于加载资源。对于许多安装，这将是足够的，但有时您可能需要从其他位置加载图片。为此，您必须在配置中设置data_root参数（通常位于app/config/config.yml）。

liip_imagine:
    loaders:
        default:
            filesystem:
                data_root: /path/to/source/images/dir

从版本1.7.2开始，您可以注册多个数据根路径，文件定位器将在每个路径中搜索请求的文件。

liip_imagine:
    loaders:
        default:
            filesystem:
                data_root:
                    - /path/foo
                    - /path/bar

从版本1.7.3开始，您可以要求从所有注册的包中自动注册公共资源路径。这允许您从位于加载的包内的Resources/public文件夹加载资源。要启用此功能，将bundle_resources.enabled配置选项设置为true。

liip_imagine:
    loaders:
        default:
            filesystem:
                bundle_resources:
                    enabled: true

如果您只想注册一些Resource/public文件夹，而不是所有文件夹，可以通过黑名单不注册的包或白名单您想要注册的包来实现。例如，要黑名单（不注册）“FooBundle”和“BarBundle”包，您可以使用以下配置。

liip_imagine:
    loaders:
        default:
            filesystem:
                bundle_resources:
                    enabled: true
                    access_control_type: blacklist
                    access_control_list:
                        - FooBundle
                        - BarBundle

或者，如果您只想白名单（仅注册）“FooBundle”和“BarBundle”包，您可以使用以下配置。

liip_imagine:
    loaders:
        default:
            filesystem:
                bundle_resources:
                    enabled: true
                    access_control_type: whitelist
                    access_control_list:
                        - FooBundle
                        - BarBundle

权限

图片位置必须可由您的Web服务器读取。在支持setfacl的系统（如Linux/BSD）上，使用

HTTPDUSER=`ps axo user,comm | grep -E '[a]pache|[h]ttpd|[_]www|[w]ww-data|[n]ginx' | grep -v root | head -1 | cut -d\  -f1`

sudo setfacl -R -m u:"$HTTPDUSER":rwX -m u:`whoami`:rwX /path/to/source/images/dir

sudo setfacl -dR -m u:"$HTTPDUSER":rwX -m u:`whoami`:rwX /path/to/source/images/dir

有关与macOS和其他环境兼容的命令，请参阅Symfony权限文档。

使用Apache

您需要通过向Apache VHost配置中添加以下内容来授予Apache的读取权限

<VirtualHost *:80>
    <!-- Rest of directives like DocumentRoot or ServerName -->

    Alias /FavouriteAlias /path/to/source/images/dir
    <Directory "/path/to/source/images/dir">
        AllowOverride None
        Allow from All
    </Directory>
</VirtualHost>

或者，您可以将指令放置在项目中的一个单独文件中，并将其包含在Apache VHost配置中。例如，您可以创建文件app/config/apache/photos.xml并在VHost文件中添加以下内容

<VirtualHost *:80>
    <!-- Rest of directives like DocumentRoot or ServerName -->

    Include "/path/to/your/project/app/config/apache/photos.xml"
</VirtualHost>

此方法将文件与您的其他代码一起保留，允许您轻松更改它或创建不同环境相关的配置文件。

一旦正确配置了Apache，具有以下绝对路径的图像的相对路径/path/to/source/images/dir/logo.png必须是/FavouriteAlias/logo.png。

文档

有关此包功能的更多信息，请参阅文档。

erdou / imagine-bundle

维护者

详细信息