LiipImagineBundle

LiipImagineBundle

PHPUnit	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. يجب تنفيذ الخطوات التالية

1. قم بتنزيل الحزمة
2. تمكين الحزمة
3. تسجيل الطرق

يمكن العثور على تعليمات الإعداد التفصيلية في فصل التثبيت بالوثائق.

إعدادات

يمكن العثور على معلومات تفصيلية حول جميع خيارات التكوين المتاحة في فصل التكوين بالوثائق.

الاستخدام التمهيدي

بشكل عام، تعمل هذه الحزمة من خلال تطبيق مجموعات المرشحات على الصور من داخل القالب. يتم تعريف مجموعات المرشحات الخاصة بك ضمن ملف تكوين التطبيق (غالبًا 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 : ~

بعد الانتهاء من التكوين الأساسي، سنبدأ بمثال يلبي حالة الاستخدام الشائعة: إنشاء صور مصغرة. لنفترض أننا نريد أن يتم تطبيق التحولات التالية على الصور المصغرة الناتجة:

• قم بقياس الصورة واقتصاصها إلى 120 × 90 بكسل.
• أضف حدًا أسود بحجم 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 بتغيير حجم الصورة إلى العرض والارتفاع المطلوبين (في هذا المثال، 120 × 90 بكسل)، mode: outbound إلى اقتصاص الصورة الناتجة إذا اختلفت نسبة الإدخال. يؤدي مرشح background إلى حد أسود بحجم 2 بكسل عن طريق إنشاء لوحة قماشية سوداء بحجم 124 × 94 بكسل، ووضع الصورة المصغرة في مركزها.

ملاحظة: يمكن أن تحتوي مجموعة المرشحات على أي عدد من المرشحات المحددة لها. قد تتطلب التحويلات البسيطة مرشحًا واحدًا فقط بينما يمكن أن تحتوي التحويلات المعقدة على عدد غير محدود من المرشحات المحددة لها.

هناك عدد من المرشحات الإضافية، ولكن في الوقت الحالي يمكنك استخدام مجموعة مرشحات 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 أو برمجيًا من داخل وحدة التحكم أو أي جزء آخر من التعليمات البرمجية.

حل مع وحدة التحكم

يمكنك حل عنوان URL لصورة باستخدام أمر وحدة التحكم liip:imagine:cache:resolve . الوسيطة الوحيدة المطلوبة هي واحد أو أكثر من مسارات الصور النسبية (والتي يجب أن تكون مفصولة بمسافة).

$ 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

حل برمجيا

يمكنك حل عنوان URL للصورة في التعليمات البرمجية الخاصة بك باستخدام طريقة getBrowserPath لخدمة liip_imagine.cache.manager . بافتراض أن لديك بالفعل الخدمة المخصصة لمتغير يسمى $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
        );

        // ..
    }
}

?> 

جذور البيانات

افتراضيًا، يتم تسجيل دليل web/ الخاص بـ Symfony كجذر بيانات لتحميل الأصول منه. بالنسبة للعديد من عمليات التثبيت، سيكون هذا كافيًا، ولكن في بعض الأحيان قد تحتاج إلى تحميل صور من مواقع أخرى. للقيام بذلك، يجب عليك تعيين المعلمة 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

الأذونات

يجب أن تكون مواقع الصور قابلة للقراءة بواسطة خادم الويب الخاص بك. على نظام يدعم 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

راجع وثائق أذونات Symfony لمعرفة الأوامر المتوافقة مع macOS والبيئات الأخرى.

باستخدام أباتشي

تحتاج إلى منح حق الوصول للقراءة لـ Apache عن طريق إضافة ما يلي إلى تكوين Apache VHost الخاص بك

< 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 .

التوثيق

للحصول على معلومات أكثر تفصيلاً حول ميزات هذه الحزمة، راجع الوثائق.