Google Maps Laravel Package

Getting Started

Install the package via Composer:

composer require <vendor>/<package>

Publish any config and migration files (if applicable):

php artisan vendor:publish --provider="<Vendor>\<Package>\<PackageServiceProvider>"
php artisan migrate

Look first at:

• config/<package>.php – locale mappings and default formatting options.
• The package’s formatter class (e.g. AddressFormatter) – the primary entry point for localized output.
• Translation files under resources/lang/vendor/<package> – address format strings per locale.

First use case: Store an address and render it using the current application locale.

use <Vendor>\<Package>\Models\Address;

$address = Address::create([
    'line1' => '123 Main St',
    'city'  => 'Springfield',
    'state' => 'IL',
    'postal_code' => '62701',
    'country' => 'US',
]);

// The formatter now respects app()->getLocale() (v0.4+)
echo $address->format(); // e.g. "123 Main St, Springfield, IL 62701"

Set the locale before formatting:

app()->setLocale('fr_FR');
echo $address->format(); // "123 Main St, 62701 Springfield (IL)"

Implementation Patterns

Locale‑aware formatting in models

Use the package’s formatter directly or through model accessors:

// Explicit locale
$formatted = $address->format('de_DE');

// Site locale (v0.4)
$formatted = $address->format();

// In a Blade view
{{ $address->format() }}

Formatting in API resources

class AddressResource extends JsonResource
{
    public function toArray($request)
    {
        return [
            'formatted' => $this->format(), // uses request locale
            'lines'     => $this->toArray(),
        ];
    }
}

Locale switching during a request

For multi‑locale sites, set the locale early (middleware, controller) so all address formatting uses the correct locale:

public function show(Address $address)
{
    app()->setLocale($request->user()->locale);
    return view('address.show', compact('address'));
}

Overriding format strings

Publish the package translations and edit the format strings for each locale:

// resources/lang/vendor/<package>/fr/address.php
return [
    'format' => '{line1}, {postal_code} {city} ({state})',
];

Batch formatting

When rendering lists of addresses, set the locale once rather than per address:

app()->setLocale('es_ES');
$formatted = $addresses->map->format();

Gotchas and Tips

• Locale fallback: If no translation exists for the current locale, the package falls back to config('app.fallback_locale'). Verify your locale is present in the published translation files.
• Caching formatted output: If you cache formatted addresses, include the locale in the cache key – otherwise a locale change will serve stale strings.
• Locale detection: The package uses app()->getLocale(). Ensure your middleware or controller sets it before any formatting occurs. Using App::setLocale() inside a view is too late for earlier calls.
• Translation publishing: After updating to v0.4, re‑publish the translation files if you need the new locale keys. Check the package changelog for any new format placeholders.
• Debugging: Use php artisan tinker to test formatting with different locales:

  app()->setLocale('it_IT');
  Address::first()->format();
  

• Custom formatters: The package may allow binding a custom formatter via the service container. Check config/<package>.php for a formatter key or use the provided extension points (e.g. macros on the formatter class).
• Testing: In your test suite, explicitly set the locale before asserting formatted strings – locale can leak between tests.
• Performance: Formatting is lightweight, but if you format thousands of addresses in a loop, consider grouping by locale and setting the locale once per group.