Getting Started

Minimal Setup

Install the package:
```
composer require symfony/intl
```
Verify the intl extension (optional but recommended for full functionality):
```
php -m | grep intl
```
If missing, install it via your OS package manager (e.g., pecl install intl or apt-get install php-intl).
Compress ICU data (for production, reduces size by ~50%):
```
php vendor/symfony/intl/Resources/bin/compress
```
This generates compressed files in vendor/symfony/intl/Resources/stubs/.

First Use Case: Localized Country Selector

Scenario: Build a multi-language country dropdown in a Laravel Blade view.

Inject the Countries service in your controller:

use Symfony\Component\Intl\Resources\Countries;

public function showCountries()
{
    $countries = Countries::getNames('en'); // English names
    // OR for user-preferred locale:
    $countries = Countries::getNames(app()->getLocale());
    return view('countries', compact('countries'));
}

Render in Blade:

<select>
    @foreach ($countries as $code => $name)
        <option value="{{ $code }}">{{ $name }}</option>
    @endforeach
</select>

Localize dynamically (e.g., switch to French):

$countries = Countries::getNames('fr'); // "États-Unis", "Canada", etc.

First Use Case: Currency Formatting

Scenario: Display and validate currencies in a payment form.

Get currency symbols/names:

use Symfony\Component\Intl\Resources\Currencies;

$symbols = Currencies::getSymbols('en'); // ['USD' => '$', 'EUR' => '€', ...]
$names = Currencies::getNames('en');     // ['USD' => 'US Dollar', 'EUR' => 'Euro', ...]

Filter active currencies (e.g., exclude deprecated ones):

$activeCurrencies = Currencies::getActiveCurrencies();

Use in a Laravel Form Request:

use Symfony\Component\Intl\Resources\Currencies;

public function rules()
{
    return [
        'amount' => 'required|numeric',
        'currency' => [
            'required',
            Rule::in(array_keys(Currencies::getActiveCurrencies())),
        ],
    ];
}

First Use Case: Timezone-Aware Features

Scenario: Display timezone names in a user profile.

Get timezone names:

use Symfony\Component\Intl\Resources\TimeZoneNames;

$timezoneNames = TimeZoneNames::getNames('en', TimeZoneNames::LONG);
// ['America/New_York' => 'Eastern Time (US & Canada)', ...]

Filter by region:

$americanTimezones = TimeZoneNames::getNames('en', TimeZoneNames::LONG, 'America');

Use in a Blade view:

<select name="timezone">
    @foreach ($timezoneNames as $code => $name)
        <option value="{{ $code }}">{{ $name }}</option>
    @endforeach
</select>

Implementation Patterns

Pattern 1: Service Provider Integration

Use Case: Register the package’s services globally for easy access.

Create a service provider (e.g., App\Providers\IntlServiceProvider):

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Symfony\Component\Intl\Resources\Countries;
use Symfony\Component\Intl\Resources\Currencies;
use Symfony\Component\Intl\Resources\TimeZoneNames;

class IntlServiceProvider extends ServiceProvider
{
    public function register()
    {
        $this->app->singleton('countries', function () {
            return new Countries();
        });

        $this->app->singleton('currencies', function () {
            return new Currencies();
        });

        $this->app->singleton('timezoneNames', function () {
            return new TimeZoneNames();
        });
    }
}

Register the provider in config/app.php:

'providers' => [
    // ...
    App\Providers\IntlServiceProvider::class,
],

Inject services anywhere:

use Illuminate\Support\Facades\App;

$countries = App::make('countries');
$currencies = App::make('currencies');

Pattern 2: Blade Directives for Localization

Use Case: Create reusable Blade directives for common localization tasks.

Add a Blade directive in AppServiceProvider:

use Illuminate\Support\Facades\Blade;

public function boot()
{
    Blade::directive('countryName', function ($code) {
        return "<?php echo Symfony\Component\Intl\Resources\Countries::getName('{$code}', app()->getLocale()); ?>";
    });

    Blade::directive('currencySymbol', function ($code) {
        return "<?php echo Symfony\Component\Intl\Resources\Currencies::getSymbol('{$code}', app()->getLocale()); ?>";
    });
}

Use in Blade:

<span>{{-- Display country name in current locale --}}
    @countryName('US') <!-- Outputs "United States" or "États-Unis" -->
</span>

<span>{{-- Display currency symbol --}}
    @currencySymbol('EUR') <!-- Outputs "€" -->
</span>

Pattern 3: Form Request Validation with Intl

Use Case: Validate country/currency inputs using the package’s data.

Create a custom validation rule:

use Illuminate\Validation\Rule;
use Symfony\Component\Intl\Resources\Countries;
use Symfony\Component\Intl\Resources\Currencies;

public function rules()
{
    return [
        'country' => [
            'required',
            Rule::in(array_keys(Countries::getNames('en'))),
        ],
        'currency' => [
            'required',
            Rule::in(array_keys(Currencies::getActiveCurrencies())),
        ],
    ];
}

Custom error messages:

public function messages()
{
    return [
        'country.in' => 'The selected country is invalid.',
        'currency.in' => 'The selected currency is invalid or deprecated.',
    ];
}

Pattern 4: Localization-Aware API Responses

Use Case: Return localized data in API responses.

Create a resource class:

use Symfony\Component\Intl\Resources\Countries;
use Illuminate\Http\Resources\Json\JsonResource;

class CountryResource extends JsonResource
{
    public function toArray($request)
    {
        return [
            'code' => $this->code,
            'name' => Countries::getName($this->code, $request->locale),
            'native_name' => Countries::getNativeName($this->code),
        ];
    }
}

Use in a controller:

public function showCountry($code)
{
    return new CountryResource(Country::find($code));
}

Pattern 5: Timezone-Aware Scheduling

Use Case: Schedule tasks in user-specific timezones.

Get timezone offsets:

use Symfony\Component\Intl\Resources\TimeZoneNames;

$timezone = 'America/New_York';
$offset = (new \DateTimeZone($timezone))->getOffset(new \DateTime());

Schedule a command with a timezone:

use Illuminate\Support\Facades\Schedule;

Schedule::command('send-newsletter')->timezone('America/New_York')->daily();

Pattern 6: Multi-Tenant Locale Configuration

Use Case: Allow tenants to set their preferred locales.

Store tenant locale in the database:

// Migration
Schema::table('tenants', function (Blueprint $table) {
    $table->string('locale')->default('en');
});

Override the app locale dynamically:

public function boot()
{
    app()->binding('locale', function () {
        return auth()->user()->tenant->locale ?? config('app.locale');
    });
}

Use in Intl calls:

$countries = Countries::getNames(app()->getLocale());

Pattern 7: Caching Localized Data

Use Case: Cache localized data to reduce ICU overhead.

Cache the countries list:

use Symfony\Component\Intl\Resources\Countries;
use Illuminate\Support\Facades\Cache;

$countries = Cache::remember('countries.'.app()->get

Intl Laravel Package