Cep Promise Php Laravel Package

Technical Evaluation

Architecture fit

• The package is a thin, single-purpose HTTP client wrapper: CepPromise::fetch($cep, ?array $providerClasses) fans out to one or more Brazilian postal-code (CEP) lookup providers and normalises their responses. This is a good architectural fit for a service-layer dependency behind a domain-level PostalCodeResolver interface — it does not impose Eloquent models, migrations, or config sprawl, so it can sit at the edge of the application rather than in the core.
• v1.2.0's new optional second parameter is the most architecturally significant change: the caller can now inject the provider list. That converts a previously hard-coded collaborator set into a caller-controlled strategy, which is the difference between "vendor black box" and "composable adapter." It is the hook a TPM should push for, because it lets us constrain providers per environment (e.g. a single provider in tests/staging, a fallback chain in production) without forking.
• Residual coupling risk: the parameter takes classes, not an interface/contract. We do not yet know whether these are FQCN strings, container-resolved bindings, or instantiated objects. If it is FQCN-string-based, we cannot inject mocks or decorators cleanly and the seam is weaker than it appears.

Integration feasibility

• Low-to-moderate effort. Adding PHP 8.0/8.1 support and moving CI to GitHub Actions with matrix testing across all supported PHP versions materially de-risks adoption on a modern Laravel stack.
• 100% coverage with mocked HTTP calls is the single strongest signal in these notes. For a package whose entire job is talking to unreliable third parties, a mocked-HTTP suite means we can trust the fallback/error-handling logic without depending on live ViaCEP/Correios endpoints in our own pipeline.
• The toArray() fix on CepPromiseException is directly relevant to us: exception serialisation into logs, API error payloads, or job failure records is a common integration point, and a toArray() that throws when a provider error is not the expected subclass would have produced secondary failures during incident debugging. Worth noting as a real, if narrow, reliability win.

Technical risk

• Semantic versioning concern (highest-priority flag): the release removes support for PHP < 7.4 and Guzzle < 7.2.0 while shipping as v1.2.0, a minor bump. Under semver, dropped platform/dependency support is a breaking change and should be v2.0.0. Anything consuming ^1.0 with a permissive lockfile could resolve into a version that no longer installs. Mitigation is straightforward — pin the constraint and rely on the lockfile — but it must be explicit, not assumed.
• Provider volatility is the dominant runtime risk, and it is external. CEP providers change response shapes, rate-limit aggressively, and occasionally go dark. v1.2.0 improves testability of this but does not change the underlying fragility. The new provider-selection parameter partly mitigates by allowing fallback ordering.
• Unquantified behaviour of the new parameter: what happens with an empty array, an unknown class, or a provider that throws vs. returns empty? Whether fetch fails open or closed determines our error contract.
• Maintainer concentration / project maturity: a merge request referenced as #17 and Portuguese-language release notes suggest a small, single-maintainer project. Bus factor is a genuine concern for a dependency in a customer-facing address flow.

Key questions

1. Is the second fetch parameter a list of FQCN strings, interface implementations, or container bindings — and can we pass our own decorator for caching/telemetry?
2. What is the default provider set and its ordering when the parameter is omitted (i.e. what changes for existing callers)?
3. Are exceptions still uniformly CepPromiseException, or can provider-level exceptions escape fetch?
4. Why was a support-dropping change released as a minor? Is a 2.0.0 planned, and is there a stated support/deprecation policy?
5. Is there first-class Laravel packaging (service provider, publishable config, facade) or is this framework-agnostic PHP that we wire ourselves?
6. License terms and whether provider terms of service permit our request volume.

Integration Approach

Stack fit

• Assumes PHP ≥ 7.4 and Guzzle ≥ 7.2.0. On Laravel 9/10 with PHP 8.1 this is a clean fit; the constraint should be expressed as "php": "^8.0", "guzzlehttp/guzzle": "^7.2" in our root composer.json so the resolver cannot drift backwards.
• No database, queue, or filesystem footprint — it is a request-time outbound call, so it belongs in a service class, not in a model observer or Blade template.
• Because it is framework-agnostic by appearance, expect to write the container binding and config ourselves unless a service provider ships.

Migration path

• There is no prior assessment and no incumbent implementation documented, so this is a greenfield adoption rather than a migration. Treat it as such: no backfill, no dual-write, no data migration.
• If we later need to swap the package out, the new provider-injection parameter gives us an exit ramp: point the provider list at our own implementations first, then replace the wrapper. That is the cheapest possible de-risking and is worth exercising deliberately as a spike.

