JoliMediaBundle

https://mediabundle.jolicode.com
Admin
JoliMediaBundle is a modern Symfony bundle that provides comprehensive media management tools...
Tokens:30,061
Snippets:277
Trust Score:9.9
Update:7 months ago
Show doc for...
Tokens:
Raw
### Minimal JoliMedia Configuration (YAML)

Source: https://mediabundle.jolicode.com/getting-started/configuration

This YAML configuration defines a basic JoliMedia setup. It includes a default library with 'original' and 'cache' storage configurations, specifying Flysystem adapters and URL generators. It also sets up a 'product' variation with a resize transformer. This serves as a starting point for customizing media handling.

```yaml
joli_media:
    default_library: default
    libraries:
        default:
            original:
                flysystem: default.original.storage
                url_generator:
                    path: /media/original/
            cache:
                flysystem: default.cache.storage
                url_generator:
                    path: /media/cache/
                must_store_when_generating_url: false
            variations:
                product:
                    transformers:
                        resize:
                            width: 200
                            height: 200
                            mode: inside
                            allow_downscale: true
                            allow_upscale: true
```

--------------------------------

### Install JoliMediaBundle with Composer

Source: https://mediabundle.jolicode.com/getting-started/installation

Use Composer to add the JoliMediaBundle to your project dependencies. This is the primary method for including the bundle.

```bash
$ composer require jolicode/media-bundle
```

--------------------------------

### Manually Install cwebp and gif2webp

Source: https://mediabundle.jolicode.com/getting-started/dependencies-and-tooling

Downloads and installs the cwebp and gif2webp binaries from Google's WebP release. These tools are used for converting images to and from the WebP format.

```bash
cd /tmp \
    && wget -O libwebp-1.6.0-linux-x86-64.tar.gz https://storage.googleapis.com/downloads.webmproject.org/releases/webp/libwebp-1.6.0-linux-x86-64.tar.gz \
    && tar xzvf libwebp-1.6.0-linux-x86-64.tar.gz \
    && cp libwebp-1.6.0-linux-x86-64/bin/cwebp /usr/local/bin/cwebp \
    && cp libwebp-1.6.0-linux-x86-64/bin/gif2webp /usr/local/bin/gif2webp
```

--------------------------------

### Crop Transformer Configuration (YAML)

Source: https://mediabundle.jolicode.com/variations/transformers

Example configuration for the 'crop' transformer. It specifies the desired width and height of the cropped area. The `start_x` and `start_y` parameters can be used to define the starting point of the crop.

```yaml
transformers:
    crop:
        width: 70
        height: 40
```

```yaml
transformers:
    crop:
        width: 50
        height: 50
        start_x: 50%
        start_y: 10%
```

--------------------------------

### Manually Install oxipng

Source: https://mediabundle.jolicode.com/getting-started/dependencies-and-tooling

Downloads and installs oxipng version 9.1.5, an advanced PNG optimizer. This command ensures the latest version is available for optimizing PNG files.

```bash
cd /tmp \
    && wget -O oxipng-9.1.5-x86_64-unknown-linux-musl.tar.gz https://github.com/shssoichiro/oxipng/releases/download/v9.1.5/oxipng-9.1.5-x86_64-unknown-linux-musl.tar.gz \
    && tar xzvf oxipng-9.1.5-x86_64-unknown-linux-musl.tar.gz \
    && cp oxipng-9.1.5-x86_64-unknown-linux-musl/oxipng /usr/local/bin/oxipng
```

--------------------------------

### Customize Post-processor Options for Library

Source: https://mediabundle.jolicode.com/variations/post-processors

Shows how to override default post-processor options for a specific media library, like 'example'. This allows for tailored optimization settings for different sets of media.

```yaml
joli_media:
    libraries:
        example:
            post_processors:
                jpegoptim:
                    max_quality: 90
                mozjpeg:
                    quality: 95
```

--------------------------------

### Sequential Transformer Application Example (YAML)

Source: https://mediabundle.jolicode.com/variations/transformers

Demonstrates how transformers are applied sequentially based on their order in the configuration file. If the same transformer type is needed multiple times, it can be listed multiple times.

```yaml
my_variation:
    transformers:
        resize:
            width: 200
            height: 150
            mode: inside
        heighten:
            height: 600
```

```yaml
my_variation:
    transformers:
        - type: resize
          width: 200
          height: 150
        - type: heighten
          height: 600
        - type: resize
          width: 300
          height: 200
```

--------------------------------

### Configure Exiftool Binary Path

Source: https://mediabundle.jolicode.com/variations/pre-processors

This configuration example illustrates how to specify the path to the exiftool binary. It can be set via an environment variable `JOLI_MEDIA_EXIFTOOL_BINARY` or directly in the `joli_media.binary.exiftool` configuration parameter. This is crucial for the pre-processor to function correctly.

