Cep Promise Php Laravel Package

Product Decisions This Supports

• Checkout and address capture: Use CEP lookup to reduce manual address entry errors and shorten Brazilian checkout/onboarding flows.
• Provider redundancy and routing: v1.2.0 adds an optional second parameter to CepPromise::fetch, allowing product/engineering to choose which provider classes are used. This supports fallback strategies, cost/performance routing, and regional provider preferences.
• Platform modernization: PHP 8.0/8.1 support and removal of PHP <7.4 and Guzzle <7.2.0 inform roadmap decisions for Laravel/PHP upgrades and dependency hygiene.
• Build vs buy: For commodity Brazilian postal-code lookup, adopting a focused package is usually cheaper than building and maintaining multiple provider integrations in-house.
• Quality and reliability: 100% test coverage with mocked HTTP calls and improved CI reduce integration risk and make the package easier to trust in production workflows.
• Maintenance investment: The exception-handling fix for CepPromiseException::toArray() reduces debugging friction when provider errors occur, supporting better observability in customer-facing flows.

When to Consider This Package

• Consider it when building a Laravel/PHP application that needs Brazilian CEP lookup and you want multi-provider querying without maintaining each provider integration yourself.
• Adopt if your platform is on PHP 7.4+ and Guzzle 7.2.0+, and you can absorb the v1.2.0 breaking changes if upgrading from older versions.
• It fits well when you need provider selection or fallback behavior, since v1.2.0 exposes provider classes through the fetch API.
• Look elsewhere if you require PHP versions below 7.4, older Guzzle versions, enterprise SLAs, official provider contracts, or address validation beyond CEP lookup.
• Reassess if your product needs global address validation, geocoding, or heavy customer-data compliance guarantees that a community package does not explicitly provide.

How to Pitch It (Stakeholders)

• For executives: This is a small, focused integration that improves Brazilian address entry without building and maintaining multiple postal-code provider integrations ourselves. The new release modernizes PHP support and strengthens automated testing, reducing long-term maintenance risk.
• For engineering: v1.2.0 is a meaningful upgrade: PHP 8.0/8.1 support, provider selection in fetch, 100% test coverage with mocked HTTP, improved GitHub Actions CI, and a bug fix in exception serialization. It also introduces breaking changes by dropping PHP <7.4 and Guzzle <7.2.0, so legacy services must upgrade dependencies first.
• Recommendation: Pilot the package in checkout/address flows where CEP lookup is non-critical but high-friction. Treat provider selection as a configuration concern, verify PHP/Guzzle compatibility, and avoid adopting it where enterprise support or non-Brazilian address validation is required.