Weave Code
Addressing Laravel Package
sylius/addressing
Sylius Addressing component provides models and services to manage addresses, countries, and provinces (states). Includes a flexible zones system to group regions and match addresses to zones—useful for shipping and tax calculations in PHP eCommerce apps.
[READ-ONLY] Addresses, countries and zones management system for PHP.
Frequently asked questions about Addressing
- How do I integrate sylius/addressing into a Laravel project with Eloquent?
- Use the Eloquent bridge by installing the package and configuring it in `config/addressing.php`. Replace your existing address tables with Sylius entities (e.g., `Country`, `Province`, `Address`) and bind repositories in `AppServiceProvider`. Example: `$this->app->bind(CountryRepositoryInterface::class, CountryRepository::class)`.
- Can I use this package for non-eCommerce projects like SaaS regional access control?
- Yes, the component is decoupled from Sylius and works for any PHP app needing address validation or geographic zones. Use it for regional user access, field service routing, or compliance-based region checks. The MIT license ensures no vendor lock-in.
- What Laravel versions does sylius/addressing support?
- The package supports Laravel 8.x and 9.x (PHP 8.0+). For older Laravel versions, check the Sylius documentation for legacy compatibility or use a Doctrine bridge like `spatie/laravel-doctrine-orm` if needed.
- How do I define a zone that includes multiple countries and excludes a province?
- Zones are defined via `ZoneMember` entities. For example, create a zone with members for `Country::US` and `Country::CA`, then exclude `Province::US::AL` (Alabama) using negative rules. The `ZoneMatcher` service handles complex logic like this during runtime.
- Does sylius/addressing include postal code validation for specific countries?
- Basic validation (e.g., format checks) is included via Symfony’s validator constraints. For advanced validation (e.g., US ZIP codes, UK postcodes), extend the `AddressValidator` or integrate third-party services like SmartyStreets or Google Maps APIs.
- How do I migrate existing address data to sylius/addressing entities?
- Use Doctrine migrations or Eloquent factories to map legacy tables to Sylius entities. For complex schemas, create a data mapper service to transform old records. Test thoroughly, as field names (e.g., `state` vs. `province`) may differ.
- What are the performance implications of zone matching for high-traffic sites?
- Zone matching is O(n) per address. For high-volume queries, cache zone memberships (e.g., with Redis) or denormalize zone data. Avoid dynamic zone recalculations during checkout; precompute zone assignments where possible.
- Can I use sylius/addressing without Doctrine (e.g., with Laravel’s Query Builder)?
- The core package requires Doctrine ORM/DBAL, but you can build a custom repository layer to work with Laravel’s Query Builder. For Eloquent, use the built-in bridge, but avoid mixing ORMs to prevent inconsistencies.
- Are there alternatives to sylius/addressing for Laravel address management?
- Alternatives include `spatie/laravel-address`, which is simpler but lacks zone flexibility, or `torann/laravel-geoip` for IP-based geolocation. Sylius/Addressing stands out for hierarchical zones and eCommerce-specific features like tax/shipping rule integration.
- How do I test zone matching logic in PHPUnit?
- Mock `Country`, `Province`, and `Address` entities, then test `ZoneMatcher` with edge cases (e.g., overlapping zones, excluded provinces). Use data providers to cover scenarios like `Zone::contains($address)`. Example: `$zoneMatcher->match($address)->getName()` should return the correct zone.
Weaver
How can I help you explore Laravel packages today?