```yaml
# Using environment variable:
# export JOLI_MEDIA_EXIFTOOL_BINARY=/usr/local/bin/exiftool

# Using configuration parameter:
joli_media:
    binary:
        exiftool: /usr/local/bin/exiftool

```

--------------------------------

### Manually Install mozjpeg

Source: https://mediabundle.jolicode.com/getting-started/dependencies-and-tooling

Compiles and installs mozjpeg version 4.1.1 from source. mozjpeg is an advanced JPEG encoder that aims to improve compression quality.

```bash
cd /tmp \
    && wget -O mozjpeg.tar.gz https://github.com/mozilla/mozjpeg/archive/refs/tags/v4.1.1.tar.gz \
    && tar xzvf mozjpeg.tar.gz \
    && cd /tmp/mozjpeg-4.1.1 \
    && cmake -G"Unix Makefiles" \
    && make \
    && make install
```

--------------------------------

### Define JoliMediaBundle Routes

Source: https://mediabundle.jolicode.com/getting-started/installation

Configure the routing for the JoliMediaBundle by including its routes file in your Symfony routing configuration. This makes the bundle's routes accessible.

```yaml
# filepath: config/routes/joli_media.yaml
_joli_media:
    resource: "@JoliMediaBundle/config/routes.php"
```

--------------------------------

### Configure Processor Binaries Location - Parameters

Source: https://mediabundle.jolicode.com/variations/processors

This outlines the configuration parameters within the MediaBundle that can be used to specify the installation paths for processor binaries. This method offers an alternative to environment variables for managing binary locations.

```yaml
joli_media.binary.cwebp
joli_media.binary.gif2webp
joli_media.binary.gifsicle
joli_media.binary.identify
```

--------------------------------

### Full JoliMedia Variation Configuration Example

Source: https://mediabundle.jolicode.com/variations/variations

This configuration defines a 'profile_picture' variation with specific settings for WebP generation, pixel ratios, post-processors, processors, transformers, and voters. It demonstrates how to control image optimization, format, and apply specific rules for media variations.

```yaml
joli_media:
    libraries:
        example_library:
            variations:
                profile_picture:
                    enable_auto_webp: true
                    pixel_ratios: [1, 2, 3]
                    post_processors:
                        jpegoptim:
                            options:
                                strip_all: false
                                max_quality: 60
                    processors:
                        imagine:
                            options:
                                jpeg_quality: 99
                    transformers:
                        thumbnail:
                            width: 100
                            height: 100
                    voters:
                        - type: format
                          format: jpg
```

--------------------------------

### Install JoliMediaBundle Dependencies on Debian

Source: https://mediabundle.jolicode.com/getting-started/dependencies-and-tooling

Installs essential media processing tools and libraries on Debian-based systems using the apt package manager. This includes tools for image format conversion, metadata extraction, and optimization.

```bash
sudo apt install \
    exiftran \
    file \
    gifsicle \
    imagemagick \
    jpegoptim \
    libheif1 \
    libheif-plugins-all \
    libimage-exiftool-perl \
    libmagickcore-dev \
    pngquant
```

--------------------------------

### Register JoliMediaBundle in Symfony

Source: https://mediabundle.jolicode.com/getting-started/installation

Manually register the JoliMediaBundle in your Symfony application's `config/bundles.php` file if not using Symfony Flex. This ensures the bundle is loaded by the framework.

```php
return [
    // ...
    JoliCode\MediaBundle\JoliMediaBundle::class => ['all' => true],
];
```

--------------------------------

### Configure Processor Binaries Location - Environment Variables

Source: https://mediabundle.jolicode.com/variations/processors

This section lists environment variables that can be used to define the installation location for various media processing binaries like cwebp, gif2webp, gifsicle, and identify. This provides a flexible way to manage binary paths.

```env
JOLI_MEDIA_CWEBP_BINARY
JOLI_MEDIA_GIF2WEBP_BINARY
JOLI_MEDIA_GIFSICLE_BINARY
JOLI_MEDIA_IDENTIFY_BINARY
```

--------------------------------

### Example MediaBundle Configuration for Variations

Source: https://mediabundle.jolicode.com/variations/variations

This configuration defines a media variation that outputs WebP files, resizes images to fit within a 200x150 box, and ensures the final height is 600 pixels. It demonstrates the use of transformers for image manipulation.

```yaml
admin:
    format: webp
    transformers:
        resize:
            width: 200
            height: 150
            mode: outside
        heighten:
            height: 600
```

--------------------------------

### Default Processor Binaries Locations

Source: https://mediabundle.jolicode.com/variations/processors

This provides the default installation paths that the MediaBundle will use for essential processing binaries if no specific configuration is provided. These are standard locations for such tools.

```text
/usr/local/bin/cwebp
/usr/local/bin/gif2webp
/usr/local/bin/gifsicle
/usr/local/bin/identify
```

--------------------------------

### Generate Img Tag from Different Library

Source: https://mediabundle.jolicode.com/misc-features/twig-components

