Cep Php Laravel Package

Technical Evaluation

Architecture fit

• The package is a thin, opinionated adapter for Brazilian CEP (postal code) lookups: a stable facade-style surface (Cep::get(), Cep::race(), SomeProvider::get()) returning a CepResponse DTO, with provider-specific logic behind it.
• v2.0.0 collapses the HTTP layer: Saloon is gone and each provider builds its own PSR-7 request via request() / handleErrors() / toDTO(), dispatched on Guzzle. Fewer moving parts, one fewer third-party abstraction, and the extension seam is now a plain subclass with typed hooks rather than a framework-specific request/connector pair.
• Fits the common use cases well: checkout address autofill, shipping quote prefill, CRM/billing data enrichment, and bulk backfill via the promise-based async path.
• Provider::useClient() is the architecturally significant addition: it makes the transport injectable, which is what enables proxying, retry policy, and deterministic tests without a mocking framework.

Integration feasibility

• Low effort for standard consumers: if we only call Cep::get(), Cep::race() or Provider::get(), the release notes state behavior, provider order, endpoints and timeouts are identical to v1.2.0.
• Guzzle is already present in effectively every Laravel application, so the new hard dependency is unlikely to add a package to the tree.
• Moderate effort only if we have custom providers or Saloon-based test fakes — both are explicitly breaking.

Technical risk

• Highest risk — silent test regression. Saloon's MockClient no longer intercepts. Any existing test relying on it will not fail loudly; it will attempt real network calls. This must be treated as a mandatory code-search item, not a nice-to-have.
• Hard removals: Saade\Cep\Requests\* and Saade\Cep\Connectors\RaceConnector are gone. Any direct reference is a fatal error at autoload/instantiation time.
• Transitive dependency pressure: the new floor guzzlehttp/guzzle: ^7.15.2|^8.0.1 can force upgrades elsewhere. Older Guzzle releases carry published advisories, so this is intentional — but it can surface conflicts with packages pinning older Guzzle, and Guzzle 8 support across the rest of our stack needs verification.
• Signature change: getAsync() / sendAsync() no longer accept a connector while still returning a Guzzle promise. Any wrapper code passing a connector breaks at call time.
• Dependency ownership shift: if anything in our app relied on Saloon arriving transitively through this package, it must now be required explicitly — otherwise a composer update elsewhere can remove it.
• Overall: the change is small in surface area but concentrated in exactly the places teams customize, so risk is "low blast radius, high surprise factor."

Key questions

• What is the supported PHP/Laravel matrix for v2, and does it match our current runtime?
• Does our framework version tolerate Guzzle 8, or must we stay on 7.15.2+?
• Do we have any custom providers, or any code referencing Saade\Cep\Requests\* / RaceConnector?
• Do our tests use Saloon MockClient anywhere against this package?
• Does anything in our app depend on Saloon being installed transitively?
• What is the intended behavior when every provider in race() fails — exception type, aggregation of errors?
• Does race() cancel losing in-flight requests, or do they complete and consume quota?
• Per-provider rate limits, terms of use, and whether any provider requires an API key or attribution.
• Maintenance posture: single maintainer, release cadence, and how quickly Guzzle security floors get bumped.

Integration Approach

Stack fit

• Standard Laravel/PHP service with Composer. Requirements: PHP per package constraint, guzzlehttp/guzzle ^7.15.2|^8.0.1, and the package's Laravel service provider/facade registration.
• Transport is now a first-class, replaceable concern via Provider::useClient(), which fits cleanly behind our existing HTTP conventions (proxy egress, correlation IDs, retry policy).

Migration path (v1.2.0 → v2.0.0)

1. Inventory usage: grep for Cep::, Saade\Cep\, Requests\, RaceConnector, getAsync, sendAsync, MockClient.
2. Raise Guzzle first, independently: composer why guzzlehttp/guzzle and composer update guzzlehttp/guzzle on a branch, run the full suite. Isolating this step separates dependency-conflict failures from package-API failures.
3. If Saloon is used anywhere else in the app, add it as a direct requirement before upgrading so nothing disappears transitively.
4. Upgrade the package to ^2.0.
5. Port custom providers to the new shape: request(): RequestInterface, handleErrors(ResponseInterface): void, toDTO(ResponseInterface): CepResponse. Note the release-note example uses a raw GuzzleHttp\Psr7\Request with manual JSON decoding via $this->json($response).
6. Convert test fakes from Saloon MockClient to Provider::useClient() with a Guzzle MockHandler/HandlerStack. Add an assertion or CI guard that no real network egress occurs in unit tests.
7. Reset the injected client to null between tests to avoid leaking a fake across the suite.

