Sulu Translated Media Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Unchanged Core Design, Broadened Platform Reach: Release 3.2.0 does not alter the bundle's architecture — it still extends Sulu's native Media entity via the MediaTranslations table and MediaTranslationsAwareInterface, ships sulu_translated_media_url() / sulu_translated_media_urls(), and adds the "Additional Data" admin tab. The change is a compatibility certification: the bundle now targets Sulu 3.1 and Symfony 8.1 in addition to the previously assessed Sulu 3.0.x / Symfony 7.x baseline.
• Two Supported Tracks: The bundle must now be treated as having a dual support matrix rather than a single target. Architectural fit is unchanged on the Symfony 7 track; on the Symfony 8.1 track the bundle benefits from the newer framework's typed service contracts and cache abstractions, but inherits that track's stricter deprecation posture.
• SEO/Localization Value Unchanged: Locale-specific filenames (/uploads/product-de.jpg), WebP-aware responsive output, and the zero-configuration auto-registration of sulu_media.objects.media.model and sulu_admin resources all remain intact. No re-architecture is required to adopt 3.2.0.
• Vendor Momentum Signal: Shipping Sulu 3.1 support promptly is a positive maintenance signal — the bundle is tracking the CMS's release train rather than lagging it. That materially reduces the "abandoned dependency" risk profile versus the prior assessment.

Integration Feasibility

• Installation Surface Unchanged: Composer install, bundle registration in config/bundles.php, route import, and a schema migration. No new services, entities, or configuration files are introduced by 3.2.0.
• Platform Floor Moves on the 8.1 Track: Symfony 8.1 implies a materially higher PHP runtime floor than the PHP 8.2 baseline previously documented (Symfony 8.x requires PHP 8.4+). Teams on PHP 8.2/8.3 must either remain on the Symfony 7 / Sulu 3.0 track or schedule a PHP upgrade as a prerequisite — not a follow-on task.
• Compatibility Gap to Close: The release jumps from 3.0.5 to 3.2.0, meaning 3.1.x release notes were not supplied. Before planning an upgrade we need the full changelog for the intervening minor to confirm whether 3.1.0 contained behavioral changes (Twig signature changes, FormatManager compiler-pass ordering, cache key format) that 3.2.0 inherited.
• Backward Compatibility (Assumed, Unverified): A minor-version bump implies no intentional breaking changes. The FormatManager compiler-pass replacement and the unchanged sulu_media_url() fallback should still hold, but this must be verified against a staging build rather than assumed.

Technical Risk

• Dependency Cascade: Adopting 3.2.0 on Symfony 8.1 pulls Doctrine ORM, Twig, and every other Sulu-adjacent bundle onto the Symfony 8 line. Third-party media bundles and storage adapters (S3, image processing) are the most likely blockers — they typically lag framework majors by months.
• Sulu 3.1 Behavioral Deltas: Sulu 3.1 may have changed media formatting, admin asset building, or cache contracts. The bundle's FormatCacheInterface usage (introduced in 3.0.3) is the highest-risk integration point; cache key structure must be re-validated on 3.1.
• Migration/Upgrade Ordering: The database schema (me_media_translations) is not reported as changed, but doctrine:schema:update --force on a newer Doctrine/Symfony stack can generate unexpected diffs. Schema diff review, not blind --force, is required.
• Admin Route Scope: The custom /admin/api prefix risk is unchanged and should be re-tested on the 3.1 admin routing stack, which may have tightened route loading.
• Performance Profile: Unchanged — one or more lookups against me_media_translations per rendered media item. The locale index recommendation stands and should be confirmed present before any traffic ramp.
• Version Pinning Discipline: With two supported tracks in the wild, unpinned composer require is now a genuine hazard. Pin to ^3.2 deliberately and record which track each environment rides.

Key Questions

1. Release Scope
   • What shipped in 3.1.0? Was 3.2.0 purely a compatibility bump, or does it carry fixes/behavior changes inherited from 3.1.x?
   • Are there deprecations introduced in 3.2.0 tied to the Symfony 8 migration (e.g., service definitions, cache adapter usage)?
2. Support Matrix
   • Does 3.2.0 still support Sulu 3.0.x / Symfony 7.x, or is it a hard cut-over to 3.1 / 8.1?
   • What is the minimum PHP version declared in composer.json for 3.2.0, and does it differ per track?