This example shows how to specify a custom library for the image using the `library` attribute in the `twig:joli:Img` component. This is useful when images are not stored in the default media library.

```twig
<twig:joli:Img
    path="example-image.png"
    variation="variation_name"
    library="library_name"
    alt="Alternative text"
/>
```

--------------------------------

### Widen Transformer Configuration (YAML)

Source: https://mediabundle.jolicode.com/variations/transformers

Example configuration for the 'widen' transformer, which adjusts the image's width to a specified percentage while maintaining the aspect ratio.

```yaml
transformers:
    widen:
        width: 300%
```

--------------------------------

### Manage Backend Dependencies with Castor

Source: https://mediabundle.jolicode.com/tests-and-qa-tooling

Installs backend dependencies for the project using the Castor task runner. This is a fundamental step for setting up the development environment.

```bash
backend:install   Install backend dependencies
```

--------------------------------

### Configure Media Validation Constraints

Source: https://mediabundle.jolicode.com/misc-features/using-in-doctrine-entities

Provides examples of configuring the `Media` validation constraint with specific options such as allowed extensions, mime types, paths, types, and maximum path length.

```php
#[MediaConstraint(
    allowedExtensions: ['jpg', 'jpeg', 'png'],
    extensionMessage: 'Allowed extensions are: {{ extensions }}.',
    allowedMimeTypes: ['image/jpeg', 'image/png'],
    mimeTypeMessage: 'Allowed mime types are: {{ mimeTypes }}.',
    allowedPaths: ['illustration', 'avatar'],
    pathMessage: 'The file path "{{ value }}" is not allowed. Allowed paths must start with one of the following: {{ paths }}.',
    allowedTypes: ['image'],
    typeMessage: 'Allowed types are: {{ types }}.',
    maxPathLength: 255,
    maxPathLengthMessage: 'The file path "{{ value }}" exceeds the maximum length of {{ limit }} characters.',
)]
public ?Media $image = null;
```

--------------------------------

### Tooling Management with Castor

Source: https://mediabundle.jolicode.com/tests-and-qa-tooling

Commands for installing and updating development tooling required for quality assurance tasks. Ensures that all necessary tools are present and up-to-date.

```bash
qa:install        Installs tooling
qa:update         Updates the tooling
```

--------------------------------

### Generate Srcset for High-Density Images

Source: https://mediabundle.jolicode.com/misc-features/twig-components

This example demonstrates how to generate a `srcset` attribute for high-density images. By providing an array of variation names (e.g., `['variation_name', 'variation_name_2x']`) to the `variation` attribute, the component creates multiple image sources for different pixel densities, along with a `sizes` attribute.

```twig
<twig:joli:Img
    path="high-density-image.png"
    alt="Alternative text"
    variation="{{ ['variation_name', 'variation_name_2x'] }}"
/>
```

--------------------------------

### Resize Transformer Configuration (YAML)

Source: https://mediabundle.jolicode.com/variations/transformers

Examples of the 'resize' transformer with different modes: 'exact' forces the image to the specified dimensions, 'inside' resizes while maintaining aspect ratio to fit within the dimensions, and 'outside' resizes to fill the dimensions while maintaining aspect ratio.

```yaml
transformers:
    resize:
        width: 90
        height: 150
        mode: exact
```

```yaml
transformers:
    resize:
        width: 90
        height: 150
        mode: inside
```

```yaml
transformers:
    resize:
        width: 90
        height: 150
        mode: outside
```

--------------------------------

### Generate Responsive Image with Complex Sizes Attribute using JoliCode MediaBundle

Source: https://mediabundle.jolicode.com/misc-features/twig-components

This example demonstrates generating a responsive image with a complex `sizes` attribute using JoliCode MediaBundle. The `sizes` attribute is defined with media conditions to provide different image sizes based on viewport width, ensuring optimal image delivery across various devices. The output is an `<img>` tag with a dynamically generated `sizes` attribute reflecting the provided conditions.

```twig
<twig:joli:Img
    path="high-density-image.png"
    alt="Alternative text"
    variation="{{ ['variation_name', 'variation_name_2x'] }}"
    sizes="(50em <= width <= 60em) 50em, (30em <= width < 50em) 30em, (width < 30em) 20em"
/>

<img
    src="/path/to/cache/variation-name/high-density-image.png"
    srcset="
        /path/to/cache/variation-name/high-density-image.png    200w,
        /path/to/cache/variation-name@2x/high-density-image.png 400w
    "
    sizes="(50em <= width <= 60em) 50em, (30em <= width < 50em) 30em, (width < 30em) 20em"
    alt="Alternative text"
    width="200"
    height="200"
    loading="lazy"
    decoding="async"
/>
```

--------------------------------

### Expand Transformer Configuration (YAML)

Source: https://mediabundle.jolicode.com/variations/transformers

Example configuration for the 'expand' transformer. This transformer increases the dimensions of the image to the specified width and height, filling the extra space with a background color. The position of the original image within the expanded canvas can be controlled.

