Laravel Locale Cookie

https://github.com/jeffersongoncalves/laravel-locale-cookie
Admin
Laravel Locale Cookie is a Laravel package and middleware that automatically resolves and validates...
Tokens:3,754
Snippets:34
Trust Score:9.8
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install laravel-locale-cookie with Composer

Source: https://github.com/jeffersongoncalves/laravel-locale-cookie/blob/master/resources/boost/skills/locale-cookie-development/SKILL.md

Installs the laravel-locale-cookie package via Composer. Requires PHP 8.2+, Laravel 11, 12, or 13, and spatie/laravel-package-tools ^1.14.

```bash
composer require jeffersongoncalves/laravel-locale-cookie
```

--------------------------------

### Run tests, coverage, static analysis, and formatting

Source: https://github.com/jeffersongoncalves/laravel-locale-cookie/blob/master/resources/boost/skills/locale-cookie-development/SKILL.md

Commands to run the test suite, coverage, static analysis, and code formatting for the package.

```bash
# Run all tests
vendor/bin/pest

# Run with coverage
vendor/bin/pest --coverage

# Static analysis
vendor/bin/phpstan analyse

# Code formatting
vendor/bin/pint
```

--------------------------------

### Use 'locale' middleware alias

Source: https://github.com/jeffersongoncalves/laravel-locale-cookie/blob/master/README.md

Use the 'locale' middleware alias registered by the package for convenience.

```php
Route::middleware('locale')->group(function () {
    // ...locale-aware routes
});
```

--------------------------------

### Register middleware with Livewire

Source: https://github.com/jeffersongoncalves/laravel-locale-cookie/blob/master/README.md

Register the middleware as a Livewire persistent middleware so subsequent /livewire/update requests keep the visitor's locale. Must be registered in addition to the route-group middleware.

```php
use Livewire\Livewire;
use JeffersonGoncalves\LocaleCookie\Middleware\SetLocale;

// In a service provider's boot() method
Livewire::addPersistentMiddleware([
    SetLocale::class,
]);
```

--------------------------------

### Run tests with composer test

Source: https://github.com/jeffersongoncalves/laravel-locale-cookie/blob/master/README.md

Runs the test suite for the package using Composer's test script.

```bash
composer test
```

--------------------------------

### Add SetLocale as Livewire persistent middleware

Source: https://github.com/jeffersongoncalves/laravel-locale-cookie/blob/master/resources/boost/skills/locale-cookie-development/SKILL.md

Registers SetLocale as a persistent Livewire middleware so /livewire/update requests keep the visitor's locale instead of falling back to the default. Required when locale-aware pages use Livewire.

```php
use Livewire\Livewire;
use JeffersonGoncalves\LocaleCookie\Middleware\SetLocale;

Livewire::addPersistentMiddleware([
    SetLocale::class,
]);
```

--------------------------------

### Default config/locale-cookie.php

Source: https://github.com/jeffersongoncalves/laravel-locale-cookie/blob/master/resources/boost/skills/locale-cookie-development/SKILL.md

Default configuration for the package. The 'cookie' key sets the cookie name, 'supported' is the whitelist of accepted locales, and 'fallback' defaults to null, which defers to config('app.fallback_locale').

```php
// config/locale-cookie.php
return [
    'cookie' => 'locale',      // cookie name to read
    'supported' => ['en'],     // accepted locales (whitelist)
    'fallback' => null,        // null => config('app.fallback_locale')
];
```

--------------------------------

### Alias middleware in bootstrap/app.php

Source: https://github.com/jeffersongoncalves/laravel-locale-cookie/blob/master/README.md

Alias the middleware in bootstrap/app.php by appending it to the web group.

```php
->withMiddleware(function (Middleware $middleware) {
    $middleware->web(append: [
        \JeffersonGoncalves\LocaleCookie\Middleware\SetLocale::class,
    ]);
})
```

--------------------------------

### Pest tests for locale resolution

Source: https://github.com/jeffersongoncalves/laravel-locale-cookie/blob/master/resources/boost/skills/locale-cookie-development/SKILL.md

Pest test patterns for the middleware. The helper builds a Request with cookies, runs the middleware, and returns App::getLocale(). The tests verify that a supported cookie sets the locale and that an unsupported cookie falls back to the configured fallback.

```php
use Illuminate\Http\Request;
use Illuminate\Support\Facades\App;
use JeffersonGoncalves\LocaleCookie\Middleware\SetLocale;

function handleWithCookies(array $cookies = []): string
{
    $request = Request::create('/', 'GET', [], $cookies);

    (new SetLocale)->handle($request, fn ($request) => response('ok'));

    return App::getLocale();
}

it('sets the app locale from a supported locale cookie', function () {
    config()->set('locale-cookie.supported', ['en', 'pt_BR']);
    config()->set('locale-cookie.fallback', 'en');

    expect(handleWithCookies(['locale' => 'pt_BR']))->toBe('pt_BR');
});

it('falls back when the cookie holds an unsupported locale', function () {
    config()->set('locale-cookie.supported', ['en']);
    config()->set('locale-cookie.fallback', 'en');

    expect(handleWithCookies(['locale' => 'xx']))->toBe('en');
});
```

