Weave Code
Addressing Laravel Package
commerceguys/addressing
Addressing library for handling international postal addresses. Provides country and subdivision data, address formats, validation, and formatting utilities. Useful for commerce, shipping, and any app that needs correct, locale-aware addresses worldwide.
commerceguys/addressing is a PHP library that standardizes international postal addressing using authoritative country data. It helps apps validate and format addresses correctly across regions, improving checkout and shipping workflows.
Built with global coverage in mind, it provides reusable models and utilities for handling address formats, subdivisions, and localization in a consistent API.
- Address format metadata per country (required fields, postal code patterns, labels)
- Hierarchical subdivision data (country → region → locality, etc.)
- Flexible formatting for display and mailing labels
- Helpers for validation and normalization of address input
- Supports localization (translated names, locale-aware formatting)
Frequently asked questions about Addressing
- Can I use this package for address validation in Laravel forms without geocoding?
- Yes, the package supports standalone validation using CLDR data without requiring Google’s geocoding API. Focus on the `AddressValidator` component for basic validation, which works offline and integrates seamlessly with Laravel’s `Validator` facade or custom validation rules.
- How do I integrate this with Laravel’s built-in validation system?
- Extend Laravel’s validation by creating a custom rule using the `AddressValidator` class. For example, define a macro in a service provider: `Rule::macro('valid_address', fn($attribute, $value, $fail) => $validator->validate($value) || $fail('Invalid address.'));` Then use it in FormRequests or controllers with `Rule::valid_address`.
- Does this package work with Laravel 10+ and PHP 8.1+?
- Yes, the package is fully compatible with Laravel 10+ and PHP 8.1+. It leverages modern PHP features like named arguments and attributes, ensuring smooth integration with Laravel’s latest versions. Check the package’s `composer.json` for exact version requirements.
- What’s the best way to handle Google API costs for geocoding in production?
- Cache geocoding responses aggressively using Laravel’s HTTP cache middleware or Redis. Implement a fallback to CLDR-only validation for offline scenarios, and consider rate-limiting API calls via Laravel’s `throttle` middleware. For high-volume use, explore free alternatives like OpenStreetMap’s Nominatim API.
- How do I store validated addresses in my Laravel database?
- Design a normalized schema (e.g., `street_address`, `locality`, `postal_code`, `country_code`) and store addresses in a dedicated `addresses` table or as JSON in a pivot table. The package doesn’t include migrations, so use Laravel’s `make:migration` to create tables. For relationships, use polymorphic associations if addresses belong to multiple models.
- Can I use this package with Livewire for real-time address validation?
- Absolutely. Use Livewire’s `@validate` directive or custom JavaScript to trigger validation via the `AddressValidator` class. Return structured errors to the frontend and display them in Livewire components. For autocomplete suggestions, integrate with Google’s Places API or a frontend library like `vue-google-autocomplete`.
- What are the alternatives if I need Laravel-specific address handling (e.g., Eloquent models)?
- For Laravel-specific features like Eloquent models or Blade components, consider pairing this package with **spatie/laravel-address** or **nwidart/laravel-modules**. These provide Laravel-centric abstractions (e.g., model traits, migrations) while still using `commerceguys/addressing` for validation logic under the hood.
- How do I update CLDR data files in the package?
- CLDR data is typically bundled as JSON files in the package. To update, replace the files in the `vendor/commerceguys/addressing/src/Resources/cldr` directory or use a Composer script to fetch the latest version from CLDR’s official repository. For automation, create an Artisan command to download and cache updates periodically.
- Does this package support non-Latin scripts (e.g., Arabic, Chinese) for address validation?
- Yes, the package leverages CLDR, which includes support for non-Latin scripts. However, accuracy may vary for niche locales or rural areas. Test thoroughly with your target regions and consider supplementing with custom rules or third-party datasets for edge cases.
- How can I test address validation for edge cases like PO boxes or military addresses?
- Write PHPUnit tests using Laravel’s testing helpers to validate edge cases. Mock the `AddressValidator` and pass test strings like `'APO AE 09876'` or `'P.O. Box 12345, New York'`. For geocoding, use Laravel’s HTTP testing to mock API responses. Include test data for non-Latin scripts, hyphenated addresses, and regional formats.
Weaver
How can I help you explore Laravel packages today?