3. Locale Handling (unchanged, still open)
   • Default-locale resolution when app.request.locale is unavailable (CLI, API, queue workers)?
   • Fallback chain support (de → en) when a translation row is missing?
4. URL Generation & Caching
   • Are translated URLs cacheable in Varnish/Symfony Cache, and has the cache key format changed alongside the FormatCacheInterface usage on 3.1?
   • Does sulu_translated_media_urls() still emit srcset-compatible URLs for both default and WebP formats?
5. Media Processing
   • Original filenames preserved at /uploads/original/... while serving translated paths?
   • File-system permission handling for generated translated paths — any change under the new stack?
6. Admin Workflow
   • Bulk-editing of translations (Sulu Data Importer) supported?
   • Validation rules for SEO filenames (length, URL-safe characters)?
7. Future-Proofing
   • Is Sulu 4.x on the vendor's roadmap, and is 3.2.0 a deliberate stepping stone toward it?
   • Any plans for CDN integration or purge hooks for translated paths?

Integration Approach

Stack Fit

• Greenfield / New Builds: Start directly on Sulu 3.1 + Symfony 8.1 + PHP 8.4+ with bundle 3.2.0. This is now the cleanest path and avoids a second migration later.
• Existing Sulu 3.0 / Symfony 7 Estates: Stay on 3.2.0 but on the Symfony 7 track initially; treat the Symfony 8.1 move as a separate, scheduled platform project rather than bundling it into the bundle upgrade.

Migration Path