```yaml
transformers:
    expand:
        width: 150
        height: 200
        background_color: '#aaffaa'
```

```yaml
transformers:
    crop:
        width: 60
        height: 60
    expand:
        width: 150
        height: 200
        background_color: '#ffccff'
```

```yaml
transformers:
    crop:
        width: 60
        height: 60
    expand:
        width: 200
        height: 150
        background_color: '#ffccff'
        position_x: end
        position_y: end
```

--------------------------------

### Thumbnail Transformer Configuration (YAML)

Source: https://mediabundle.jolicode.com/variations/transformers

Configurations for the 'thumbnail' transformer, which creates a thumbnail of the image. Options include specifying dimensions and the crop position ('start' or 'end').

```yaml
transformers:
    thumbnail:
        width: 40
        height: 120
```

```yaml
transformers:
    thumbnail:
        width: 120
        height: 40
```

```yaml
transformers:
    thumbnail:
        width: 40
        height: 120
        crop_position: start
```

```yaml
transformers:
    thumbnail:
        width: 120
        height: 40
        crop_position: end
```

--------------------------------

### Manage Frontend Assets with Castor

Source: https://mediabundle.jolicode.com/tests-and-qa-tooling

Commands for managing frontend assets, including compilation, installation of dependencies, and watching for changes during development. These tasks ensure frontend code is built and served correctly.

```bash
frontend:compile  Compile assets
frontend:install  Install assets
frontend:watch    Watch frontend assets
```

--------------------------------

### Override Processor Options for Library - YAML

Source: https://mediabundle.jolicode.com/variations/processors

This YAML configuration demonstrates how to override specific processor options, like 'jpeg_quality', for a particular library ('example') within the MediaBundle. It allows for fine-tuning processing for individual libraries.

```yaml
joli_media:
    libraries:
        example:
            processors:
                imagine:
                    jpeg_quality: 90
```

--------------------------------

### Perform QA Tasks with Castor

Source: https://mediabundle.jolicode.com/tests-and-qa-tooling

Runs a suite of quality assurance tasks, including installing tooling, building Docker images, and executing all defined QA checks. This command is recommended before contributing to the project.

```bash
$ castor docker:build
$ castor qa:install
$ castor qa:all
```

--------------------------------

### Complex Sequential Transformer Pipeline (YAML)

Source: https://mediabundle.jolicode.com/variations/transformers

An example demonstrating a complex sequence of multiple transformers, including crop, expand, heighten, widen, and resize, applied in a specific order to achieve a desired final image.

```yaml
transformers:
    - type: crop
      width: 60
      height: 60
    - type: expand
      width: 80
      height: 80
      background_color: '#ffcccc'
      position_x: end
      position_y: end
    - type: heighten
      height: 100
    - type: expand
      width: 120
      height: 120
      background_color: '#ccffcc'
      position_x: start
      position_y: end
    - type: widen
      width: 140
    - type: expand
      width: 160
      height: 160
      background_color: '#ccccff'
      position_x: start
      position_y: start
    - type: resize
      width: 180
      height: 180
      mode: exact
    - type: expand
      width: 200
      height: 200
      background_color: '#ffff44'
    - type: thumbnail
      width: 100
      height: 100
```

--------------------------------

### Configure Media Deletion Behavior in Entity with Attributes

Source: https://mediabundle.jolicode.com/misc-features/media-deletion-behavior

This example demonstrates how to use the `#[MediaDeleteBehavior]` attribute to configure deletion strategies for media fields within an entity. It shows how to set the `SET_NULL` strategy for an optional image field and the `RESTRICT` strategy for a required image field, leveraging Doctrine types and MediaBundle constraints.

```php
use JoliCode\MediaBundle\DeleteBehavior\Attribute\MediaDeleteBehavior;
use JoliCode\MediaBundle\DeleteBehavior\Strategy;
use JoliCode\MediaBundle\Doctrine\Types as MediaTypes;
use JoliCode\MediaBundle\Model\Media;
use JoliCode\MediaBundle\Validator\Media as MediaConstraint;

#[ORM\Entity]
class Article
{
    // ...

    #[MediaConstraint(allowedTypes: ['image', 'video'])]
    #[MediaDeleteBehavior(strategy: Strategy::SET_NULL)]
    #[ORM\Column(type: MediaTypes::MEDIA, nullable: true)]
    public ?Media $image = null;

    #[MediaConstraint(allowedTypes: ['image', 'video'])]
    #[MediaDeleteBehavior(strategy: Strategy::RESTRICT)]
    #[ORM\Column(type: MediaTypes::MEDIA, nullable: false)]
    public Media $requiredImage;

    // ...
}
```

--------------------------------

### Configure Global Pre-processors in JoliMediaBundle

Source: https://mediabundle.jolicode.com/variations/pre-processors

This configuration snippet shows how to define pre-processors that will be applied globally to all media before any variation is computed. Pre-processors are executed sequentially in the order they are listed.

