Client Laravel Package

Technical Evaluation

Architecture fit

• The package is a thin HTTP wrapper around the CheddarGetter REST API, not a Laravel package. There is no service provider, facade, config publishing, or contract binding, so it slots in as a low-level SDK at the outermost edge of the domain — behind an adapter we own, never referenced directly from controllers, models, or jobs.
• Because it carries no framework opinions and no ORM coupling, it is portable and easy to isolate. That neutrality is the package's main architectural virtue; it is also the reason nearly all integration value has to be built by us.
• The product domain is recurring billing (customers, plans, subscriptions, transactions), which is high-blast-radius. The client must sit behind a BillingGateway interface so the vendor SDK is a swappable detail rather than an assumption baked into application code.

Integration feasibility

• Composer-installable and MIT-licensed, so there is no legal or packaging barrier to adoption or to forking.
• The practical unknown is dependency compatibility. A 2020-vintage release likely pins an older Guzzle (or bundles raw cURL), which may collide with the Guzzle version shipped by current Laravel releases. A 30-minute composer require spike against our actual PHP/Laravel matrix resolves this before any planning commitment.
• PHP 8.x compatibility is unverified: expect deprecation notices, missing type declarations, and possible fatal errors on 8.2+. This is patchable under MIT but must be scoped as our work, not the vendor's.

Technical risk

• Staleness (high). Last release October 2020; roughly five years without a tag. No PHP minor-version maintenance, no security response path, no deprecation runway.
• Bus factor (high). 28 stars, 0 dependents, single-maintainer history. There is effectively no community, no issue-triage cadence, and no Stack Overflow corpus to lean on. Every question becomes a vendor-ticket or read-the-source question.
• Vendor viability (medium-high). The SDK's health is downstream of the CheddarGetter SaaS itself; current ownership, roadmap, and API investment need diligence before we couple revenue flows to it.
• Thin safety surface (medium). Expect coarse exception types, no built-in retry/backoff, no idempotency-key plumbing for charge creation, no PSR-3 logging hooks, and no PSR-18 abstraction we can swap or decorate. Each gap is one we fill.
• Credential handling (medium). API-key auth means secrets management, redaction in logs, and rotation are entirely our responsibility.

Key questions

1. Which PHP and Laravel versions does the client actually run on cleanly, and what Guzzle constraint does it impose?
2. Does it expose idempotency keys on charge/subscription creation, or must we synthesize them?
3. How are 429s, timeouts, and 5xx responses surfaced — exceptions, return codes, or silent failure?
4. Is the underlying CheddarGetter API under active development, and is there a commercial support tier?
5. Does it verify and parse webhooks, and is there replay protection?
6. What is the true cost of a hand-rolled client (~400–600 LOC against a documented REST API) versus forking and maintaining this one?

Integration Approach

Stack fit

• Bind the client as a singleton in a dedicated service provider, with credentials sourced from config/services.php and environment secrets — never from committed config.
• Wrap it in an adapter implementing our BillingGateway contract; keep every vendor type inside that namespace. Application code sees our DTOs, not the SDK's arrays or objects.
• Treat the SDK as an implementation detail of one integration module, with contract tests around the adapter so a swap (or a fork) does not ripple outward.

Migration path

• Greenfield: install behind the adapter from day one; no direct SDK usage permitted outside the integration namespace, enforced by an architecture test.
• Replacing an existing billing provider is a data-migration project, not a client-swap: plan subscription-state migration with vendor assistance, run shadow reads in parallel, and cut over per-plan rather than per-account.
• Where the SDK proves unusable on our PHP version, fork it into our namespace and patch — MIT permits this and it is likely cheaper than waiting for an upstream that has not shipped since 2020.

Compatibility

• Validate a matrix of PHP 8.1/8.2/8.3 against Laravel 10/11 before commitment; record the Guzzle resolution outcome as a gate.
• Confirm the sandbox environment exists and behaves like production, since contract tests are the only reliable regression net we will have.

Sequencing

1. Two-day spike: install, authenticate against sandbox, complete one customer→plan→subscription→cancel cycle, document gaps.
2. Build adapter, config, secrets wiring, and exception translation.
3. Implement core flows incrementally with contract tests per flow.
4. Add webhook ingestion (queued, idempotent, replay-safe).
5. Harden: retry/backoff, idempotency, timeouts, structured logging, alerting.
6. Write internal runbook and API-model documentation before first production charge.

Operational Impact

Maintenance

• We own this. Budget a standing allowance for PHP-version patches and dependency bumps; assume zero upstream fixes and plan the fork as the default, not the contingency.
• Track the SDK as a supply-chain item: single maintainer, no release cadence, no CVE process. Pin the version and review before any bump.

Support

• SDK support is best-effort and community-scale (effectively us). Vendor support depends on our CheddarGetter contract tier and covers the API, not the PHP client.
• Internal documentation must compensate for the absent public knowledge base; the runbook becomes the primary onboarding artifact.

Scaling

• The binding constraint is vendor API rate limits, not our application tier. Add client-side throttling and push all billing calls onto queues with backoff.
• Never call billing synchronously in a user request path; checkout, upgrades, and cancellations should enqueue jobs and reconcile asynchronously.
• Webhook ingestion must be queued, deduplicated, and ordered-tolerant to survive vendor retries and burst delivery.

Failure modes

• Duplicate charges from retried creates without idempotency keys — the highest-severity risk and the one to engineer against first.
• Silent exception swallowing leading to subscription state drift between our database and the vendor.
• Vendor outage blocking checkout and plan changes; needs a degradation story and user-facing messaging.
• Credential exposure through unredacted logs or verbose exception dumps.
• Post-upgrade breakage: a PHP or Guzzle bump silently breaks the unpinned client in production.

Ramp-up

• The API surface is small enough that a competent PHP developer is productive inside the adapter in two to three days.
• The real learning curve is CheddarGetter's product model — how products, plans, pricing tiers, and transactions relate — plus its billing semantics. Budget a week for genuine domain fluency, not just API fluency.
• The adapter and contract tests are the onboarding accelerant: they encode vendor behavior so new engineers learn our model first and the vendor's second.

Overall: conditional go. The package is technically adequate but operationally orphaned; approve only with the adapter boundary, a fork-and-patch budget, and the two-day compatibility spike completed first. If the spike shows PHP 8 incompatibility and no sandbox access, a purpose-built client is the lower-risk path.