Getting Started

Minimal Steps

Installation:
```
composer require alengo/sulu-translated-media-bundle:^3.0.5
```
Register the bundle in config/bundles.php and import admin routes in config/routes/sulu_admin.yaml.

Database Migration:

bin/adminconsole doctrine:schema:update --force

First Use Case: Upload a media file in Sulu CMS admin. Navigate to the "Additional Data" tab to set:
- seoFilename (e.g., red-shoes-de.jpg for German locale)
- title and description per locale
- Optional flags (verifyDownload, aiGenerated).

Render in Twig:

{{ sulu_translated_media_url(media, '800x', app.request.locale) }}

Implementation Patterns

Core Workflow

Media Upload & Translation:
- Upload media via Sulu’s admin.
- Use the "Additional Data" tab to define locale-specific metadata (e.g., seoFilename, title, description).
- Example: A product image might have seoFilename = "sneakers-en.jpg" for English and schuhe-de.jpg for German.

URL Generation in Twig:

Single URL:

{{ sulu_translated_media_url(media, '800x', app.request.locale) }}

Output: /uploads/schuhe-de_800x.jpg (if locale is de).

Multi-format URLs (for <picture> tags):

{% set urls = sulu_translated_media_urls(media, '800x', app.request.locale) %}
<picture>
    <source srcset="{{ urls.webp }}" type="image/webp">
    <img src="{{ urls.default }}">
</picture>

Integration with Sulu’s Media System:
- Extend the provided Entity\Media or use it directly.
- Implement MediaTranslationsAwareInterface or MediaAdditionalDataInterface in custom media entities for additional fields.

Format Management:

Override default formats via TranslatedFormatManager (e.g., add custom WebP presets).

Example:

# config/packages/translated_media.yaml
sulu_translated_media:
    formats:
        - name: 'webp_800x'
          extension: 'webp'
          mime_type: 'image/webp'
          quality: 80

Admin Customization:

Extend the "Additional Data" tab by overriding the admin resource:

# config/packages/sulu_admin.yaml
sulu_admin:
    resources:
        media:
            admin:
                groups:
                    additional_data:
                        label: 'Custom Additional Data'
                        icon: 'cog'

Gotchas and Tips

Pitfalls

Locale Fallback:
- If no seoFilename is set for the current locale, the bundle falls back to the default locale (configured in Sulu). Ensure default locale translations exist.
- Debug missing filenames with:
```
$media->getSeoFilename(app.request->getLocale()); // Returns null if unset
```
File Permissions:
- The bundle dynamically generates symlinks for translated filenames. Ensure the uploads/ directory is writable by the web server:
```
chmod -R 775 var/uploads
```
Format Cache & Memoization:
- The FormatCacheInterface (introduced in v3.0.3) now includes memoization for improved performance. Clear cache after adding new formats:
```
bin/adminconsole cache:clear
```
- Memoization ensures format configurations are cached in memory, reducing redundant database queries.
WebP Support:
- Requires imagick or gd PHP extensions with WebP support. Verify with:
```
php -m | grep imagick
```
- If WebP fails, check sulu_translated_media_urls() output for null in the webp key.
Database Schema:
- The me_media_translations table is auto-created, but manual schema updates may fail if Sulu’s base schema changes. Backup before running migrations.

Debugging Tips

Check Generated URLs:
- Use Symfony’s profiler (/_profiler) to inspect the sulu_translated_media_url() function call and verify the resolved path.
Admin Tab Missing:
- Ensure the admin routes are imported (TranslatedMediaBundle in sulu_admin.yaml).
- Clear cache if the tab doesn’t appear:
```
bin/adminconsole cache:clear
```
Symlink Issues:
- If translated filenames return 404, check symlinks in uploads/:
```
ls -la var/uploads | grep -E 'schuhe-de\.jpg|red-shoes-en\.jpg'
```
- Manually recreate symlinks if corrupted:
```
php bin/adminconsole sulu:media:generate-symlinks
```
Memoization Debugging:
- To verify memoization is working, inspect the FormatCache service:
```
bin/adminconsole debug:container sulu_translated_media.format_cache
```
- If formats aren’t being cached as expected, ensure the cache:clear command was run after configuration changes.

Extension Points

Custom Media Entity:

Extend Entity\Media to add project-specific fields:

use Alengo\SuluTranslatedMediaBundle\Entity\Media as BaseMedia;

class CustomMedia extends BaseMedia {
    // Add custom fields here
}

sulu_media:
    objects:
        media:
            model: App\Entity\CustomMedia

Override Twig Functions:

Replace the default Twig functions in config/packages/twig.yaml:

twig:
    globals:
        sulu_translated_media_url: '@TranslatedMediaBundle/twig/sulu_translated_media_url'
        sulu_translated_media_urls: '@TranslatedMediaBundle/twig/sulu_translated_media_urls'

Format Manager:

Replace the TranslatedFormatManager entirely by binding a custom service:

# config/services.yaml
services:
    App\Service\CustomFormatManager:
        tags: ['sulu_translated_media.format_manager']

Admin Tab Customization:

Override the admin resource template:

{# templates/sulu_admin/media/additional_data.html.twig #}
{% extends '@TranslatedMediaBundle/admin/media/additional_data.html.twig' %}
{% block additional_fields %}
    {{ parent() }}
    <div class="field">
        <label>Custom Field</label>
        <input type="text" name="custom_field">
    </div>
{% endblock %}

Memoization Customization:

To customize memoization behavior (e.g., TTL or cache pool), bind a custom FormatCache service:

# config/services.yaml
services:
    App\Cache\CustomFormatCache:
        arguments:
            $cachePool: '@cache.app'
            $ttl: 3600 # Custom TTL in seconds
        tags: ['sulu_translated_media.format_cache']

Sulu Translated Media Bundle Laravel Package