```yaml
joli_media:
    pre_processors:
        - App\Media\PreProcessor\AutoRotateImagePreProcessor
        # - ...

```

--------------------------------

### Configure Default Folder for Media Selector

Source: https://mediabundle.jolicode.com/bridges/easy-admin

Shows how to set a default folder for the media selector widget using the `setFolder()` method. If media is already selected, it defaults to the folder of the selected media.

```php
use JoliCode\MediaBundle\Bridge\EasyAdmin\Field\MediaChoiceField;

class ArticleCrudController extends AbstractCrudController
{
    public function configureFields(string $pageName): iterable
    {
        return [
            MediaChoiceField::new('image')->setFolder('example-folder')
        ];
    }
}
```

--------------------------------

### Heighten Transformer Configuration (YAML)

Source: https://mediabundle.jolicode.com/variations/transformers

Configuration example for the 'heighten' transformer, which adjusts the image's height to a specified value while maintaining the aspect ratio.

```yaml
transformers:
    heighten:
        height: 300
```

--------------------------------

### Configure ExifRemovalPreProcessor in JoliCode MediaBundle

Source: https://mediabundle.jolicode.com/variations/pre-processors

This configuration snippet shows how to register the ExifRemovalPreProcessor within the `joli_media` configuration. It demonstrates adding the pre-processor to the `pre_processors` list. This is essential for enabling EXIF metadata removal.

```yaml
joli_media:
    pre_processors:
        - JoliCode\MediaBundle\PreProcessor\ExifRemovalPreProcessor
        # - ...

```

--------------------------------

### Generate Basic Responsive Image with JoliCode MediaBundle

Source: https://mediabundle.jolicode.com/misc-features/twig-components

This snippet shows how to generate a basic responsive image using JoliCode MediaBundle. It utilizes `variation` and `sizes` attributes to create `srcset` and `sizes` for the `<img>` tag, enabling responsive image loading. The output is a standard HTML `<img>` tag with attributes like `src`, `srcset`, `sizes`, `alt`, `width`, `height`, `loading`, and `decoding`.

```twig
<twig:joli:Img
    path="high-density-image.png"
    alt="Alternative text"
    variation="{{ ['variation_name', 'variation_name_2x'] }}"
    sizes="600px"
/>

<img
    src="/path/to/cache/variation-name/high-density-image.png"
    srcset="
        /path/to/cache/variation-name/high-density-image.png    200w,
        /path/to/cache/variation-name@2x/high-density-image.png 400w
    "
    sizes="600px"
    alt="Alternative text"
    width="200"
    height="200"
    loading="lazy"
    decoding="async"
/>
```

--------------------------------

### Generate Responsive Images with Picture Component

Source: https://mediabundle.jolicode.com/misc-features/twig-components

Demonstrates how to use the `joli:Picture` component to generate a responsive image with multiple sources for different screen sizes and formats. It takes attributes like `variation`, `alt`, `class`, and `sources` to configure the output.

```twig
<twig:joli:Picture
    variation="variation_name"
    alt="Alternative text"
    picture:class="picture-class"
    img:class="image-class"
    sources="{{ [
        {
            media: '(width > 1024px)',
            sizes: '1920px',
            srcset: {
                '1920w': 'variation-large',
                '2560w': 'variation-extra-large'
            }
        },
        {
            media: '(width > 768px)',
            sizes: '1024px',
            srcset: {
                '1024w': 'variation-medium',
                '1600w': 'variation-large'
            }
        },
    ] }}"
/>
```

--------------------------------

### Skip Automatic Image Dimensions

Source: https://mediabundle.jolicode.com/misc-features/twig-components

This example demonstrates how to prevent the `twig:joli:Img` component from automatically setting the `width` and `height` attributes by using the `skipAutoDimensions` attribute. The `loading` and `decoding` attributes will still be applied by default.

```twig
<twig:joli:Img
    path="example-image.png"
    variation="variation_name"
    alt="Alternative text"
    skipAutoDimensions
/>
```

--------------------------------

### Implement Custom Image Pre-processor with ImagineInterface

Source: https://mediabundle.jolicode.com/variations/pre-processors

This PHP code defines a custom pre-processor, OgImagePreProcessor, that resizes an image to fit within specified dimensions (1200x1000) and adds a yellow background canvas. It utilizes the ImagineInterface for image manipulation and extends AbstractPreProcessor.

