Sulu Translations Bundle Laravel Package

Getting Started

• Install with Composer: composer require phpro/sulu-translations-bundle. As of 1.2.0 the floor is PHP 8.4 — verify php -v on your machine, your Docker image, and every CI matrix entry before you start, because composer install will simply refuse on 8.3.
• This is a Sulu CMS bundle (Symfony), not a Laravel package. There is no composer.json extra.laravel.providers entry, no auto-discovery, no publishable config. If you are in a genuine Laravel app you have already hit the wrong repo — the only realistic consumer is a Sulu/Symfony application.
• Register the bundle in config/bundles.php:

  Phpro\SuluTranslationsBundle\SuluTranslationsBundle::class => ['all' => true],
  

  then let Sulu's admin build pick it up. Nothing else is needed for a first smoke test.
• Where to look first: DependencyInjection/Configuration.php for the config tree, Resources/config/ for service wiring, and bin/console debug:container --tag=sulu.admin to confirm your services landed. Check the Sulu admin UI afterwards to see whether the translation screens you expect actually appear.
• First use case: open the Sulu admin, navigate to the translations area the bundle decorates, and confirm you can list and edit translations. Only after that works should you try calling its services from your own code.

Implementation Patterns

• Inject services, don't reach for facades. The bundle exposes Symfony services. Wire them into your own services/controllers via constructor injection or services.yaml bind:. There is no Translations:: facade equivalent.
• Configuration lives in config/packages/. Add a sulu_translations: (or bundle-prefixed) YAML block matching the keys in the bundle's Configuration.php. Do not look for a config/translations.php artisan-published file — it does not exist.
• Treat it as a translation read/write layer, not a full i18n solution. Typical day-to-day flow: pull existing translation keys for a locale, feed them into a Sulu admin view or an import command, persist changes back through the bundle's service rather than touching storage directly.
• Import/export workflows are the natural integration point. Write an Artisan-style equivalent as a Symfony command (bin/console app:translations:sync) that pulls from the bundle's service and writes to your canonical source (XLIFF, JSON, or a DB table). Keeping the bundle on one side of that boundary means the 8.4 bump (and whatever comes next) stays contained.
• Decorate rather than fork. If you need extra validation or logging around translation writes, use Symfony service decoration:

  App\Translations\LoggingTranslator:
      decorates: phpro_sulu_translations.some_service_id
  

  This survives minor-version upgrades, unlike editing vendor code.
• Testing. Unit-test your own decorators and commands with the service mocked; use Sulu's functional test base (or an application-level kernel boot) only for the integration seam. Don't write tests that assert on the bundle's internal service IDs unless you are prepared to chase them each release.

Gotchas and Tips

• The 1.2.0 change is a hard break for PHP 8.3 and below. "php": "~8.4.0" (or similar) means the upgrade is all-or-nothing. Budget a platform bump first; if your host or a dependent package pins below 8.4 you are stuck on 1.1.0. There is no compatibility shim.
• azjezz/psl → php-standard-library is mostly transparent, but check for duplicates. The fork retains the Psl\ namespace, so the bundle's internal code needs no rewrite. However, composer why azjezz/psl and composer show | grep -i psl before and after upgrading: if another dependency still pulls the original, you can end up with both packages installed and conflicting function/class definitions at autoload time. Symptoms are "cannot redeclare" or "class not found" errors that look unrelated.
• Don't type-hint against Psl\* in your own code if you consume the bundle's values (e.g. a collection returned from a service). That interface is the one that just moved vendors; stay on plain arrays/iterables at the boundary.
• Clear caches between bundle and platform upgrades. Symfony's compiled container caches service signatures; after a PHP minor/major bump also run composer dump-autoload. Most "class not found" reports after this release are stale var/cache rather than real bugs.
• Debugging translation problems: bin/console debug:container --show-private | grep -i translation to find the real implementation behind an alias, and enable the Symfony profiler's translation panel to see which domain/locale is actually resolving.
• No Laravel parity. Auto-discovery, php artisan vendor:publish, facades, app() resolution, and Eloquent-backed translations are all absent. If your team is Laravel-first, factor in the Sulu/Symfony learning curve — that, not the 8.4 bump, is the real adoption cost.
• Upgrade sequencing: bump PHP to 8.4 → composer update phpro/sulu-translations-bundle → composer dump-autoload → clear cache → run Sulu admin smoke test. Run this on a branch before touching production; the platform bump is the risky part, not the bundle code.