Getting Started

Minimal Setup

Installation:
```
composer require bukashk0zzz/liip-imagine-serialization-bundle
```
Ensure liip/imagine-bundle and jms/serializer-bundle are already installed.

Enable Bundle: Add to config/bundles.php:

Bukashk0zzz\LiipImagineSerializationBundle\LiipImagineSerializationBundle::class => ['all' => true],

Configure: Update config/packages/liip_imagine.yaml to include serialization filters:

filters:
    my_thumbnail:
        # ... existing config ...
        serialization: true  # Enable serialization for this filter

First Use Case: Annotate an entity property with @SerializedName and use LiipImagineFilter in a serializer context:

use Bukashk0zzz\LiipImagineSerializationBundle\Serializer\Filter\LiipImagineFilter;

class ProductSerializer extends AbstractSerializer
{
    public function serialize($data, $format, array $context = [])
    {
        $context['filters'] = ['my_thumbnail'];
        return parent::serialize($data, $format, $context);
    }
}

Implementation Patterns

Core Workflow

Filter Configuration: Define filters in liip_imagine.yaml with serialization: true to enable dynamic image generation during serialization.

Serializer Integration: Use the LiipImagineFilter in your serializers:

use Bukashk0zzz\LiipImagineSerializationBundle\Serializer\Filter\LiipImagineFilter;

$serializer = $this->container->get('serializer');
$result = $serializer->serialize($entity, 'json', [
    'filters' => [new LiipImagineFilter('my_thumbnail')]
]);

Dynamic Filtering: Pass filter names dynamically via context:

$context = [
    'filters' => ['thumbnail_100', 'thumbnail_200'],
    'liip_imagine' => ['format' => 'webp']
];

Entity Annotations: Use @Groups and @SerializedName to control serialization:

use Symfony\Component\Serializer\Annotation\Groups;
use Symfony\Component\Serializer\Annotation\SerializedName;

class Product
{
    #[SerializedName('image_url')]
    #[Groups(['api'])]
    private $image;
}

API Platform Integration: For API Platform projects, configure serialization_context in resources:

# config/api_platform/resources.yaml
App\Entity\Product:
    attributes:
        serialization_context:
            groups: ['api']
            filters: ['my_thumbnail']

Advanced Patterns

Custom Filter Classes: Extend LiipImagineFilter for reusable logic:

use Bukashk0zzz\LiipImagineSerializationBundle\Serializer\Filter\LiipImagineFilter;

class CustomImagineFilter extends LiipImagineFilter
{
    public function __construct(string $filterName, array $options = [])
    {
        parent::__construct($filterName, array_merge($options, ['watermark' => true]));
    }
}

Event-Based Filtering: Use LiipImagineSerializationEvents to modify behavior:

$dispatcher->addListener(
    LiipImagineSerializationEvents::PRE_FILTER,
    function (PreFilterEvent $event) {
        $event->setFilterOptions(['quality' => 80]);
    }
);

Caching Strategies: Leverage Symfony’s cache system for serialized images:
```
# config/packages/liip_imagine.yaml
cache: cache.adapter.redis
```

Conditional Serialization: Use Normalizer interfaces to conditionally apply filters:

use Symfony\Component\Serializer\Normalizer\ContextualNormalizerInterface;

class ConditionalImagineNormalizer implements ContextualNormalizerInterface
{
    public function normalize($object, $format = null, array $context = [])
    {
        if ($context['is_admin'] ?? false) {
            $context['filters'] = ['admin_thumbnail'];
        }
        return $this->serializer->serialize($object, $format, $context);
    }
}

Gotchas and Tips

Common Pitfalls

Filter Not Found:
- Issue: Filter "my_filter" does not exist error.
- Fix: Ensure the filter is defined in liip_imagine.yaml and serialization: true is set.
- Debug: Run php bin/console debug:liip-imagine:filter to list available filters.
Circular References:
- Issue: Serialization fails with circular reference errors when entities reference each other.
- Fix: Use @MaxDepth annotation or configure max_depth in serializer context:
```
$context = ['max_depth' => 2];
```
File Permissions:
- Issue: Generated images fail to save due to permission issues.
- Fix: Ensure the cache directory in liip_imagine.yaml is writable:
```
cache: '%kernel.project_dir%/var/cache/liip_imagine'
```
Missing Dependencies:
- Issue: Class "LiipImagineFilter" not found.
- Fix: Verify bukashk0zzz/liip-imagine-serialization-bundle is installed and enabled.

Debugging Tips

Enable Debug Mode: Set debug: true in liip_imagine.yaml to log filter execution:
```
debug: true
```

Log Serialization Context: Dump the context to verify filter inclusion:

$context = $serializer->getContext();
dump($context['filters']); // Check if your filter is present

Check Cache: Clear cache after configuration changes:
```
php bin/console cache:clear
```
Validate YAML: Use symfony/validator to validate liip_imagine.yaml:
```
php bin/console debug:config liip_imagine
```

Configuration Quirks

Default Filter Behavior:
- Filters without serialization: true are ignored during serialization, even if referenced.
Format Overrides:
- The format option in liip_imagine.yaml can be overridden per-serialization via context:
```
$context = ['liip_imagine' => ['format' => 'jpg']];
```
Priority in Normalizers:
- The LiipImagineFilter runs after default normalizers. Use @Groups to control precedence.

API Platform Specifics:

In API Platform, ensure serialization_context is merged correctly with global settings:

# config/api_platform/resources.yaml
App\Entity\Product:
    attributes:
        serialization_context:
            groups: ['api']
            filters: ['my_thumbnail']
            liip_imagine: { format: 'webp' }

Extension Points

Custom Normalizers: Create a custom normalizer to preprocess data before LiipImagineFilter:

use Symfony\Component\Serializer\Normalizer\NormalizerInterface;

class ImaginePreprocessNormalizer implements NormalizerInterface
{
    public function normalize($object, $format = null, array $context = [])
    {
        if ($object instanceof Product) {
            $object->setImagePath($this->generatePath($object->getImage()));
        }
        return $object;
    }
}

Event Subscribers: Subscribe to LiipImagineSerializationEvents for dynamic behavior:

use Bukashk0zzz\LiipImagineSerializationBundle\Event\PreFilterEvent;
use Bukashk0zzz\LiipImagineSerializationBundle\Event\LiipImagineSerializationEvents;

$dispatcher->addListener(
    LiipImagineSerializationEvents::PRE_FILTER,
    function (PreFilterEvent $event) {
        if ($event->getFilterName() === 'thumbnail') {
            $event->setFilterOptions(['size' => [200, 200]]);
        }
    }
);

Compiler Passes: Modify bundle behavior via compiler passes (e.g., to add default filters):

use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
use Symfony\Component\DependencyInjection\ContainerBuilder;

class AddDefaultFiltersPass implements CompilerPassInterface
{
    public function process(ContainerBuilder $container)
    {
        $definition = $container->findDefinition('liip_imagine.serialization.filter_collection');
        $definition->addMethodCall('addFilter', ['default', new LiipImagineFilter('thumbnail')]);
    }
}

Twig Integration: Use the bundle in Twig templates via the serializer

Liip Imagine Serialization Bundle Laravel Package