```php
namespace App\Media\PreProcessor;

use Imagine\Image\Box;
use Imagine\Image\ImagineInterface;
use Imagine\Image\Point;
use JoliCode\MediaBundle\Binary\Binary;
use JoliCode\MediaBundle\PreProcessor\AbstractPreProcessor;
use JoliCode\MediaBundle\PreProcessor\PreProcessorInterface;
use JoliCode\MediaBundle\Variation\Variation;

readonly class OgImagePreProcessor extends AbstractPreProcessor implements PreProcessorInterface
{
    private const WIDTH = 1200;
    private const HEIGHT = 1000;

    public function __construct(
        private ImagineInterface $imagine,
    ) {
    }

    public function process(Binary $binary, Variation $variation): Binary
    {
        $image = $this->imagine->load($binary->getContent());

        $width = $image->getSize()->getWidth();
        $height = $image->getSize()->getHeight();

        if (!$width || !$height) {
            return $binary;
        }

        if ($width > self::WIDTH || $height > self::HEIGHT) {
            $ratio = $width / $height;

            if ($width > self::WIDTH) {
                $height = self::WIDTH / $ratio;
                $width = self::WIDTH;
            }

            if ($height > self::HEIGHT) {
                $width = self::HEIGHT * $ratio;
                $height = self::HEIGHT;
            }

            $image = $image->resize(new Box($width, $height));
        }

        $canvas = $this->imagine->create(
            new Box(self::WIDTH, self::HEIGHT),
            $image->palette()->color('#ffff00'),
        );

        $x = (self::WIDTH - $width) / 2;
        $y = (self::HEIGHT - $height) / 2;

        $canvas->paste($image, new Point($x, $y));

        return new Binary(
            $binary->getMimeType(),
            $binary->getFormat(),
            $canvas->get($binary->getFormat()),
        );
    }
}

```

--------------------------------

### Configure Serving Original Media via PHP in JoliMedia

Source: https://mediabundle.jolicode.com/storage/storage

This configuration enables serving original media files through the Symfony application. It requires setting `enable_serve_using_php` to `true` in the original storage configuration. Be aware that this can impact performance as all requests will pass through Symfony.

```yaml
joli_media:
    libraries:
        private:
            enable_auto_webp: false
            original:
                enable_serve_using_php: true
                flysystem: "filesystem.private.original.storage"
                url_generator:
                    strategy: folder
                    path: /media/original/
            cache:
                flysystem: "filesystem.private.cache.storage"
                url_generator:
                    strategy: folder
                    path: /media/cache/
            variations:
                content:
                    format: webp

```

--------------------------------

### Configure Assets for JoliMediaEasyAdminBundle

Source: https://mediabundle.jolicode.com/bridges/easy-admin

Provides the necessary configuration for the JoliMediaEasyAdminBundle assets within an EasyAdmin controller's `configureAssets` method. This ensures the media selector button functions correctly in the text editor.

```php
use Symfony\Component\Asset\PathPackage;
use Symfony\Component\Asset\VersionStrategy\JsonManifestVersionStrategy;

public function configureAssets(Assets $assets): Assets
{
    $package = new PathPackage(
        '/bundles/jolimediaeasyadmin',
        new JsonManifestVersionStrategy(__DIR__ . '/../../../public/bundles/jolimediaeasyadmin/manifest.json')
    );

    return $assets
        ->addCssFile($package->getUrl('joli-media-easy-admin.css'))
        ->addJsFile($package->getUrl('joli-media-easy-admin.js'))
    ;
}
```

--------------------------------

### Customize Post-processor Options for Variation

Source: https://mediabundle.jolicode.com/variations/post-processors

Illustrates overriding post-processor configurations for a specific media variation within a library. This enables fine-grained control over optimization for different media renditions, including disabling them entirely.

```yaml
joli_media:
    libraries:
        example:
            variations:
                my_variation:
                    post_processors:
                        jpegoptim:
                            max_quality: 70
                        mozjpeg:
                            quality: 75
                no_post_processing_variation:
                    post_processors:
                        jpegoptim: false
                        mozjpeg: false
```

--------------------------------

### Default Post-processor Configuration

Source: https://mediabundle.jolicode.com/variations/post-processors

Defines the default options for various image post-processors like gifsicle, jpegoptim, mozjpeg, oxipng, and pngquant. These settings balance compression and quality.

```yaml
joli_media:
    post_processors:
        gifsicle:
            options:
                optimize: 3
                lossy: 20
                colors: 256
        jpegoptim:
            options:
                strip_all: true
                progressive: true
                max_quality: 80
        mozjpeg:
            options:
                optimize: true
                progressive: true
                quality: 80
        oxipng:
            options:
                optimization: 4
                strip:
                    - all
                zopfli: false
        pngquant:
            options:
                quality: 75-85
                speed: 5
```

--------------------------------

### Configure Variation-Specific Pre-processors in JoliMediaBundle

Source: https://mediabundle.jolicode.com/variations/pre-processors

This configuration demonstrates how to define pre-processors for a specific media variation. These pre-processors are applied before the variation's transformers and after any global pre-processors.

```yaml
variations:
    real_estate:
        format: webp
        pre_processors:
            - App\Media\PreProcessor\ApplyWatermarkPreProcessor
            # - ...
        transformers:
            resize:
                width: 200
                height: 150
                mode: inside
            heighten:
                height: 600

```

--------------------------------

