Location Laravel Package

Getting Started

• Install with composer require abr4xas/location:^6.0.0; v6 is a new major, so verify PHP/Laravel version constraints before upgrading an existing app.
• Start by checking the package README, service provider, and publishable assets. Publish only what you need:
  • php artisan vendor:publish --provider="Abr4xas\Location\LocationServiceProvider"
  • Prefer specific tags if available, such as config, migrations, or seeders.
• Run migrations and seed/reference-data import as documented, then inspect the resulting models/tables before building against them.
• First practical use case: address forms and lookup validation. Use the package’s location records to populate country/state/city selects, validate submitted IDs/codes with exists or custom rules, and store normalized foreign keys or ISO codes in your own domain tables.
• Treat v6 as a reference-data layer, not a geocoder. Keep your application’s address/business logic in your own models and use the package for lookup data.

Implementation Patterns

• Wrap package models behind your own repository/service or query scope when possible. This limits blast radius from future major upgrades and keeps business rules out of vendor code.
• For forms, load only the levels needed:
  • Country list on initial render.
  • State/region list filtered by selected country.
  • City/locality list filtered by selected state/region.
• Cache stable lookup lists with tagged or keyed cache entries. Invalidate only when reference data is re-seeded or upgraded.
• Use eager loading and indexes for relationship-heavy lookups. Avoid lazy-loading location relationships inside loops or API resources.
• Validate hierarchical consistency server-side, not only in the UI: e.g. ensure the submitted city belongs to the submitted state and country.
• Store stable identifiers in your domain tables. Prefer ISO codes or package IDs depending on package stability; avoid storing display names as the only reference.
• For APIs, return lean API resources with id, code, name, and parent identifiers. Do not expose full package models unless the package’s API is intentionally public.
• In tests, use a small fixture set or factory-like seed data rather than importing the full location dataset. Add an upgrade smoke test that verifies published config, migrations, model relationships, and a basic lookup query.
• If v6 changes namespaces, config keys, table names, or model contracts, update imports and published files in one dedicated upgrade branch before feature work.

Gotchas and Tips

• v6.0.0 is a major release, but the release note only says “Upgrade.” Treat it as potentially breaking until you review the diff between v5.0.0...v6.0.0, especially service provider bindings, config publishing, migrations, namespaces, and minimum Laravel/PHP versions.
• Do not assume published migrations/config from v5 are compatible with v6. Republish to a temporary directory and diff before overwriting app-customized files.
• Watch for seeder size and import performance. Use transactions, disable constraints only when appropriate, and prefer idempotent upserts over truncate-and-reload in production.
• Avoid editing vendor files. If you need custom behavior, extend package models, bind your own implementation, or copy published migrations/config into the app and document the divergence.
• Debug upgrade issues with composer show abr4xas/location, composer why-not abr4xas/location 6.0.0, php artisan vendor:publish --list, and a fresh test database migration/seed run.
• Confirm whether location data is bundled, downloaded, or seeded manually. If it is bundled, plan for data refresh cadence; if manual, document the import step in deployment.
• Check query performance after upgrade. New major versions sometimes add indexes, change column types, or alter relationship defaults; verify with EXPLAIN on common lookups.
• If the package registers routes or helpers, check for collisions with existing app routes/helpers after upgrading. Clear cached config/routes with php artisan optimize:clear.
• Extension points to prefer: published config, custom model subclasses, repository bindings, validation rules, and API resources. Avoid relying on undocumented internals or direct table mutations.