Sdk Laravel Package

Getting Started

Reality check first: this repository is a read-only subtree split of the Netflex SDK component from netflex/framework. It has 0 stars, 0 dependents, and the last release was 2025-01-29. In practice that means:

• Do not target netflex/sdk directly for new work. Install netflex/framework unless you have a specific reason to pull only the SDK layer.
• Do not open issues or PRs here — they belong in the parent repo. This repo exists only so Composer can resolve the component in isolation.
• Expect sparse external documentation. The authoritative reference is the source in netflex/framework and the Netflex platform API docs (Netflex is a Norwegian CMS/e-commerce SaaS; the SDK is the PHP client for that API).

Minimal setup:

composer require netflex/sdk

Then look, in this order:

1. src/ — the client entry point and resource/entity classes.
2. The service provider (registered via package discovery) — this tells you what is bound into the container and which config keys exist.
3. config/ (if published) or the provider's mergeConfigFrom call — for base URL, credentials, and cache settings.
4. tests/ — the fastest way to learn the intended call shape when docs are absent.

Typical first use case: authenticate against the Netflex API and read a single resource (a structure/page, a customer, or a product) to confirm credentials and connectivity before building anything on top.

// Shape will vary — verify class names against src/
$client = app(\Netflex\Sdk\Client::class);

$resource = $client->get('structures', $id);

If a Client or similarly named entry class is not resolvable from the container, fall back to constructing it manually with your config array — that is the signal the provider did not auto-register (see Gotchas).

Implementation Patterns

Wrap it, don't sprinkle it. Because the SDK surface is small and lightly documented, the highest-leverage move is a thin application-level adapter: one class that owns the SDK instance and exposes your domain methods (getPage, createOrder, syncProduct). This isolates you from API churn and gives you a single seam for caching, retries, and logging.

final class NetflexGateway
{
    public function __construct(private \Netflex\Sdk\Client $client) {}

    public function page(string $id): ?array
    {
        return Cache::remember("netflex.page.$id", 300, fn () =>
            $this->client->get('structures', $id)
        );
    }
}

Bind credentials through config, not code. Put base URL, API key/token, and any tenant identifier in config/services.php or a dedicated config/netflex.php, sourced from env. Never hardcode a tenant ID — Netflex deployments are multi-tenant and the same code will hit staging and production sites.

Treat reads and writes differently.

• Reads: cache aggressively (structures and content change on publish, not on request). Cache invalidation via webhooks or a short TTL is usually enough.
• Writes: no caching, explicit timeouts, and log the request payload at debug level. Write failures against a CMS API are the expensive ones to debug after the fact.

Pagination and filters. Content APIs are list-heavy. Encapsulate pagination in the gateway (iterate() generator) rather than leaking page cursors into controllers — otherwise every caller reinvents the loop and one of them gets the termination condition wrong.

Error handling. Distinguish three failure classes and handle them separately:

• Transport failures (timeout, DNS, 5xx) → retry with backoff, then fail loudly.
• Auth failures (401/403) → do not retry; surface as a configuration error, not a user-facing one.
• Validation/domain errors (422) → pass through to the caller with the API's message intact.

Integration with Laravel. Prefer constructor injection of your gateway over app()/facades. If you need the SDK in queued jobs, keep the payload small (IDs, not serialized SDK objects) and re-resolve the client inside handle() — the client is not designed to survive serialization.

Testing. Since you cannot rely on upstream test fixtures, wrap the SDK client in an interface and bind a fake in tests. Hitting the real API in CI is a trap: it is a live tenant, it is slow, and credentials will leak into logs eventually.

Gotchas and Tips

The subtree split is the biggest gotcha. Bug reports filed here go nowhere, and fixes merged here do not exist. Always check whether the class you are patching lives in netflex/framework and contribute there. Pin your version constraint to the parent package where possible; otherwise you can end up with netflex/sdk and netflex/framework resolving to divergent versions of the same code and producing "class not found" or, worse, silently inconsistent behavior.

Version drift between the split and the parent. A split published 2025-01-29 may lag the framework by days or weeks. If a method you saw in the GitHub history is missing, that is usually why — Composer resolved an older tagged split.

Zero dependents means zero community answers. There will be no Stack Overflow trail, no blog posts, no third-party wrapper. Budget for reading source. When you learn something non-obvious, write it down in your repo — you are the documentation.

Debugging the HTTP layer. The fastest diagnostic is to capture the outgoing request before it leaves the app. Log method, URL, and headers (redact the auth header) at debug level around the SDK call. If the SDK wraps a PSR-18/Guzzle client, you may be able to swap in a logging handler via the container binding — check the provider before assuming you need to fork.

Config merge quirks. Packages that use mergeConfigFrom silently ignore your published config if you cached config before publishing. After any config change: php artisan config:clear. This one burns people constantly on low-traffic packages where the config was published months ago and quietly diverged.

Extension points are scarce by design. A subtree split exposes the public API but not the internal wiring the framework uses. If you find yourself wanting to override a resource class, that is a strong signal you should be depending on netflex/framework instead — that is where the binding overrides and macros live.

Authentication is likely tenant-scoped. Netflex credentials typically map to a specific site/tenant. Caching under keys that omit the tenant ID will produce cross-tenant data leaks the moment you run a multi-site setup or share a Redis instance between staging and production. Always namespace cache keys by tenant.

Rate limits are unadvertised. Assume a limit exists and put a token bucket or a simple RateLimiter in front of bulk operations (content migration, product sync). Discovering the limit halfway through a 50k-item import is a bad afternoon.

Check the parent before writing an adapter. The framework may already ship helpers for pagination, caching, or model mapping that the split does not make obvious. Five minutes in netflex/framework frequently saves an afternoon of reinvention.