Rsflowhub Php Laravel Package

Getting Started

v1.0.0 is the first tagged release of rsflowhub/rsflowhub-php, so it establishes the stability baseline rather than documenting a change set — the release body is only a link to the commit list, which means the initial commit history is the changelog. Read it once before adopting.

• Install: composer require rsflowhub/rsflowhub-php (confirm the exact vendor/package string on Packagist; the GitHub org name and the Composer name are not guaranteed to match).
• Look here first, in order: composer.json (PHP version floor, PSR-4 namespace, Guzzle/HTTP client constraints), README.md (auth model and the minimal call example), then src/ root (client class, exception types, config/options object), then tests/ if shipped.
• Assume framework-agnostic. This is a plain PHP SDK, so there is no service provider, facade, or publishable config. You own the Laravel wiring.
• First use case: a single read-only call in php artisan tinker — authenticate, hit the cheapest list/ping endpoint the API offers, dump the raw response. Confirm credential shape (token vs. key/secret pair) and error format before writing any abstraction. Almost every early integration bug is an auth-header or base-URL mistake, and this isolates it in one step.

Implementation Patterns

• Bind it once, in a dedicated provider. Register the SDK client as a singleton with $this->app->singleton(Client::class, fn () => new Client(config('services.rsflowhub'))). Constructing a client per call throws away connection reuse and makes timeout config impossible to reason about.
• Configure through config/services.php, never inline. Add a rsflowhub block reading env() values there and nowhere else — this survives php artisan config:cache, which direct env() calls in providers do not.
• Put a gateway between your domain and the SDK. A single RsFlowHubGateway class with methods named after your use cases (createRecord, fetchStatus) rather than after API endpoints. When the SDK changes method signatures — likely, given v1.0.0 — you edit one file.
• Map responses to your own DTOs at the boundary. Hydrate into readonly value objects or Laravel Resources immediately; never let a raw SDK response object travel through controllers, jobs, or Blade views.
• Wrap calls in a decorator for cross-cutting concerns. Logging with a correlation ID, timing, and exception translation all belong in one wrapper implementing the same gateway interface, so the underlying client stays untested boilerplate.
• Queue anything that writes. SDK calls are synchronous and blocking; a slow upstream on a web request is a slow page. Dispatch a job, return 202, and let the queue absorb retries.
• Test with fakes at the transport layer. If the SDK accepts an injected HTTP client or handler, build a MockHandler in a base TestCase; otherwise Http::fake() only helps if the SDK sits on Laravel's client (it likely does not). Store real response payloads as fixtures and replay them.
• Keep an Http:: escape hatch for endpoints the SDK hasn't wrapped yet. You will hit one during rollout; a small RsFlowHubRaw client using Laravel's HTTP client avoids forking the package for a missing method.

Gotchas and Tips

• v1.0.0 with an empty changelog body is a yellow flag, not a red one. Pin the exact version ("1.0.0", not "^1.0") until you've read the source, and check the commit count and dates — a release cut from a handful of commits over a few days behaves very differently from one backed by months of work.
• Set timeouts explicitly. HTTP-client defaults in most PHP SDKs are generous or absent; without connect_timeout and timeout, a hung upstream ties up PHP-FPM workers until the request limit kills them.
• Audit retry behaviour before enabling it. If the SDK retries internally, stacking Laravel retries on top multiplies attempts — dangerous on non-idempotent POSTs. Prefer retries at exactly one layer, and only on idempotent verbs.
• Translate exceptions, don't leak them. Catch the SDK's base exception in your gateway, convert to a domain exception, and let Laravel's handler render it. Otherwise a 429 or auth failure surfaces to your user as a 500 and pollutes your error tracking.
• Verify PSR-18/PSR-17 compliance. If the client is built on PSR interfaces you can swap in any implementation and mock it cleanly; if it hardcodes Guzzle, your test strategy is narrower than you'd like. This is the single most important thing to check in composer.json.
• Debug by logging the raw request, not the exception. SDK exceptions frequently drop the response body. Add a temporary handler or Log::debug in the decorator that captures status, headers, and body before translation — it saves hours against undocumented error envelopes.
• Prefer decorating over forking. If you need behaviour changes, wrap the client. Fork only if upstream is unresponsive; a fork of a v1.0.0 package is a maintenance tax with no upgrade path.
• Expect the surface to move. Treat every SDK method name as provisional through the 1.x line, keep the gateway thin, and re-read the changelog on each minor bump rather than assuming semver discipline from a first release.