Locale Bundle Laravel Package

Getting Started

• Know what you're adopting first. This bundle targets the Symfony 4/5 era (last tagged release Dec 2020, PHP 7.x constraints). Before anything else, open composer.json and confirm the php/symfony/* requirements match your project. On Symfony 6/7 you will likely need to fork.
• Install: composer require phospr/locale-bundle. With Flex it should auto-register; otherwise add Phospr\LocaleBundle\PhosprLocaleBundle::class => ['all' => true] to config/bundles.php.
• Configure: create config/packages/phospr_locale.yaml. Start from the bundle's DependencyInjection/Configuration.php — with 0 stars the README is thin, and that file is the authoritative list of keys (available locales, default/fallback locale, session persistence toggles).
• Where to look first: src/EventListener/ for the kernel.request subscriber (that's where locale is actually set on the Request) and src/ for the negotiator service that parses Accept-Language. Those two classes are ~90% of the bundle's behavior.
• First use case: drop it in and let it negotiate the locale from Accept-Language on each request so $request->getLocale() is already correct when your controllers run, falling back to framework.default_locale. Verify with a quick functional test that sends an Accept-Language header and asserts the locale — if that passes, the bundle is doing its one job.

Implementation Patterns

• Request negotiation + session persistence. The standard flow: the kernel.request listener reads Accept-Language, picks the best match from your allowlist, and writes it to the session so it survives redirects and subsequent requests. Rely on this rather than calling the negotiator by hand in controllers.
• Explicit locale switcher. Add a route like /locale/{locale} with a controller that validates locale against your configured allowlist, writes it to the session, and redirects back to the referer. The listener then honors it on the next request. Never trust the path segment without the allowlist check.
• Single source of truth for locales. Keep one available_locales array in config and inject it into both the bundle and any validator/switcher form. Drift between "what the listener accepts" and "what your UI offers" is the most common bug in this pattern.
• Integration with symfony/translation. Make sure the bundle's chosen locale lands on $request->setLocale(); the translator reads that, and falls back to framework.default_locale otherwise. If translations are stuck on the default, this link is broken.
• First-visit guess, URL for the rest. Session/Accept-Language negotiation doesn't change URLs, which is bad for SEO and sharing. Day-to-day, prefer Symfony's built-in /{_locale}/... route prefix with a _locale requirement, and use this bundle only to guess the locale for first-time visitors before redirecting them to a prefixed URL.
• Testing. Unit-test the negotiator directly with mocked Accept-Language headers (fast, no kernel). Add one functional test per locale through $client->request(..., server: ['HTTP_ACCEPT_LANGUAGE' => ...]) to catch listener-priority regressions.

Gotchas and Tips

• Maintenance risk is the headline. 0 stars, 0 dependents, dormant since 2020. Pin an exact version, and budget for vendoring or forking. Don't build critical flows on top of it.
• You may not need the dependency at all. FrameworkBundle already ships LocaleListener, and Accept-Language parsing is a few lines with AcceptHeader/getLanguages() from symfony/http-foundation. For a single-locale-plus-fallback setup, hand-rolling is often less risk than an unmaintained bundle.
• Locale "not changing" checklist: (1) your own kernel.request listener has higher/lower priority than the bundle's — inspect with bin/console debug:event-dispatcher kernel.request; (2) session isn't started or the cookie is dropped; (3) stale cache — run cache:clear; (4) a CDN/proxy strips or ignores Accept-Language.
• Cache poisoning. If response content varies by negotiated locale, you must emit Vary: Accept-Language (and not cache session-dependent locales in a shared cache), or users will see each other's language.
• Validate the session value on read, not just on write. A stale or manually edited session value should be checked against the allowlist every time, otherwise you render an unsupported locale or hit missing translation catalogs.
• Extension points. The negotiator and listener are ordinary services — decorate them or override the service id in services.yaml rather than forking the repo. If a knob isn't exposed in config, a small compiler pass is cleaner than patching DependencyInjection/.
• Locale is presentation only. Never branch authorization or business logic on the negotiated locale; it comes from a client-controlled header.