- How do I install fndmiranda/simple-address in a Laravel application?
- Install it with Composer using composer require fndmiranda/simple-address, then publish the package configuration and migrations with php artisan vendor:publish and run php artisan migrate. If you need the shipped states and cities data, run the package seeders after migrating. Check the package's composer.json for PHP and Laravel version constraints before installing, and validate the install in a non-production environment first.
- Does this package support Brazilian CEP (zip code) lookup?
- Yes. The package includes a CEP lookup service that queries multiple external APIs and fills address data automatically. It is focused on Brazilian postcodes, so behavior outside Brazil should not be assumed. Confirm which providers are included and their quotas and terms before relying on it.
- Which Laravel and PHP versions does this package support?
- The overview does not pin specific Laravel or PHP versions, so check the composer.json constraints in the repository before installing. Test the package against your exact PHP, Laravel, database, cache, and queue runtime. If your application is on an older or very new Laravel release, verify dependency compatibility in a sandbox first.
- Does the package ship migrations, models, and seeders for states and cities?
- Yes, it ships migrations, models, and seeders for Brazilian states and cities. Publish the migrations, run them, and seed the data if you want the package's address tables. For existing applications, consider mapping package outputs into your own address schema rather than adopting the package models wholesale.
- How does the optional Google Maps geocoding work?
- Geocoding is optional and uses Google Maps to enrich lookup results with coordinates. You will need Google Maps API credentials and should review quotas, billing, and terms of service. Treat geocoding results as enrichment rather than authoritative address data, and validate accuracy for your use case.
- Can I swap or extend the postcode API providers?
- The package is designed to search addresses across multiple APIs, but you should verify how providers are registered and whether custom providers are supported. A safer integration is to wrap it behind your own AddressLookupService interface and map responses into internal DTOs. That keeps domain code independent of package models, facades, and provider-specific response shapes.
- Does it cache lookup responses or handle timeouts and retries?
- Caching, timeout, and retry behavior is not clear from the package overview, so inspect the source and test it explicitly. External API rate limits and latency will dominate scaling, so add application-level caching, timeouts, retries, and fallback providers. Monitor quota exhaustion and malformed responses in production.
- Is fndmiranda/simple-address safe to use in production?
- Treat it as an accelerator rather than a strategic platform dependency: it has low community adoption and should be validated thoroughly. Pin the package version, add contract tests with mocked provider responses, and monitor upstream maintenance activity. Have a fork or internal ownership plan ready, and review retention and logging because address and geolocation data may contain PII.
- Does it support addresses outside Brazil or batch and queued lookups?
- The package is built for Brazilian addresses and CEP lookup, so multi-country operation should not be assumed. Batch and queued lookups are not described in the overview; if you need them, wrap lookups in jobs with rate limiting and idempotency. Confirm provider coverage and postcode format assumptions before expanding beyond Brazil.
- How do I test the package without calling real postcode or geocoding APIs?
- Use a time-boxed sandbox spike with real provider credentials in a non-production environment, then mock HTTP responses for automated contract tests. Cover lookup success, provider failure, malformed responses, rate limits, and geocoding errors. Roll out behind a feature flag and add observability before enabling it for all users.