### Configure JoliMedia EasyAdmin Integration Settings

Source: https://mediabundle.jolicode.com/bridges/easy-admin

Customize the behavior of the JoliMedia integration within EasyAdmin by configuring options in the `joli_media_easy_admin.yaml` file. This includes settings for pagination, file uploads, and the visibility of various media management features.

```yaml
joli_media_easy_admin:
    pagination:
        per_page: 20
    upload:
        max_files: 10
        max_file_size: 20
        accepted_files:
            - image/*
            - video/*
            - application/pdf
    visibility:
        show_variations_stored: true
        show_variations_action_regenerate: true
        show_html_code: true
        show_markdown_code: true
```

--------------------------------

### Bulk Generate Media Variations

Source: https://mediabundle.jolicode.com/misc-features/commands

The joli:media:batch-convert command is used for bulk generation of media variations. It's beneficial for large media sets or when regenerating variations after configuration changes. It supports parallelization and chunk size options for performance.

```bash
$ php ./bin/console joli:media:batch-convert [options]
```

--------------------------------

### Configure JoliMedia EasyAdmin Routes

Source: https://mediabundle.jolicode.com/bridges/easy-admin

Define the routes for the media library in your Symfony routing configuration. This step ensures that the media library is accessible via a specific URL prefix within your EasyAdmin interface.

```yaml
# filepath: config/routes/joli_media.yaml
_joli_media_easy_admin:
    resource: "@JoliMediaEasyAdminBundle/src/Controller/"
    prefix: /admin/media
```

--------------------------------

### Expand Image with Background - YAML

Source: https://mediabundle.jolicode.com/variations/transformers

This transformer expands an image to a target width and height by adding a background color. It allows specifying dimensions, background color, and the position of the original image within the expanded area. Options include absolute pixel values, percentages, and keywords like 'start', 'center', 'end' for positioning.

```yaml
expand:
    width: 600
    height: 400
    background_color: red
    position_x: 100
    position_y: end
```

--------------------------------

### Configure Default Folder for Media Selector Widget

Source: https://mediabundle.jolicode.com/bridges/sonata-admin

Shows how to specify a default folder to be opened in the media browser when using the `MediaChoiceType`. If a media item is already selected, the widget will default to the folder containing that media.

```php
use JoliCode\MediaBundle\Bridge\SonataAdmin\Form\Type\MediaChoiceType;
use Sonata\AdminBundle\Form\FormMapper;

class ArticleAdmin extends AbstractAdmin
{
    protected function configureFormFields(FormMapper $formMapper)
    {
        $formMapper
            ->add('media', MediaChoiceType::class, [
                'required' => false,
                'folder' => 'my-folder',
            ])
        ;
    }
}
```

--------------------------------

### Implement Custom Media Access Voter in Symfony

Source: https://mediabundle.jolicode.com/bridges/sonata-admin

Provides an example of creating a custom security voter for the media library by extending `MediaVoter`. This allows for fine-grained control over user permissions for media actions like deletion, based on user identity, roles, or media properties. The custom voter must be aliased as `joli_media_admin.security.voter` to override the default.

```php
namespace App\Security\Voter;

use JoliCode\MediaBundle\Bridge\Security\Voter\MediaVoter as BaseMediaVoter;
use Symfony\Component\DependencyInjection\Attribute\AsAlias;
use Symfony\Component\Security\Core\User\UserInterface;

#[AsAlias(id: 'joli_media_admin.security.voter')]
class MediaVoter extends BaseMediaVoter
{
    protected function canDelete(?UserInterface $user, string $libraryName, string $path): bool
    {
        if ('john.doe@example.com' === $user?->getUserIdentifier()) {
            // John Doe can delete any media
            return true;
        }

        if ('public-storage' === $libraryName) {
            // only users with the ROLE_ADMIN role can delete media in the public-storage library
            return \in_array('ROLE_ADMIN', $user?->getRoles() ?? [], true);
        }

        // other users cannot delete media in the private folder
        return !str_starts_with($path, 'private/');
    }
}
```

--------------------------------

### Generate Source Tag with Joli:Source Component

Source: https://mediabundle.jolicode.com/misc-features/twig-components

Illustrates the usage of the `joli:Source` component to generate a single `<source>` tag within an HTML `<picture>` element. This component allows fine-grained control over media queries, sizes, and srcset attributes for specific image variations.

```twig
<twig:joli:Source
    media="{{ media }}"
    mediaAttr="(width > 1024px)"
    sizes="1024px"
    srcset="{{ {
        '1920w': 'variation-large',
        '2560w': 'variation-extra-large'
    } }}"
/>
```

--------------------------------

### Disable Post-processor Configuration

Source: https://mediabundle.jolicode.com/variations/post-processors

Demonstrates how to disable specific post-processors, such as jpegoptim and mozjpeg, by setting their `enabled` key to `false` or by directly assigning `false` to the post-processor name.