1. Pre-Installation
   • Capture the full 3.1.x + 3.2.0 changelog from Alengo releases; confirm no breaking changes.
   • Backup database and uploads/ directory.
   • Record current pinned versions of sulu/sulu, symfony/*, doctrine/orm, and all media-adjacent third-party bundles.
2. Bundle Upgrade (same platform)

   composer require alengo/sulu-translated-media-bundle:^3.2
   

   • Run on the existing Symfony 7 / Sulu 3.0 platform first to isolate bundle-level regressions from framework-level ones.
3. Database Verification

   bin/adminconsole doctrine:schema:update --dump-sql
   

   • Review the diff before applying. Apply with --force only after confirming the diff is empty or limited to expected changes.
4. Platform Upgrade (separate change window)
   • Bump Sulu to 3.1, then Symfony to 8.1, then PHP to the required floor — in that order, with a deployable, revertible build at each step.
   • Re-run the admin asset build and clear var/cache.
5. Configuration
   • No new config required for core functionality. Re-verify the /admin/api route prefix does not collide with existing admin routes on the 3.1 routing stack.
6. Post-Installation Validation
   • Smoke-test translated URLs across all supported locales, including a missing-translation case to confirm fallback behavior.
   • Confirm WebP generation and fallback still work end-to-end.
   • Verify admin "Additional Data" tab loads and saves.

Compatibility

• Third-Party Media Bundles: The single largest adoption risk on the Symfony 8.1 track. Inventory every bundle that touches Sulu media, image processing, or storage (S3/GCS adapters) and confirm Symfony 8 support before committing.
• Caching Layers: Re-validate FormatCacheInterface behavior, HTTP caches (Varnish/Nginx), and OPcache under the new stack. Cache key formats are the most likely silent regression.
• Legacy Templates: Existing sulu_media_url() calls continue to work; migration to sulu_translated_media_url() remains opt-in and template-by-template.
• Tooling: Confirm CI matrix covers both tracks if you maintain more than one environment on different versions.

Sequencing

1. Phase 0: Discovery (2–3 days) — obtain 3.1.x changelog, confirm composer.json constraints, inventory third-party Symfony 8 readiness.
2. Phase 1: Bundle Upgrade on Current Platform (1 week) — 3.2.0 on existing Sulu 3.0 / Symfony 7; full regression on admin UI and translated URL generation.
3. Phase 2: Platform Upgrade (2–3 weeks, gated on Phase 0 findings) — PHP floor → Sulu 3.1 → Symfony 8.1, staged with rollback points.
4. Phase 3: Frontend Rollout (1 week) — template migration to translated URL helpers, <picture>/WebP adoption.
5. Phase 4: Performance & Monitoring (ongoing) — index verification on me_media_translations.locale, cache warm-up, 404 and query-load dashboards.

Operational Impact

Maintenance

• Two-Track Support Burden: Until the Symfony 8.1 ecosystem matures, the team may need to support environments on both tracks. Document explicitly which environment rides which version triple (Sulu / Symfony / PHP) and enforce it in composer.json pins.
• Release Cadence: The jump from 3.0.5 (June 2026) to 3.2.0 indicates an active cadence. Subscribe to Alengo release notifications and review each minor for deprecations rather than only majors.
• Dependency Hygiene: Symfony 8.1 adoption accelerates the deprecation clock across the stack. Budget recurring time for deprecation cleanup in adjacent bundles, not just this one.
• Database Schema: No schema change reported in 3.2.0, but continued vigilance on me_media_translations migrations remains necessary; prefer explicit migrations over --force in production.
• Logging: Retain custom logging for failed translated URL generation and missing-locale fallbacks; add a log line for cache-key misses if the format cache layer changed.

Support

• Troubleshooting Playbook:
  • Broken translated URLs → inspect me_media_translations for the locale row; check fallback configuration.
  • Admin UI failures on Sulu 3.1 → verify /admin/api prefix and admin asset build output.
  • WebP failures → confirm the image processing pipeline on the upgraded stack; this is the most likely place a framework major surfaces as a user-visible bug.
  • Upgrade-specific → reproduce on the Symfony 7 track first to determine whether the fault is the bundle or the platform.
• Documentation Gaps: Build internal runbooks for (a) upgrading the bundle within a track, (b) crossing tracks, (c) bulk-updating translations via Data Importer, and (d) rolling back a failed Symfony 8 migration.
• Vendor Support: Still GitHub-issues-only. Given the dual-track matrix, consider designating an internal owner for the fork/watch decision, and be prepared to backport a patch if a Symfony 8.1 incompatibility surfaces in a third-party dependency.

Scaling

• Database Load: Unchanged — per-request lookups against me_media_translations. Confirm indexes on locale and the media join key exist after the platform upgrade; schema tooling on a new Doctrine version can silently alter index naming.
• Query Caching: Cache translated filenames in Symfony Cache / Redis. On Symfony 8.1, re-verify cache adapter configuration and pool namespacing; a misconfigured pool manifests as a performance regression, not an error.
• File System: Translated paths increase directory entry count. Monitor disk I/O; consider symlinking translated paths to originals if storage duplication grows.
• CDN: If fronting with a CDN, translated paths must be cacheable and purge logic must account for locale edits. Test edge behavior explicitly on the upgraded stack, since cache-key changes are the most likely silent breakage.
• High Availability: Validate read-replica behavior for translated-metadata queries; load-test simultaneous multi-locale requests before peak traffic.

Failure Modes

• Silent Fallback to Untranslated URLs — missing locale rows cause sulu_translated_media_url() to return the default path. SEO impact without any error signal; mitigate with logging and a locale-coverage report.
• Cache Key Collision After Upgrade — if the format cache key structure changed between 3.0.x and 3.2.0, stale entries can serve the wrong locale's asset. Mitigate with a full cache flush as a mandatory upgrade step.
• Third-Party Bundle Incompatibility on Symfony 8.1 — most likely at container compile time; caught in CI, not production, if the CI matrix includes the Symfony 8 track.
• Schema Drift from --force — applying an unreviewed Doctrine diff on a new ORM version can drop or rename indexes. Mitigate by always reviewing --dump-sql output first.
• Admin Route Collision — custom /admin/api prefix conflicting with existing admin routes on the Sulu 3.1 routing stack; surfaces as a 404 or 500 in the admin, not the frontend.
• PHP Runtime Mismatch — deploying 3.2.0 to an environment below the Symfony 8.1 PHP floor fails at Composer resolution or container warm-up. Mitigate by pinning the PHP platform requirement in composer.json rather than relying on host configuration.

Ramp-Up

• Engineering: Low for the bundle itself (unchanged API surface); moderate-to-high for the platform upgrade, which is the real effort in 3.2.0 adoption. Estimate 2–3 weeks of senior Symfony/Sulu engineer time for the Symfony 8.1 crossing, contingent on third-party readiness.
• Editorial: No new training required — the "Additional Data" tab behaves as before. Refresh only the guidance on translated filename conventions and fallback behavior.
• DevOps: Medium — new PHP runtime image, updated CI matrix covering both tracks, cache topology re-validation, and a rehearsed rollback for the platform migration.
• Product/SEO Stakeholders: Should be briefed on the upgrade timeline, since translated URL stability during the platform migration is a direct SEO risk and worth a freeze window around the cut-over.