Recurly Laravel Package

Technical Evaluation

Architecture fit

moovly/recurly occupies a single, well-understood slot in a Laravel codebase: an infrastructure-layer HTTP/SDK adapter that talks to Recurly's REST API. It is a vendor-namespaced repackaging (or fork) of Recurly's PHP client, not a Laravel billing abstraction. There is no service provider, config publishing, facade, or queue-aware webhook handling described, and no Cashier-equivalent exists for Recurly — so whichever client we pick, we own the domain wrapper (BillingService, SubscriptionRepository, webhook consumer).

From a TPM standpoint, that reframes the decision: architecture fit is neutral and non-differentiating. Any Recurly PHP client sits in the same slot behind the same adapter. The real decision is supplier selection for that slot, and the correct default is Recurly's own recurly/recurly-client. This package is glue, not leverage — it does not unlock roadmap capability, it only changes how cheaply we wire up capability we've already decided to buy from Recurly.

Integration feasibility

Technically trivial (composer require), strategically questionable. Zero stars, zero dependents, score 0 is a strong negative signal: no public adoption, no discoverability, no evidence of maintenance. The most likely origin is an internal Moovly fork that surfaced on a public index, or an abandoned personal publication. Either way we cannot treat it as a dependency we consume; we'd be adopting source code.

Feasibility depends entirely on an answer we don't yet have: what does this fork change relative to upstream? A fork of a payment SDK is only justifiable if it carries a documented patch that upstream refused or hasn't shipped, or pins an API version we specifically need. Absent that, the fork is pure liability with no offsetting benefit.

Technical risk

• Supply chain (highest severity). Unowned third-party code in the payment path with zero external scrutiny — nobody else is reading diffs, filing issues, or catching a bad release. A payment client handles API keys and webhook signature verification; both require a trusted maintainer.
• Abandonment. Single-maintainer, low-visibility forks rot. PHP 8.x deprecations, Guzzle majors, and Recurly API version changes will not be absorbed. This becomes a blocking dependency on an unrelated platform upgrade.
• Silent divergence. Without an upstream diff we cannot know whether retry, timeout, idempotency, or signature-verification semantics differ. Divergence in a billing client surfaces as a financial discrepancy, not a test failure.
• Security and licensing. No disclosure channel, no security policy, no audit trail. Must confirm the MIT license is preserved and no incompatible code was introduced.
• Stale API version pinning. Recurly versions its API via Accept headers; an unpinned or outdated version can change behavior silently when Recurly moves defaults.

Key questions

1. Which upstream tag and Recurly API version does this fork track, and what is the diff against recurly/recurly-client?
2. Why does the fork exist — bug fix, API pin, or convenience? Is that reason still valid?
3. Is there a maintained internal branch, or is this snapshot effectively dead?
4. Does it support our PHP (8.2/8.3) and Laravel versions, and which Guzzle major?
5. Does it implement webhook signature verification, and does it match upstream?
6. Are releases tagged, semver-adhered, and changelogged?
7. Is there any named owner or SLA behind it?

Verdict to carry into planning: conditional reject. Budget it as a 1–2 day audit task, not a delivery task. Default to upstream.

Integration Approach

Stack fit

Framework-agnostic PHP SDK; all Laravel ergonomics are our work regardless of supplier. Recommended shape: package → thin RecurlyClientInterface adapter → BillingService domain API → controllers/jobs. Nothing outside the adapter imports package classes. This is the single most important mitigation, because it makes the supplier decision reversible at low cost and decouples roadmap delivery from the audit outcome.

Migration path

1. Audit (1–2 days): clone, diff against upstream, read composer.json, check license, scan for network calls or telemetry beyond Recurly endpoints.
2. Baseline against upstream: if the diff is trivial, drop the fork and take recurly/recurly-client directly. If a patch is genuinely needed, carry it as a cweagans/composer-patches patch rather than a whole forked SDK — far cheaper to own.
3. Adapter first: define our interface and contract tests (recorded Recurly fixtures) so either implementation is swappable and verifiable.
4. Shadow verification: run against Recurly sandbox; replay fixtures; compare fork vs. upstream responses where both are viable.

Compatibility

Confirm PHP constraint, Guzzle major, PSR-7/18 implementations, and any symfony/* ranges against our Laravel release. Expect no auto-discovery; if a service provider ships, verify it doesn't register conflicting bindings. Verify the Recurly API version header is explicit and pinned.

Sequencing

• Gate 1 — dependency/security audit. A fork of a payment SDK that fails audit stops here; use upstream.
• Gate 2 — adapter + contract tests merged before any feature work.
• Gate 3 — sandbox integration for the flows in scope: plans, subscriptions, invoices, transactions, webhooks.
• Gate 4 — production cutover behind a feature flag, old path retained until one full billing cycle reconciles.

Do not let roadmap pressure invert this. Billing integration work is a dependency chain; starting feature development before Gate 1 clears converts a 2-day audit risk into a multi-week rework risk.

Operational Impact

Maintenance

Effectively fork-and-own. Budget 2–5 engineer-days annually for dependency bumps plus unbudgeted incident time when a breaking change lands. Every app-wide PHP/Guzzle upgrade becomes a manual verification of an unmaintained payment SDK — that recurring tax is the true cost of "free."

Support

No vendor support: Recurly supports their API, not third-party wrappers. No community: zero dependents means no issue history, no Stack Overflow corpus, no one to escalate to. First-line debugging requires reading SDK source. Escalation path terminates internally.

Scaling

The client is not the bottleneck; Recurly is. Real constraints are Recurly's per-endpoint rate limits (429s) and webhook throughput. Require exponential backoff with jitter, idempotency keys on all mutating calls, and a queue-backed webhook consumer. If the package doesn't expose configurable timeouts and retry hooks, we wrap or fork it — which is precisely the maintenance burden we're trying to avoid, and should be costed as such in the build/buy comparison.

Failure modes

• Silent divergence — fork bug already fixed upstream, found via billing discrepancy. Mitigation: contract tests on recorded responses.
• Abandonment — incompatible with a PHP/Guzzle bump mid-quarter, blocking unrelated platform work. Mitigation: adapter isolation; swap in one file.
• Supply-chain compromise — unowned code in the payment path. Mitigation: audit, lockfile pinning, integrity hashes, no floating constraints.
• Stale API version — Recurly deprecation lands, requests fail or behave differently. Mitigation: explicit pin plus deprecation watch.
• Webhook replay/spoofing — signature verification missing or divergent. Mitigation: a test proving forged signatures are rejected; treat as release blocker.
• Credential leakage — API keys logged at debug level. Mitigation: audit logging config before prod.

Ramp-up

Low code volume, high cognitive overhead: no docs beyond the repo, so engineers read source. Estimate 1–2 days for a strong Laravel engineer to be productive against the adapter, plus the audit time. The adapter interface substantially reduces this — new engineers learn our BillingService, not the SDK — which is another reason to invest in the wrapper before evaluating the supplier.

TPM summary: plan the audit as a 2-day spike with a hard decision gate; pre-commit to upstream Recurly unless the fork carries a documented, still-needed patch; and fund the adapter regardless, because it is the only thing that keeps the supplier question cheap to revisit.