LiipImagineBundleダウンロード - LiipImagineBundleソースコードのダウンロード

LiipImagineバンドル

PHPUユニット	PHP-CS-フィクサー	カバレッジ	ダウンロード	リリース

このバンドルは、Symfony ベースのプロジェクト用の画像操作抽象化ツールキットを提供します。

概要

フィルターセット: Symfony でサポートされている設定言語 (YML や XML など) を使用して、変換ルーチンを指定するフィルターセット定義を作成できます。これらの定義には、フィルターとポストプロセッサーのセット、およびその他のオプションのパラメーターが含まれます。
フィルター: 画像変換はフィルターを使用して適用されます。一連の組み込みフィルターがバンドルによって提供され、最も一般的な変換を実装します。例には、サムネイル、スケール、クロップ、フリップ、ストリップ、ウォーターマークなどがあります。さらに高度な変換を行うには、独自のカスタムフィルターを簡単に作成できます。
ポストプロセッサ: 結果として得られるバイナリイメージファイル (フィルタから作成された) の変更は、ポストプロセッサによって処理されます。例には、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 ) 内で定義され、 filter 、 post-processors 、およびその他のオプションのパラメーターのコレクションで構成されます。

ポストプロセッサーやその他の使用可能なパラメーターについては後ほど詳しく学習しますが、ここでは、いくつかのフィルターで構成される単純なフィルターセットを定義する方法に焦点を当てましょう。

サムネイルの作成

始める前に、データローダーとキャッシュリゾルバーが正しく動作することを確認するために、少量の設定が必要です。構成ファイルで次の定型文を使用します。

 # 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に調整します。

上記の定型文に追加して、 thumbnailフィルターとbackgroundフィルターという 2 つのフィルターが構成されたフィルターセット( my_thumbという名前にします) を定義する必要があります。

 # 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フィルターは、画像のサイズを希望の幅と高さ (この例では 120x90px) に設定し、そのmode: outboundオプションにより、入力比率が異なる場合に結果の画像がトリミングされます。 backgroundフィルターでは、サイズ 124x94 ピクセルの黒いキャンバスを作成し、サムネイルをその中心に配置することにより、2 ピクセルの黒い境界線が作成されます。

注:フィルタセットには、任意の数のフィルタを定義できます。単純な変換には 1 つのフィルターのみが必要ですが、複雑な変換には無制限の数のフィルターを定義できます。

追加のフィルターが多数ありますが、現時点では、新しく定義した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 のコンソールバイナリを使用するか、コントローラーまたは他のコード部分からプログラムで簡単に実現できます。

コンソールで解決する

コンソールコマンドliip:imagine:cache:resolve使用してイメージ URL を解決できます。唯一必要な引数は、1 つ以上の相対画像パス (スペースで区切る必要があります) です。

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

さらに、 --filterオプションを使用して、解決するフィルターを指定できます ( --filterオプションを省略すると、使用可能なすべてのフィルターが解決されます)。

$ php bin/console liip:imagine:cache:resolve relative/path/to/image1.jpg --filter=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 ' );

フィルター

このバンドルには一連の組み込みフィルターが提供されており、独自のフィルターを簡単に定義することもできます。ドキュメントのフィルターの章を参照してください。

サービスとして使用する

コントローラー内から定義した「フィルターセット」を使用する必要がある場合は、このバンドルの FilterService をサービスコンテナーから取得して、面倒な作業を行うことができます。

 <?php

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

        // 1) Simple filter, OR
        $ resourcePath = $ imagine -> getUrlOfFilteredImage ( ' uploads/foo.jpg ' , ' my_thumb ' );
        
        // 2) Runtime configuration
        $ runtimeConfig = [
            ' thumbnail ' => [
                ' size ' => [ 200 , 200 ]
            ],
        ];
        $ resourcePath = $ imagine -> getUrlOfFilteredImageWithRuntimeFilters (
            ' uploads/foo.jpg ' ,
            ' my_thumb ' ,
            $ runtimeConfig
        );

        // ..
    }
}

?>

データルート

デフォルトでは、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でなければなりません。