Getting Started

Minimal Setup

Installation:

composer require arthem/locale-bundle

Enable the bundle in config/bundles.php:

return [
    // ...
    Arthem\LocaleBundle\ArthemLocaleBundle::class => ['all' => true],
];

Configure Locales: Define supported locales in config/packages/arthem_locale.yaml:
```
arthem_locale:
    locales:
        - en
        - fr
        - fr_CA
```

First Use Case:

Switching Locales Dynamically: Inject the LocaleListener into a controller/service:

use Arthem\LocaleBundle\EventListener\LocaleListener;

public function __construct(private LocaleListener $localeListener) {}

public function switchLocale(string $locale): void
{
    $this->localeListener->setLocale($locale);
}

Call it from a route:

Route::get('/set-locale/{locale}', [YourController::class, 'switchLocale']);

Implementation Patterns

Core Workflows

Locale Switching in Controllers: Use dependency injection to leverage the LocaleListener:

public function index(LocaleListener $localeListener, Request $request)
{
    $locale = $request->get('locale', config('app.locale'));
    $localeListener->setLocale($locale);
    // ...
}

Middleware for Locale Persistence: Create middleware to persist locale across requests (e.g., via session):

use Arthem\LocaleBundle\EventListener\LocaleListener;

class LocaleMiddleware
{
    public function __invoke(Request $request, LocaleListener $localeListener)
    {
        $locale = session('locale', config('app.locale'));
        $localeListener->setLocale($locale);
        return $next($request);
    }
}

protected function configureMiddleware(Middleware $middleware)
{
    $middleware->alias('locale', LocaleMiddleware::class);
    // ...
}

Twig Integration: Access the current locale in Twig:

{{ app.request.attributes.get('_locale') }}

Or use the bundle’s provided filters:

{{ 'Hello'|trans({locale: app.request.attributes.get('_locale')}) }}

Route-Based Locale Switching: Use Symfony’s LocaleListener (if extended) or custom logic to parse locales from routes:

# config/routes.yaml
_locale:
    path: /{_locale}
    defaults:
        _locale: en
        _controller: Symfony\Bundle\FrameworkBundle\Controller\RedirectController::urlRedirectAction
        route: home
    requirements:
        _locale: en|fr|fr_CA

Integration Tips

Translation Integration: Pair with Symfony’s Translation component for seamless translations:
```
$translator = $this->get('translator');
$translator->trans('key', [], null, $locale);
```
Database Locale Storage: Store user-preferred locales in the database and hydrate the LocaleListener on auth:
```
$user->locale; // e.g., 'fr_CA'
$localeListener->setLocale($user->locale);
```

Fallback Logic: Configure fallback locales in arthem_locale.yaml:

arthem_locale:
    locales:
        - en
        - fr
    fallback_locale: en

Gotchas and Tips

Pitfalls

Locale Validation: The bundle does not validate locales against the configured list by default. Always sanitize input:

$validLocales = config('arthem_locale.locales');
if (!in_array($locale, $validLocales)) {
    throw new \InvalidArgumentException("Invalid locale: {$locale}");
}

Intl Extension Dependency: The package requires ext-intl for full locale features (e.g., locale-aware sorting). Test locally:
```
php -m | grep intl
```
If missing, install via:
```
pecl install intl
```
Session vs. Request Locale: Without middleware, the locale resets per-request. Use session storage for persistence:
```
session(['locale' => $locale]);
```
Twig Cache Invalidation: Changing locales dynamically may require Twig cache clearing:
```
php bin/console cache:clear
```
Or configure runtime compilation in config/packages/twig.yaml:
```
twig:
    runtime_loader: Symfony\Component\Twig\Loader\FilesystemLoader
```

Debugging

Check Current Locale: Dump the locale in a controller:

dump(app()->getLocale()); // Symfony's locale
dump($localeListener->getLocale()); // Bundle's locale

Log Locale Switches: Extend LocaleListener to log changes:

use Psr\Log\LoggerInterface;

class CustomLocaleListener extends LocaleListener
{
    public function __construct(private LoggerInterface $logger) {}

    public function setLocale(string $locale): void
    {
        $this->logger->info("Locale switched to: {$locale}");
        parent::setLocale($locale);
    }
}

Extension Points

Custom Locale Provider: Implement Arthem\LocaleBundle\Provider\LocaleProviderInterface for dynamic locales:

class UserLocaleProvider implements LocaleProviderInterface
{
    public function getLocale(): string
    {
        return auth()->user()->locale ?? config('app.locale');
    }
}

# config/services.yaml
services:
    Arthem\LocaleBundle\Provider\LocaleProviderInterface: '@user_locale_provider'

Event Listeners: Subscribe to LocaleChangedEvent (if exposed) for side effects:

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Arthem\LocaleBundle\Event\LocaleChangedEvent;

class LocaleSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            LocaleChangedEvent::class => 'onLocaleChanged',
        ];
    }

    public function onLocaleChanged(LocaleChangedEvent $event): void
    {
        // Redirect to locale-specific URL, etc.
    }
}

Override Default Behavior: Extend the bundle’s services in config/packages/arthem_locale.yaml:

services:
    Arthem\LocaleBundle\EventListener\LocaleListener:
        arguments:
            $fallbackLocale: 'en_US'
            $supportedLocales: ['%kernel.project_dir%/config/locales.php']

Configuration Quirks

Locale Format: The bundle expects ICU locale strings (e.g., fr_CA). Avoid shorthand (e.g., fr) unless explicitly configured.

Priority: The bundle’s locale listener runs after Symfony’s default listener. Override priority in config/packages/arthem_locale.yaml:

 services:
     Arthem\LocaleBundle\EventListener\LocaleListener:
         tags:
             - { name: kernel.event_listener, event: kernel.request, method: onKernelRequest, priority: 255 }

Locale Bundle Laravel Package