Clearfacts Laravel Sdk Laravel Package

Technical Evaluation

Architecture fit

• chuckbe/clearfacts-laravel-sdk is a thin Laravel wrapper over the ClearFacts accounting API, built on Saloon (a PHP HTTP-client abstraction for API integrations). It follows idiomatic Laravel packaging (service provider, publishable config, facade-style access), so it slots into our existing Laravel footprint without introducing a new architectural pattern.
• Footprint is small and low-coupling: it is an outbound integration client, not an infrastructure component. It does not touch persistence, queues, or auth internals.
• Maturity signal is weak: v0.2.0, one PR, one new external contributor. Treat this as an early-adopter dependency, not a platform primitive.

Integration feasibility

• composer require plus config publishing; the only real gate is transitive dependency resolution.
• Saloon 4 is the decisive constraint. If any other package or in-house integration in the estate still requires Saloon 3, Composer will hard-fail — Saloon 3 and 4 cannot coexist in one lockfile. This must be checked before any commitment.
• Saloon 4 raises the PHP floor and drops older Laravel support; confirm the package's own constraints (php, illuminate/*) against our standard runtime image before scheduling work.

Technical risk

• Security-driven breaking change. v0.2.0 exists solely to move off Saloon < 4, which carries published security advisories. This is a positive remediation, but it means v0.1.x must be treated as unsuitable for production and excluded from any allowlist.
• A major-version bump of the HTTP layer can change retry behaviour, authenticator lifecycle, middleware ordering, and response/error handling — all of which are exactly the surfaces that fail silently in production integrations.
• Supply-chain concentration: a small, single-maintainer package wrapping a vendor API. Low bus factor on both the SDK and our ability to patch it.
• Unverified: whether the SDK's public surface (methods, DTOs, exceptions) changed, or whether the bump is purely internal.

Key questions

1. What are the exact php and illuminate/* constraints in v0.2.0, and does Saloon 4 force PHP 8.2+?
2. Is Saloon pinned as ^4.0, and are there any remaining advisories against that range?
3. Did the bump alter the SDK's public API, or only the Saloon internals?
4. Does the SDK handle token refresh, retry/backoff, and 429 rate-limit responses, or is that on us?
5. Which ClearFacts API version is targeted, and is it pinned or floating?
6. Is this maintained by ClearFacts or a third party? Is there a support path beyond GitHub issues?
7. What test coverage exists, and is there a sandbox environment for validation?

Integration Approach

Stack fit

• PHP 8.2+ / Laravel 10–11 / Composer 2 is the likely baseline; verify against our runtime image.
• Fit is clean for teams already on Saloon (many Laravel API integrations are). It is a non-starter for any service pinned to Saloon 3.

Migration path

• From v0.1.x: a composer update that drags the whole Saloon major bump with it. If we only consume the SDK, this is likely a lockfile change plus regression testing.
• If we extended the SDK (custom connectors, request subclasses, authenticators, middleware), budget real porting effort: Saloon 4 changed base classes, authenticator contracts, and response handling in ways that break subclasses.
• From nothing: greenfield, no migration debt — but validate before adopting.

Compatibility

• Explicitly pin saloonphp/saloon:^4.0 and chuckbe/clearfacts-laravel-sdk:^0.2 in the root composer.json.
• Run composer why-not saloonphp/saloon 4 across every service that touches ClearFacts or Saloon before committing.
• Add a Composer audit step to CI so a future downgrade or transitive re-introduction of Saloon 3 fails the build.

Sequencing

1. Inventory — enumerate all Saloon 3 usage across the estate; identify conflicts.
2. Spike — install v0.2.0 in a throwaway branch on our target PHP/Laravel versions; confirm resolution and boot.
3. Contract test — exercise auth, a read call, a write call, and an error/429 path against a ClearFacts sandbox.
4. Wrap — put the SDK behind an internal interface/adapter so downstream code never imports SDK classes directly.
5. Pilot — one non-critical workflow, queue-driven, behind a feature flag.
6. Broaden — widen scope only after a stable observation window.

Operational Impact

Maintenance

• Pre-1.0 with a single release-driver: expect API churn and infrequent, batched updates. Our adapter layer is the mitigation — it confines future breaking changes to one file.
• Pin exact versions and upgrade deliberately; do not float on ^0.2 in production without re-running the contract test.

Support

• Upstream support is GitHub issues only, with no SLA. Escalation for API-level problems runs through the ClearFacts commercial/support channel, not the package maintainer.
• Internally, designate one owner. A dependency with one external contributor should not be orphaned.

Scaling

• Throughput is bounded by ClearFacts' API rate limits, not by our infrastructure. The SDK is an outbound HTTP client; it will not be our bottleneck.
• Route all calls through queued jobs with concurrency caps, and cache read-heavy reference data locally.
• Configure retry/backoff explicitly rather than relying on defaults — Saloon 4's defaults may differ from 3's.

Failure modes

• Dependency conflict — a Saloon 3 requirement elsewhere blocks deploys with an unresolvable lockfile. Detect early via CI.
• Silent behaviour change — altered retry/auth semantics after the major bump can turn transient 5xx into hard failures, or vice versa.
• Token expiry / auth drift — unhandled refresh leads to 401 storms during long-running jobs.
• Rate limiting — unthrottled bursts returning 429s; needs backoff and a dead-letter path.
• Upstream outage — accounting API downtime stalls dependent workflows; isolate with queues and idempotency keys on writes.
• Abandonment — package goes stale against ClearFacts API changes; the adapter layer buys us an exit.

Ramp-up

• ~1–2 days for a Laravel developer already familiar with Saloon: install, configure credentials, wrap, test.
• Add ~2–3 days for teams new to Saloon's connector/request/authenticator model.
• Add ~1 day for the estate-wide Saloon compatibility audit — this is the item most likely to surface a blocking surprise.