```yaml
joli_media:
    post_processors:
        jpegoptim:
            enabled: false
        mozjpeg:
            enabled: false
```

```yaml
joli_media:
    post_processors:
        jpegoptim: false
        mozjpeg: false
```

--------------------------------

### Generate Media Cache Files for Specific Files

Source: https://mediabundle.jolicode.com/misc-features/commands

The joli:media:convert command generates media cache files for specific files within a library. This is a more targeted approach compared to batch conversion.

```bash
$ php ./bin/console joli:media:convert
```

--------------------------------

### Configure High Pixel Density Images for Non-Resizing Variations in JoliCode MediaBundle

Source: https://mediabundle.jolicode.com/misc-features/twig-components

This section explains how to configure JoliCode MediaBundle to provide high pixel density images for variations that do not resize the original image, such as applying watermarks or changing formats. By setting `pixel_ratios` to `[1,2]` and using a resize operation with a 50% scale, you can ensure high-density versions are available even when the image dimensions remain the same.

```twig
// Example configuration within a variation processing chain:
// variation.add(new Resize(50, null, ['quality' => 85])); // Resize to 50% scale
// variation.add(new Watermark('/path/to/watermark.png'));

// In the template, ensure pixel_ratios is set if needed, though the resize operation handles density:
// <twig:joli:Img
//     path="image.png"
//     variation="{{ ['watermarked', 'watermarked_2x'] }}"
//     pixel_ratios="[1, 2]" // Explicitly define ratios if not inferred
// />
```

--------------------------------

### Integrate MediaSelector with Nested Forms in EasyAdmin

Source: https://mediabundle.jolicode.com/bridges/easy-admin

Illustrates how to use MediaChoiceField within a CollectionField for managing multiple media items. It also includes necessary asset configuration for nested forms, addressing a known EasyAdmin bug.

```php
use JoliCode\MediaBundle\Bridge\EasyAdmin\Field\MediaChoiceField;
use Symfony\Component\Asset\PathPackage;
use Symfony\Component\Asset\VersionStrategy\JsonManifestVersionStrategy;

class ArticleCrudController extends AbstractCrudController
{
    public function configureAssets(Assets $assets): Assets
    {
        // this should not be needed, but there is a bug in EA with assets in nested forms
        // see https://github.com/EasyCorp/EasyAdminBundle/issues/6127
        $package = new PathPackage(
            '/bundles/jolimediaeasyadmin',
            new JsonManifestVersionStrategy(__DIR__ . '/../../../public/bundles/jolimediaeasyadmin/manifest.json')
        );

        return $assets
            ->addCssFile($package->getUrl('joli-media-easy-admin.css'))
            ->addJsFile($package->getUrl('joli-media-easy-admin.js'))
        ;
    }

    public function configureFields(string $pageName): iterable
    {
        return [
            CollectionField::new('images')
                ->setHelp('Add some media to illustrate this article')
                ->renderExpanded(true)
                ->useEntryCrudForm(ArticleImagesCrudController::class)
                ->setEntryIsComplex()
        ];
    }
}
```

--------------------------------

### Generate Media URLs using Media Resolver Service (PHP)

Source: https://mediabundle.jolicode.com/misc-features/url-generation

Shows how to obtain Media and MediaVariation objects using the media 'Resolver' service and then generate their URLs. This is the recommended approach for most use cases.

```php
$resolver = $this->get('joli_media.resolver');

// Resolve media with library name
$media = $resolver->resolve('example-image.png', 'library_name');
echo $media->getUrl();

// Resolve media variation with library and variation names
$mediaVariation = $resolver->resolve('example-image.png', 'library_name', 'variation_name');
echo $mediaVariation->getUrl();

// Omitting library name when only one library is defined
$media = $resolver->resolve('example-image.png');
$mediaVariation = $resolver->resolve('example-image.png', null, 'variation_name');
echo $media->getUrl();
echo $mediaVariation->getUrl();
```

--------------------------------

### Imagine Processor Options for Image Manipulation

Source: https://mediabundle.jolicode.com/variations/processors

Configures the Imagine processor for image conversions using the Imagine library. Supports quality settings for JPEG and PNG, and a general quality option. It allows specifying the driver (gd, imagick, gmagick).

```yaml
imagine:
    options:
        jpeg_quality: 80
        png_quality: 80
        quality: 80

```

--------------------------------

### Docker Operations with Castor

Source: https://mediabundle.jolicode.com/tests-and-qa-tooling

Commands for interacting with Docker, including building the test infrastructure and opening a shell within the test container. These are essential for managing the testing environment.

```bash
docker:build      Build the test infrastructure
docker:builder    Open a shell (bash) into the tests container
```

--------------------------------

### List All Castor Tasks

Source: https://mediabundle.jolicode.com/tests-and-qa-tooling

Displays all available tasks that can be executed using the Castor task runner. This command is useful for discovering the range of automatable operations within the project.

```bash
$ castor
```
Tokens:
Raw