{"id":14983917,"url":"https://github.com/liip/liipimaginebundle","last_synced_at":"2025-05-14T22:06:05.380Z","repository":{"id":37780394,"uuid":"2515323","full_name":"liip/LiipImagineBundle","owner":"liip","description":"Symfony Bundle to assist in image manipulation using the imagine library","archived":false,"fork":false,"pushed_at":"2024-12-12T09:38:48.000Z","size":9002,"stargazers_count":1671,"open_issues_count":77,"forks_count":380,"subscribers_count":78,"default_branch":"2.x","last_synced_at":"2025-05-07T21:58:15.761Z","etag":null,"topics":["bundle","php","symfony","symfony-bundle"],"latest_commit_sha":null,"homepage":"http://liip.ch","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/liip.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2011-10-04T22:41:15.000Z","updated_at":"2025-05-01T20:05:41.000Z","dependencies_parsed_at":"2023-02-14T05:47:16.065Z","dependency_job_id":"0f38fb6b-a5a7-46ab-90fc-ff64179c1a72","html_url":"https://github.com/liip/LiipImagineBundle","commit_stats":{"total_commits":1389,"total_committers":250,"mean_commits":5.556,"dds":0.8912886969042476,"last_synced_commit":"98e0318ea0f7b9500343236e63cc29ded58a1d43"},"previous_names":[],"tags_count":99,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liip%2FLiipImagineBundle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liip%2FLiipImagineBundle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liip%2FLiipImagineBundle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liip%2FLiipImagineBundle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/liip","download_url":"https://codeload.github.com/liip/LiipImagineBundle/tar.gz/refs/heads/2.x","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254235693,"owners_count":22036963,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bundle","php","symfony","symfony-bundle"],"created_at":"2024-09-24T14:08:10.356Z","updated_at":"2025-05-14T22:06:05.333Z","avatar_url":"https://github.com/liip.png","language":"PHP","readme":"# LiipImagineBundle\n\n|         PHPUnit        |      PHP-CS-Fixer       |         Coverage        |        Downloads        |         Release         |\n|:----------------------:|:-----------------------:|:-----------------------:|:-----------------------:|:-----------------------:|\n| [![PHPUnit](https://github.com/liip/LiipImagineBundle/workflows/PHPUnit/badge.svg)](https://github.com/liip/LiipImagineBundle/actions?query=branch%3A2.x+workflow%3APHPUnit) | [![PHP-CS-Fixer](https://github.com/liip/LiipImagineBundle/workflows/PHP-CS-Fixer/badge.svg)](https://github.com/liip/LiipImagineBundle/actions?query=branch%3A2.x+workflow%3APHP-CS-Fixer) | [![Coverage](https://src.run/shield/liip/LiipImagineBundle/2.0/coveralls.svg)](https://src.run/service/liip/LiipImagineBundle/2.0/coveralls) | [![Downloads](https://src.run/shield/liip/LiipImagineBundle/packagist_dt.svg)](https://src.run/service/liip/LiipImagineBundle/packagist) | [![Latest Stable Version](https://src.run/shield/liip/LiipImagineBundle/packagist_v.svg)](https://src.run/service/liip/LiipImagineBundle/packagist) |\n\n*This bundle provides an image manipulation abstraction toolkit for\n[Symfony](http://symfony.com/)-based projects.*\n \n## Overview\n\n- [Filter Sets](http://symfony.com/doc/current/bundles/LiipImagineBundle/basic-usage.html):\n  Using any Symfony-supported configuration language (such as YML and XML), you can create *filter set* definitions that\n  specify transformation routines. These definitions include a set of\n  *[filters](http://symfony.com/doc/current/bundles/LiipImagineBundle/filters.html)* and\n  *[post-processors](http://symfony.com/doc/current/bundles/LiipImagineBundle/post-processors.html)*,\n  as well as other optional parameters.\n\n- [Filters](http://symfony.com/doc/current/bundles/LiipImagineBundle/filters.html):\n  Image transformations are applied using *filters*. A set of\n  [build-in filters](http://symfony.com/doc/current/bundles/LiipImagineBundle/filters.html) are provided by the bundle,\n  implementing the most common transformations; examples include\n  [thumbnail](http://symfony.com/doc/current/bundles/LiipImagineBundle/filters/sizing.html#thumbnails),\n  [scale](http://symfony.com/doc/current/bundles/LiipImagineBundle/filters/sizing.html#scale),\n  [crop](http://symfony.com/doc/current/bundles/LiipImagineBundle/filters/sizing.html#cropping-images),\n  [flip](http://symfony.com/doc/current/bundles/LiipImagineBundle/filters/orientation.html#flip),\n  [strip](http://symfony.com/doc/current/bundles/LiipImagineBundle/filters/general.html#strip), and\n  [watermark](http://symfony.com/doc/current/bundles/LiipImagineBundle/filters/general.html#watermark).\n  For more advances transformations, you can easily create your own\n  [custom filters](http://symfony.com/doc/current/bundles/LiipImagineBundle/filters.html#filter-custom).\n\n- [Post-Processors](http://symfony.com/doc/current/bundles/LiipImagineBundle/post-processors.html):\n  Modification of the resulting binary image file (created from your *filters*) are handled by *post-processors*.\n  Examples include\n  [JPEG Optim](http://symfony.com/doc/current/bundles/LiipImagineBundle/post-processors/jpeg-optim.html),\n  [Moz JPEG](http://symfony.com/doc/current/bundles/LiipImagineBundle/post-processors/jpeg-moz.html),\n  [Opti PNG](http://symfony.com/doc/current/bundles/LiipImagineBundle/post-processors/png-opti.html), and\n  [PNG Quant](http://symfony.com/doc/current/bundles/LiipImagineBundle/post-processors/png-quant.html). Just like filters\n  you can easily create your own\n  [custom post-processors](http://symfony.com/doc/current/bundles/LiipImagineBundle/post-processors.html#post-processors-custom).\n\n\n### Example\n\nSuppose you defined a `my_thumb` filter set, which can be configured to \nperform any number of different transformations. The simplest invocation would \nbe to pipe the path of your image to the provided `imagine_filter` Twig \nfilter.\n\n```twig\n\u003cimg src=\"{{ asset('/relative/path/to/image.jpg') | imagine_filter('my_thumb') }}\" /\u003e\n```\n\n### Contributor Code of Conduct\n\nThis project is released with a [Contributor Code of Conduct](.github/CODE_OF_CONDUCT.md).\nBy participating in this project you agree to abide by its terms.\n\n### Attribution\n\n- Thanks to the many [contributors](https://github.com/liip/LiipImagineBundle/graphs/contributors) \n  who have dedicated their time and code to this project.\n\n- The standalone PHP\n  [Imagine Library](https://github.com/avalanche123/Imagine)\n  is used by this bundle for image transformations.\n\n- This package was forked from\n  [AvalancheImagineBundle](https://github.com/avalanche123/AvalancheImagineBundle)\n  with the goal of making the code more extensible. Reference\n  [AvalancheImagineBundle#25](https://github.com/avalanche123/AvalancheImagineBundle/pull/25)\n  for additional information on the reasoning for this fork.\n\n\n## Setup\n\n\n### Installation\n\nUsing this package is similar to all Symfony bundles. The following steps must \nbe performed\n\n1. [Download the Bundle](http://symfony.com/doc/current/bundles/LiipImagineBundle/installation.html#step-1-download-the-bundle)\n2. [Enable the Bundle](http://symfony.com/doc/current/bundles/LiipImagineBundle/installation.html#step-2-enable-the-bundle)\n3. [Register the Routes](http://symfony.com/doc/current/bundles/LiipImagineBundle/installation.html#step-3-register-the-bundle-s-routes)\n\nDetailed setup instructions can be found in the \n[installation](http://symfony.com/doc/current/bundles/LiipImagineBundle/installation.html)\nchapter of the documentation.\n\n\n### Configuration\n\nDetailed information on all available configuration options can be found in the\n[configuration](http://symfony.com/doc/current/bundles/LiipImagineBundle/configuration.html)\nchapter of the documentation.\n\n\n## Usage Primer\n\nGenerally, this bundle works by applying *filter sets* to images from inside\na template. Your *filter sets* are defined within the application's configuration\nfile (often `app/config/config.yml`) and are comprised of a collection of\n*filters*, *post-processors*, and other optional parameters.\n\nWe'll learn more about *post-processors* and other available parameters later,\nbut for now lets focus on how to define a simple *filter set* comprised of a\nfew *filters*.\n\n\n### Create Thumbnails\n\nBefore we get started, there is a small amount of configuration needed to ensure\nour [data loaders](http://symfony.com/doc/current/bundles/LiipImagineBundle/data-loaders.html)\nand [cache resolvers](http://symfony.com/doc/current/bundles/LiipImagineBundle/cache-resolvers.html)\noperate correctly. Use the following boilerplate in your configuration file.\n\n```yml\n# app/config/config.yml\n\nliip_imagine :\n\n    # configure resolvers\n    resolvers :\n\n        # setup the default resolver\n        default :\n\n            # use the default web path\n            web_path : ~\n\n    # your filter sets are defined here\n    filter_sets :\n\n        # use the default cache configuration\n        cache : ~\n```\n\nWith the basic configuration in place, we'll start with an example that fulfills a\ncommon use-case: creating thumbnails. Lets assume we want the resulting thumbnails\nto have the following transformations applied to them:\n\n- Scale and crop the image to 120x90px.\n- Add a 2px black border to the scaled image.\n- Adjust the image quality to 75.\n\nAdding onto our boilerplate from above, we need to define a *filter set* (which we'll\nname `my_thumb`) with two *filters* configured: the `thumbnail` and `background`\n*filters*.\n\n```yml\n# app/config/config.yml\n\nliip_imagine :\n    resolvers :\n        default :\n            web_path : ~\n\n    filter_sets :\n        cache : ~\n\n        # the name of the \"filter set\"\n        my_thumb :\n\n            # adjust the image quality to 75%\n            quality : 75\n\n            # list of transformations to apply (the \"filters\")\n            filters :\n\n                # create a thumbnail: set size to 120x90 and use the \"outbound\" mode\n                # to crop the image when the size ratio of the input differs\n                thumbnail  : { size : [120, 90], mode : outbound }\n\n                # create a 2px black border: center the thumbnail on a black background\n                # 4px larger to create a 2px border around the final image\n                background : { size : [124, 94], position : center, color : '#000000' }\n```\n\nYou've now created a *filter set* called `my_thumb` that performs a thumbnail\ntransformation. The `thumbnail` filter sizes the image to the desired width\nand height (in this example, 120x90px), and its `mode: outbound` option causes\nthe resulting image to be cropped if the input ratio differs. The `background`\nfilter results in a 2px black border by creating a black canvas 124x94px in size,\nand positioning the thumbnail at its center.\n\n**Note:**\n*A *filter set* can have any number of *filters* defined for it. Simple\ntransformations may only require a single *filter* while complex\ntransformations can have an unlimited number of *filters* defined for them.*\n\nThere are a number of additional [filters](http://symfony.com/doc/current/bundles/LiipImagineBundle/filters.html),\nbut for now you can use your newly defined ``my_thumb`` *filter set* immediately\nwithin a template.\n\n*For Twig-based template, use:*\n\n```twig\n\u003cimg src=\"{{ asset('/relative/path/to/image.jpg') | imagine_filter('my_thumb') }}\" /\u003e\n```\n\n*Or, for PHP-based template, use:*\n\n```php\n\u003cimg src=\"\u003c?php $this['imagine']-\u003efilter('/relative/path/to/image.jpg', 'my_thumb') ?\u003e\" /\u003e\n```\n\nBehind the scenes, the bundle applies the filter(s) to the image on-the-fly\nwhen the first page request is served. The transformed image is then cached\nfor subsequent requests. The final cached image path would be similar to\n`/media/cache/my_thumb/relative/path/to/image.jpg`.\n\n**Note:**\n*Using the ``dev`` environment you might find that images are not properly\nrendered via the template helper. This is often caused by having\n`intercept_redirect` enabled in your application configuration. To ensure\nimages are rendered, it is strongly suggested to disable this option:\n\n```yml\n# app/config/config_dev.yml\n\nweb_profiler :\n    intercept_redirects : false\n```\n\n\n### Runtime Options\n\nSometime, you may have a filter defined that fulfills 99% of your usage\nscenarios. Instead of defining a new filter for the erroneous 1% of cases,\nyou may instead choose to alter the behavior of a filter at runtime by\npassing the template helper an options array.\n\n*For Twig-based template, use:*\n\n```twig\n{% set runtimeConfig = {\"thumbnail\": {\"size\": [50, 50] }} %}\n\n\u003cimg src=\"{{ asset('/relative/path/to/image.jpg') | imagine_filter('my_thumb', runtimeConfig) }}\" /\u003e\n```\n\n*Or, for PHP-based template, use:*\n\n```php\n\u003c?php\n$runtimeConfig = array(\n    \"thumbnail\" =\u003e array(\n        \"size\" =\u003e array(50, 50)\n    )\n);\n?\u003e\n\n\u003cimg src=\"\u003c?php $this['imagine']-\u003efilter('/relative/path/to/image.jpg', 'my_thumb', $runtimeConfig) ?\u003e\" /\u003e\n```\n\n\n### Path Resolution\n\nSometime you need to resolve the image path returned by this bundle for a\nfiltered image. This can easily be achieved using Symfony's console binary\nor programmatically from within a controller or other piece of code.\n\n\n#### Resolve with the Console\n\nYou can resolve an image URL using the console command\n`liip:imagine:cache:resolve`. The only required argument is one or more\nrelative image paths (which must be separated by a space).\n\n```bash\n$ php bin/console liip:imagine:cache:resolve relative/path/to/image1.jpg relative/path/to/image2.jpg\n```\n\nAdditionally, you can use the ``--filter`` option to specify which filter\nyou want to resolve for (if the ``--filter`` option is omitted, all\navailable filters will be resolved).\n\n```bash\n$ php bin/console liip:imagine:cache:resolve relative/path/to/image1.jpg --filter=my_thumb\n```\n\n\n#### Resolve Programmatically\n\nYou can resolve the image URL in your code using the `getBrowserPath`\nmethod of the `liip_imagine.cache.manager` service. Assuming you already\nhave the service assigned to a variable called `$imagineCacheManager`,\nyou would run:\n\n```php\n$imagineCacheManager-\u003egetBrowserPath('/relative/path/to/image.jpg', 'my_thumb');\n```\n\nOften, you need to perform this operation in a controller. Assuming your\ncontroller inherits from the base Symfony controller, you can take advantage\nof the inherited ``get`` method to request the ``liip_imagine.cache.manager``\nservice, from which you can call ``getBrowserPath`` on a relative image\npath to get its resolved location.\n\n```php\n/** @var CacheManager */\n$imagineCacheManager = $this-\u003eget('liip_imagine.cache.manager');\n\n/** @var string */\n$resolvedPath = $imagineCacheManager-\u003egetBrowserPath('/relative/path/to/image.jpg', 'my_thumb');\n```\n\n\n## Filters\n\nThis bundle provides a set of built-in filters and you may easily\ndefine your own filters as well. Reference the\n[filters chapter](http://symfony.com/doc/current/bundles/LiipImagineBundle/filters.html)\nfrom our documentation.\n\n\n## Use as a Service\n\nIf you need to use your defined \"filter sets\" from within your controller, you \ncan fetch this bundle's FilterService from the service container to do the heavy\nlifting for you.\n\n```php\n\u003c?php\n\nclass MyController extends Controller\n{\n    public function indexAction()\n    {\n        /** @var FilterService */\n        $imagine = $this\n            -\u003econtainer\n            -\u003eget('liip_imagine.service.filter');\n\n        // 1) Simple filter, OR\n        $resourcePath = $imagine-\u003egetUrlOfFilteredImage('uploads/foo.jpg', 'my_thumb');\n        \n        // 2) Runtime configuration\n        $runtimeConfig = [\n            'thumbnail' =\u003e [\n                'size' =\u003e [200, 200]\n            ],\n        ];\n        $resourcePath = $imagine-\u003egetUrlOfFilteredImageWithRuntimeFilters(\n            'uploads/foo.jpg',\n            'my_thumb',\n            $runtimeConfig\n        );\n\n        // ..\n    }\n}\n\n?\u003e\n```\n\n## Data Roots\n\nBy default, Symfony's `web/` directory is registered as a data root to load\nassets from. For many installations this will be sufficient, but sometime you\nmay need to load images from other locations. To do this, you must set the\n`data_root` parameter in your configuration (often located at `app/config/config.yml`).\n\n```yml\nliip_imagine:\n    loaders:\n        default:\n            filesystem:\n                data_root: /path/to/source/images/dir\n```\n\nAs of version `1.7.2` you can register multiple data root paths, and the \nfile locator will search each for the requested file.\n\n```yml\nliip_imagine:\n    loaders:\n        default:\n            filesystem:\n                data_root:\n                    - /path/foo\n                    - /path/bar\n```\n\nAs of version `1.7.3` you ask for the public resource paths from all registered bundles\nto be auto-registered as data roots. This allows you to load assets from the\n`Resources/public` folders that reside within the loaded bundles. To enable this\nfeature, set the `bundle_resources.enabled` configuration option to `true`.\n\n```yml\nliip_imagine:\n    loaders:\n        default:\n            filesystem:\n                bundle_resources:\n                    enabled: true\n```\n\nIf you want to register some of the `Resource/public` folders, but not all, you can do\nso by blacklisting the bundles you don't want registered or whitelisting the bundles you\ndo want registered. For example, to blacklist (not register) the bundles \"FooBundle\" and\n\"BarBundle\", you would use the following configuration.\n\n```yml\nliip_imagine:\n    loaders:\n        default:\n            filesystem:\n                bundle_resources:\n                    enabled: true\n                    access_control_type: blacklist\n                    access_control_list:\n                        - FooBundle\n                        - BarBundle\n```\n\nAlternatively, if you want to whitelist (only register) the bundles \"FooBundle\" and \"BarBundle\",\nyou would use the following configuration.\n\n```yml\nliip_imagine:\n    loaders:\n        default:\n            filesystem:\n                bundle_resources:\n                    enabled: true\n                    access_control_type: whitelist\n                    access_control_list:\n                        - FooBundle\n                        - BarBundle\n```\n\n### Permissions\n\nImage locations must be readable by your web server. On a system that supports \n`setfacl` (such as Linux/BSD), use\n\n```sh\nHTTPDUSER=`ps axo user,comm | grep -E '[a]pache|[h]ttpd|[_]www|[w]ww-data|[n]ginx' | grep -v root | head -1 | cut -d\\  -f1`\n\nsudo setfacl -R -m u:\"$HTTPDUSER\":rwX -m u:`whoami`:rwX /path/to/source/images/dir\n\nsudo setfacl -dR -m u:\"$HTTPDUSER\":rwX -m u:`whoami`:rwX /path/to/source/images/dir\n```\n\nSee the [Symfony Permissions documentation](http://symfony.com/doc/current/setup/file_permissions.html)\nfor commands compatible with macOS and other environments.\n\n\n### Using Apache\n\nYou need to grant read access for Apache by adding the following to your \nApache VHost configuration\n\n```xml\n\u003cVirtualHost *:80\u003e\n    \u003c!-- Rest of directives like DocumentRoot or ServerName --\u003e\n\n    Alias /FavouriteAlias /path/to/source/images/dir\n    \u003cDirectory \"/path/to/source/images/dir\"\u003e\n        AllowOverride None\n        Allow from All\n    \u003c/Directory\u003e\n\u003c/VirtualHost\u003e\n```\n\nAlternatively, you can place the directive in a separate file within your \nproject, and include it within your Apache VHost configuration. For example, \nyou can create the file `app/config/apache/photos.xml` and add the following \nto your VHost file\n\n```xml\n\u003cVirtualHost *:80\u003e\n    \u003c!-- Rest of directives like DocumentRoot or ServerName --\u003e\n\n    Include \"/path/to/your/project/app/config/apache/photos.xml\"\n\u003c/VirtualHost\u003e\n```\n\nThis method keeps the file with the rest of your code, allowing you to change\nit easily or create different environment-dependent configuration files.\n\nOnce you have configured Apache properly, the relative path to an image with \nthe following absolute path `/path/to/source/images/dir/logo.png` must be\n`/FavouriteAlias/logo.png`.\n\n\n## Documentation\n\nFor more detailed information about the features of this bundle, refer to\nthe [documentation](http://symfony.com/doc/current/bundles/LiipImagineBundle).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fliip%2Fliipimaginebundle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fliip%2Fliipimaginebundle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fliip%2Fliipimaginebundle/lists"}