Clearfacts Laravel Sdk Laravel Package

Getting Started

ClearFacts is a Belgian accounting platform; this package wraps its API in a Laravel-friendly SDK built on Saloon. Day-to-day you'll use it to pull accounting data, push documents, and integrate ClearFacts into Laravel apps, jobs, and commands.

1. Install alongside Saloon 4:

   composer require chuckbe/clearfacts-laravel-sdk:^0.2.0
   

   The v0.2.0 release pins Saloon ^4.0 (see PR #1). Saloon 3.x had open security advisories, so do not stay on 0.1.x — if you are already installed, run composer update chuckbe/clearfacts-laravel-sdk saloonphp/saloon and expect to touch any custom Connector/Request/Response classes you wrote against the SDK.
2. Publish config (if the package ships one):

   php artisan vendor:publish --tag=clearfacts-config
   

   Set credentials in .env — typically something like CLEARFACTS_CLIENT_ID, CLEARFACTS_CLIENT_SECRET, and an environment switch (sandbox vs production). Check config/clearfacts.php first; that's the source of truth for what the package actually reads.
3. First use case: authenticate and fetch the current administration/user, then list a small resource (e.g. administrations or documents) to prove the credential flow end-to-end before wiring anything into jobs.

   $connector = app(\Chuckbe\ClearFacts\ClearFactsConnector::class);
   $response  = $connector->send(new \Chuckbe\ClearFacts\Requests\GetAdministrationsRequest);
   $response->throw()->json();
   

   Namespaces above are illustrative — grep the src/ tree on first install; the class names are what you'll actually copy into your IDE.

Implementation Patterns

Wrap the SDK behind your own service. Don't sprinkle Connector calls across controllers and jobs. Create app/Services/ClearFactsService.php (or a thin repository) that owns the connector, translates SDK DTOs into your domain models, and gives you one place to change when the SDK bumps (see Gotchas).

Use Saloon's MockClient in tests. Saloon 4 is fully mockable via PSR-18-compatible clients. In feature tests:

$mock = new \Saloon\Http\Faking\MockClient([
    GetAdministrationsRequest::class => new \Saloon\Http\Faking\MockResponse([/* ... */], 200),
]);
$connector->withMockClient($mock);

This is much better than hitting the real ClearFacts sandbox in CI.

Queue long-running syncs. Any bulk operation (importing documents, reconciling invoices) should be a ShouldQueue job. ClearFacts rate-limits and their API is a third-party dependency — a synchronous request in a web request will bite you on latency or auth expiry.

Centralise auth on the connector. If ClearFacts uses OAuth2, let Saloon's Authenticator and token caching do the work at the connector level (Saloon 4 changed some of this — see Gotchas). Avoid manually attaching tokens per request.

Cache read-heavy endpoints. Administrations, chart-of-accounts, and VAT codes change rarely. Wrap those calls in Cache::remember() with a modest TTL; invalidate explicitly after write operations.

Integrate with Laravel's HTTP middleware layer you already trust. Because calls go through Guzzle/PSR-18, you can attach Laravel Telescope or HTTP client events for logging. Wire up a Log::withContext(['sdk' => 'clearfacts']) in a Saloon middleware so failures in production are diagnosable.

Use Laravel's scheduler for reconciliation. A daily php artisan clearfacts:sync command, registered in Kernel::schedule(), is the idiomatic pattern for keeping your local mirror of ClearFacts data fresh.

Gotchas and Tips

v0.2.0 is a breaking dependency bump, not a feature release. The only change in this release is Saloon 3 → 4. If you extended the SDK with your own Connector, Request, Response, or Authenticator classes, expect breakage:

• Contract namespaces moved (Saloon\Contracts\... → Saloon\Contracts\... reorganised).
• Request::boot() / resolve() and middleware hooks changed signatures in places.
• The default HTTP client switched toward PSR-18; if you were passing a Guzzle-specific config array via ->config(), verify it still applies.
• MockClient and MockResponse APIs were reshaped — old test fixtures may not compile. Read the Saloon 4 upgrade guide before you merge.

Security rationale, not just a version bump. The release notes cite security advisories on Saloon < 4. Treat 0.2.0 as the minimum safe version. Pin ^0.2.0 in composer.json and add saloonphp/saloon: ^4.0 explicitly if the SDK's constraint is loose — that way composer why-not can tell you when an upstream package is blocking your upgrade.

Version 0.x semantics still apply. This is a pre-1.0 SDK; minor bumps can break your integration without a major version bump. Treat every 0.x release as potentially breaking and read the changelog. Do not use ~0.2 in composer.json without reading releases.

Credential/sandbox handling. Confirm whether the package has separate sandbox vs production clients or a single connector that switches on config. Getting this wrong in CI is a classic footgun — you don't want a scheduled job posting test invoices to a live accountant's ledger.

Extension points. The connector is the seam: subclass it (or bind a customised one in a service provider) if you need custom retry policies, circuit breakers, or headers. Saloon supports retry() and middleware on the connector itself — use those rather than re-implementing retry logic in your service.

Debugging tips. Enable Telescope HTTP client watcher or set LOG_LEVEL=debug with Saloon's Log middleware on the connector. When an API call returns a 4xx, dump $response->body() and $response->headers() — ClearFacts error payloads are usually descriptive and tell you whether it's auth, scopes, or validation.

Watch the repository for follow-ups. A single-contributor v0.2.0 that only bumps a dependency is a smell: there's no indication yet that SDK-level features (pagination helpers, DTOs, webhooks, OAuth refresh) are stable. Budget time to review each release and keep the SDK isolated behind your own service layer so an upstream break can't cascade through your codebase.