- How do I install jeffersongoncalves/laravel-cep in a Laravel application?
- Install the package with Composer by running composer require jeffersongoncalves/laravel-cep. Then publish the migration with php artisan vendor:publish --tag=cep-migrations and run php artisan migrate to create the table that stores queried CEPs. The package's service provider is auto-discovered, so no manual registration is required in a standard Laravel app.
- Which Brazilian CEP API providers does this package support?
- The package ships with support for multiple providers, including BrasilAPI, ViaCEP, and AwesomeAPI. Providers are configured through the package's config file, where each entry can be enabled and given its own API URL, so you can prioritise one service and keep others as fallbacks. This abstraction means you can swap providers without refactoring your application code.
- Does laravel-cep store queried CEPs in the database?
- Yes, database storage is a core feature. When Cep::findByCep() runs, it first checks the local database and only calls an external API if the CEP is not already stored, then persists the result for future lookups. Because of this local persistence, repeated lookups of popular CEPs avoid unnecessary external requests and reduce exposure to provider rate limits.
- How do I get address details for a Brazilian postal code in Laravel?
- Use the Cep model and call Cep::findByCep('01310-100'), which returns an array containing the normalised CEP, state, city, neighbourhood, and street. The method handles formatting, validation, local database lookup, and the external API request in a single call. You can use the returned array directly in a controller, form request, or service class.
- How can I check whether a CEP exists without pulling the full address?
- Call Cep::checkCep('01310-100'), which returns a simple true or false. It is useful for form validation rules where you only need to confirm the postal code is real before accepting a submission. Under the hood it uses the same lookup pipeline, so successfully resolved CEPs still benefit from local storage.
- Does the package validate and format CEP input automatically?
- Yes, CEP validation and formatting are built in, so input such as 01310-100 is normalised before being queried and stored. This means you can accept masked or unmasked CEPs from user input without writing your own sanitisation logic. Returned data uses the digits-only format along with the separated state, city, neighbourhood, and street fields.
- Which Laravel and PHP versions are required by laravel-cep?
- The package targets modern Laravel releases and requires PHP 8.0 or newer, with Laravel 8+ reported as supported. Because supported ranges can change between releases, check the require block in the package's composer.json before adding it to a legacy project. On older Laravel or PHP versions, Composer will surface the constraint conflict during installation.
- How should I handle invalid CEPs or provider failures in laravel-cep?
- Wrap lookups in a try/catch and log failures so you can observe provider outages and invalid input: catch the package's CEP exception type and write a warning via Laravel's Log facade. checkCep() is a lighter alternative when you only need a boolean and do not want to handle exceptions. Since the package depends on third-party APIs, also consider retries or a fallback provider for resilience.
- Can I add a custom CEP provider or extend the package?
- The package is built around Laravel's service container and configuration system, so providers can be configured or extended rather than hard-coded. You can register your own implementation through a service binding or a custom service provider if you need an internal database or a paid API. Review the package source for the exact provider contract before implementing a custom driver.
- How do I test code that queries CEPs without hitting external APIs?
- Since HTTP calls go through Guzzle and Laravel's HTTP layer, you can use Http::fake() to return canned provider responses in your test suite. You can also seed the package's CEP table directly, which lets findByCep() resolve entirely from the database with no network access. Both approaches keep tests fast and deterministic while still exercising your address-handling logic.