LiipImagineBundle

Liip ImagineBundle

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 : ~

เมื่อมีการกำหนดค่าพื้นฐานแล้ว เราจะเริ่มต้นด้วยตัวอย่างที่ตอบสนองกรณีการใช้งานทั่วไป: การสร้างภาพขนาดย่อ สมมติว่าเราต้องการให้ภาพขนาดย่อที่ได้มีการแปลงดังต่อไปนี้:

• ปรับขนาดและครอบตัดรูปภาพเป็น 120x90px
• เพิ่มขอบสีดำ 2px ให้กับรูปภาพที่ปรับขนาดแล้ว
• ปรับคุณภาพของภาพเป็น 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 จะปรับขนาดรูปภาพตามความกว้างและความสูงที่ต้องการ (ในตัวอย่างนี้ 120x90px) และตัวเลือก mode: outbound จะทำให้รูปภาพที่ได้ถูกตัดออกหากอัตราส่วนอินพุตแตกต่างกัน ตัวก background ส่งผลให้มีเส้นขอบสีดำขนาด 2px โดยการสร้างผืนผ้าใบสีดำขนาด 124x94px และวางตำแหน่งภาพขนาดย่อไว้ที่กึ่งกลาง

หมายเหตุ: ชุดตัวกรอง สามารถมี ตัวกรอง จำนวนเท่าใดก็ได้ที่กำหนดไว้ การแปลงแบบง่ายอาจต้องใช้ ตัวกรอง เพียงตัวเดียว ในขณะที่การแปลงแบบซับซ้อนสามารถกำหนด ตัวกรอง ได้ไม่จำกัดจำนวน

มีตัวกรองเพิ่มเติมจำนวนหนึ่ง แต่สำหรับตอนนี้ คุณสามารถใช้ ชุดตัวกรอง 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

เอกสารประกอบ

สำหรับข้อมูลโดยละเอียดเพิ่มเติมเกี่ยวกับคุณสมบัติของบันเดิลนี้ โปรดดูที่เอกสารประกอบ