- How do I install claudsonm/cep-promise-php in a Laravel application?
- Install it with Composer using composer require claudsonm/cep-promise-php. The package is framework-agnostic, so no Laravel service provider or configuration file is required; call CepPromise::fetch directly from a service, job, or controller. In v1.2.0, confirm your app satisfies PHP 7.4 or newer and Guzzle 7.2.0 or newer before updating.
- How do I perform a CEP lookup with the promise-based API?
- Call CepPromise::fetch with a Brazilian postal code and handle the returned promise with then and catch, or await it in an async context. The promise resolves to normalized address data from the selected provider chain, so your application does not need to parse each provider response separately. Use a catch handler to deal with invalid CEPs or provider failures.
- Which Brazilian CEP providers does claudsonm/cep-promise-php support?
- The package queries services such as Correios, ViaCEP, and CepAberto, and is designed to support additional providers through its provider list. When you omit the provider parameter, fetch uses the package default provider set and ordering. Check the default order in your installed version if fallback behavior matters for your address flow.
- How can I restrict or customize CEP providers for testing and production?
- Version 1.2.0 added an optional second argument to CepPromise::fetch that lets you pass the provider classes to use. A common pattern is a single provider in tests or staging and a fallback chain in production. Verify whether your installed version expects fully qualified class names or instantiated provider objects before building mocks or decorators around that seam.
- Does claudsonm/cep-promise-php work with Laravel 9, 10, or 11?
- The package is not tied to a specific Laravel version because it is a plain PHP HTTP client wrapper. It can be used in modern Laravel applications as long as the platform satisfies PHP 7.4 or newer and Guzzle 7.2.0 or newer for v1.2.0. Pin the package constraint and rely on your lockfile because support-dropping changes were released as a minor version.
- How is claudsonm/cep-promise-php tested?
- The project reports 100 percent coverage using mocked HTTP calls, which is important for a package that depends on external CEP services. That means fallback and error-handling logic can be tested without live Correios, ViaCEP, or CepAberto endpoints. You can also pass a restricted provider list in your own tests to avoid unpredictable network behavior.
- What happens when a CEP provider fails or returns an empty result?
- The package is designed to try the configured provider chain and fall back when a lookup does not succeed. Failures are generally surfaced as CepPromiseException, but the behavior for edge cases such as an empty provider array or an unknown provider class should be verified in your installed version. Test your error contract explicitly if address lookup failures affect customer-facing flows.
- How should I handle and log CEP lookup exceptions in Laravel?
- Catch CepPromiseException around your fetch call and convert it into your application’s error response, job failure record, or log entry. Version 1.2.0 fixed toArray on CepPromiseException, which matters when exception serialization is used for logs or API error payloads. Also test whether provider-level exceptions can escape fetch in your version so your catch blocks are complete.
- Is claudsonm/cep-promise-php production-ready and actively maintained?
- It has useful production signals, including mocked HTTP test coverage, PHP 8 support, and injectable provider selection in v1.2.0. The main caution is project maturity: release notes are in Portuguese and the project appears to be small and single-maintainer, so bus factor is a real concern. Pin the version, monitor updates, and consider caching or an internal fallback path for critical address flows.
- What are alternatives to claudsonm/cep-promise-php for CEP lookup in Laravel?
- Alternatives include dedicated ViaCEP or Correios PHP clients, broader Brazilian address SDKs, or a small custom Guzzle client around the providers you trust. This package’s differentiator is its promise-based API and multi-provider fallback with normalized responses. Choose based on provider coverage, maintenance activity, and whether you need a promise-style interface or a simple synchronous lookup.