--------------------------------

### Publish locale-cookie config file

Source: https://github.com/jeffersongoncalves/laravel-locale-cookie/blob/master/resources/boost/skills/locale-cookie-development/SKILL.md

Publishes the package's config file (config/locale-cookie.php) so you can customize the cookie name, supported locales, and fallback.

```bash
php artisan vendor:publish --tag="locale-cookie-config"
```

--------------------------------

### Register SetLocale middleware on route group

Source: https://github.com/jeffersongoncalves/laravel-locale-cookie/blob/master/resources/boost/skills/locale-cookie-development/SKILL.md

Registers the SetLocale middleware on a route group so those routes become locale-aware. Place this in your routes file.

```php
use JeffersonGoncalves\LocaleCookie\Middleware\SetLocale;

Route::middleware(SetLocale::class)->group(function () {
    // ...locale-aware routes
});
```

--------------------------------

### Shorten locale code with LocaleCookie::short()

Source: https://github.com/jeffersongoncalves/laravel-locale-cookie/blob/master/README.md

Use the LocaleCookie::short() helper to reduce a locale to its short language code. Useful for <html lang="…">, flag icons, or any place needing only the base language. Returns 'en' as fallback when there is no usable prefix.

```php
use JeffersonGoncalves\LocaleCookie\LocaleCookie;

LocaleCookie::short('pt_BR'); // 'pt'
LocaleCookie::short('pt-BR'); // 'pt'
LocaleCookie::short('EN');    // 'en'
LocaleCookie::short();        // current app locale, shortened
LocaleCookie::short('');      // 'en' (fallback when there is no usable prefix)
```

--------------------------------

### SetLocale middleware implementation

Source: https://github.com/jeffersongoncalves/laravel-locale-cookie/blob/master/resources/boost/skills/locale-cookie-development/SKILL.md

The SetLocale middleware reads the cookie named by config('locale-cookie.cookie'), validates it against config('locale-cookie.supported'), and falls back to config('locale-cookie.fallback') ?? config('app.fallback_locale') when the cookie is missing or unsupported. It then calls App::setLocale() and passes the request along.

```php
namespace JeffersonGoncalves\LocaleCookie\Middleware;

use Closure;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\App;
use Symfony\Component\HttpFoundation\Response;

class SetLocale
{
    public function handle(Request $request, Closure $next): Response
    {
        $cookieName = config('locale-cookie.cookie', 'locale');
        $supported = config('locale-cookie.supported', ['en']);
        $fallback = config('locale-cookie.fallback') ?? config('app.fallback_locale');

        $locale = $request->cookie($cookieName);

        if (! is_string($locale) || ! in_array($locale, $supported, true)) {
            $locale = $fallback;
        }

        App::setLocale($locale);

        return $next($request);
    }
}
```

--------------------------------

### Set locale cookie from PHP

Source: https://github.com/jeffersongoncalves/laravel-locale-cookie/blob/master/README.md

Set the locale cookie from PHP. The package only reads the cookie; your application must set it when the visitor chooses a locale.

```php
return redirect()->back()->withCookie(cookie()->forever('locale', 'pt_BR'));
```

--------------------------------

### Locale switch route configuration

Source: https://github.com/jeffersongoncalves/laravel-locale-cookie/blob/master/README.md

Configuration for the locale switch route. The {locale} param is constrained to config('locale-cookie.supported'). You can configure or disable it under 'locale-cookie.switch'.

```php
'switch' => [
    'enabled' => true,
    'path' => 'locale/{locale}',
    'name' => 'locale.switch',
    'lifetime' => 60 * 24 * 365, // cookie lifetime in minutes
    'middleware' => ['web'],     // attaches the queued cookie; the locale cookie is excluded from encryption
],
```

--------------------------------

### Set locale cookie from JavaScript

Source: https://github.com/jeffersongoncalves/laravel-locale-cookie/blob/master/README.md

Set the locale cookie from the client with JavaScript. The cookie is never encrypted, so it works with the middleware's plaintext read.

```javascript
document.cookie = 'locale=pt_BR; path=/; max-age=31536000';
```

--------------------------------

### Language switcher Blade template

Source: https://github.com/jeffersongoncalves/laravel-locale-cookie/blob/master/README.md

Blade template for a language switcher that points to the 'locale.switch' route. The route persists the chosen locale in the cookie and redirects back to a same-host Referer.

```blade
@foreach (config('locale-cookie.supported') as $code)
    <a href="{{ route('locale.switch', ['locale' => $code]) }}">{{ strtoupper($code) }}</a>
@endforeach
```

--------------------------------

### Use LocaleCookie::short() in Blade for html lang

Source: https://github.com/jeffersongoncalves/laravel-locale-cookie/blob/master/README.md

Blade usage of LocaleCookie::short() to set the HTML lang attribute to the current locale's short code.

```blade
<html lang="{{ \JeffersonGoncalves\LocaleCookie\LocaleCookie::short() }}">
```
Tokens:
Raw