Compatibility

• Blocking constraint: any service still on PHP 7.2/7.3 or Guzzle 6.x cannot consume v1.2.0. Confirm the platform matrix before adoption; if any runtime is below 7.4, this release is unavailable to it and the previous line must be pinned.
• Lockfile and CI matrix should both be updated in the same change so local and pipeline environments cannot diverge.
• The toArray() fix is behaviour-changing for anyone who was catching and serialising the exception. Audit any log formatter or error-response mapper that touches CepPromiseException and verify the output shape is unchanged for the happy path.

Sequencing

1. Pin ~1.2.0 (not ^1.0) and confirm the PHP/Guzzle platform matrix against every runtime we deploy.
2. Spike: call fetch with an explicit single-provider list to validate the new parameter's semantics — argument type, ordering, failure behaviour — before designing around it.
3. Wrap the package in our own PostalCodeResolver interface and bind it in the container, so no domain code names the package directly.
4. Add caching (CEP data is effectively static; a TTL cache collapses both latency and third-party call volume) and a timeout/retry policy at the wrapper level.
5. Add contract tests in our own suite that assert the wrapper's error contract, so a future upstream release cannot silently change it.
6. Only then wire into the address-entry flow and instrument.

Operational Impact

Maintenance

• Low ongoing surface area: no schema, no scheduled jobs, no persistent state. The maintenance burden is almost entirely "track upstream releases" plus "monitor third-party providers."
• The move from StyleCI to PHP CS Fixer on GitHub Actions removes a third-party SaaS from the toolchain — a small but real reduction in vendor dependencies and in the number of accounts/credentials attached to the project.
• CI now runs the suite against every supported PHP version. That is a meaningful maturity step: it means PHP-version regressions get caught upstream rather than in our pipeline.

Support

• Small-maintainer project: no vendor SLA, no commercial support path. Internal ownership must be explicit — name a team that owns the wrapper and the upgrade decision.
• Portuguese-only release notes and issue tracker are an operational reality; budget for translation effort or accept slower triage on upstream questions.
• Because the wrapper is ours, most support questions stop at our boundary. That is the main reason to insist on the wrapper even though the package is thin.

Scaling

• The bottleneck is not CPU or memory, it is outbound HTTP fan-out. A multi-provider fallback chain multiplies requests per lookup, and each CEP lookup in a checkout or bulk-import flow becomes one or more third-party round trips.
• With the new provider-list parameter we can bound this: choose exactly one provider in latency-sensitive paths and use the full chain only in async/backfill paths. That is a concrete, low-cost scaling lever this release enables.
• Mandatory caching. CEP-to-address mappings are near-immutable; caching turns a per-request external dependency into a local lookup and removes provider rate limits as a scaling constraint. Without it, throughput is governed by someone else's quota.
• Bulk operations (address cleansing, import validation) should go through a queue with concurrency limits rather than synchronous fan-out.

Failure modes

• Provider outage / degraded response: the headline risk. Mitigated by fallback across providers, bounded by per-provider timeouts, and surfaced as a domain-level "postal code unresolvable" rather than a 500.
• Rate limiting or IP blocking by a provider under load — the classic failure that only shows up at scale. Cache first, then throttle.
• Version-resolution breakage: a permissive constraint pulling a release that dropped PHP support. Pinning and a lockfile in CI prevents this.
• Exception-serialisation failure: the bug fixed in v1.2.0 — previously, toArray() could throw when an error element was not a CepPromiseProviderException, turning an error-handling path into a second error. This is exactly the class of defect that makes incidents worse; its fix is a reason to take this release rather than defer it.
• Behavioural change on the default provider set if the package altered defaults alongside the new parameter — verify with an explicit-parameter vs. default-parameter comparison in staging.

Ramp-up

• Near-zero for a PHP developer: one method call, one result object, one exception type. Expect hours, not days.
• The real ramp-up is the surrounding policy, which the package does not provide and we must define: caching TTL, timeout and retry budgets, provider preference order, and the product behaviour when a CEP cannot be resolved. Document these in the wrapper, not in tickets.
• Recommend a short design note covering (a) why the version is pinned, (b) the provider strategy per call site, and (c) the error contract — so the next maintainer does not rediscover the semver and provider-volatility issues from scratch.