Compatibility

• Verify Guzzle 8 against our other HTTP-dependent packages before adopting; otherwise pin ^7.15.2 and accept the floor.
• Confirm the package's Laravel/PHP constraints against our runtime before bumping; do not assume v2 widened support.
• Provider::useClient() is global/static in shape — if we inject a client, it affects every provider for the process. Account for that in long-running workers (Octane, queue workers) where state persists across requests.

Sequencing

• Non-production first: dependency bump → package bump → provider port → test-fake conversion → staging smoke against real providers → production behind a feature flag with the old path as fallback for one release cycle.
• If we have no custom providers and no MockClient usage, this collapses to a same-day dependency bump plus a staging smoke test.
• Do not bundle this with unrelated dependency upgrades; the Guzzle floor change deserves its own change window.

Operational Impact

Maintenance

• Net positive: one fewer dependency, and the security advisories inherited from Saloon 3 are cleared. Smaller supply chain and a narrower CVE surface for a package whose only job is outbound HTTP.
• Cost shifts to us for anything customized: a hand-written provider is now entirely our code with no framework scaffolding, so we own its request construction, error semantics and DTO mapping.
• Ongoing obligation: track Guzzle security releases, since the package's floor will keep moving on future releases. Expect future minor bumps to raise the Guzzle minimum as advisories land.
• Provider endpoints and payload shapes are external and can change without notice; the DTO mapping is the buffer, and it is our code for custom providers.

Support

• v2.0.0 is a fresh major. Budget for a patch release or two shortly after adoption, particularly around async error propagation and the new useClient() behavior.
• Single-maintainer, small-package risk: upstream responsiveness to provider breakage is not guaranteed by an SLA. Plan to be able to fork or vendor the provider classes if needed.
• Upstream providers (Correios, ViaCEP, etc.) have their own availability and terms; support burden for "CEP lookup failed" is mostly provider-side and needs a documented triage path.

Scaling

• CEP lookups are chatty and highly cacheable. Put a Laravel cache in front with a long TTL (address data is effectively static) — this is the single biggest lever and dwarfs any transport optimization.
• Cep::race() fans out to multiple providers per lookup: outbound request volume and egress scale with provider count, and p95 latency is bounded by the slowest participating provider, not the fastest, unless losers are cancelled (unconfirmed).
• Per-provider timeouts (the example shows protected float $timeout = 5) compound under race and retry configurations; worst-case lookup latency needs to be computed, not assumed.
• For bulk enrichment, use getAsync()/sendAsync() with bounded concurrency, or push to a queue. Unbounded promise fan-out against public CEP APIs is a rate-limit incident waiting to happen.

Failure modes

• Single provider down/timeout: race() absorbs it only if at least one other provider is healthy. All-providers-down needs an explicit catch and a graceful degradation path (manual address entry) rather than a checkout-blocking exception.
• Test fakes not migrated: unit tests silently hit the network, producing flaky CI, slow suites, and unexpected egress from CI runners. Highest-likelihood operational surprise in this upgrade.
• Malformed or changed provider responses: handleErrors() / toDTO() throwing or producing partial DTOs; validate that null fields (street, neighborhood) are tolerated downstream.
• Leftover Saloon references: fatal Class not found at runtime, likely on a rarely exercised code path (custom provider, async wrapper) — hence the grep step.
• Composer conflict on the Guzzle floor: blocks the upgrade entirely and can stall unrelated work; resolve early and in isolation.
• Static client leakage: a useClient() fake set in tests or a proxy client set in a bootstrapper persisting into worker requests.

Ramp-up

• Small public API (get, race, per-provider get, CepResponse) — a Laravel developer is productive in well under a day.
• Writing or porting a custom provider is roughly a one-to-two hour task per provider given the documented pattern; the conceptual load is PSR-7 request/response handling and mapping into CepResponse.
• Documentation gaps to fill internally: exact error semantics and exception types, async usage with bounded concurrency, and the recommended caching strategy. Produce a short internal runbook before rollout — the release notes describe the what but not the failure contract.