Framework Laravel Package

Getting Started

netflex/framework is a monorepo — the real integration point for most apps is the individual packages it ships (e.g. netflex/api, netflex/client, netflex/types, plus the framework core). Install the framework package via Composer and let its composer.json replace/provide entries pull in the subpackages, or pin the specific subpackages you need if you want to narrow the dependency surface.

composer require netflex/framework
php artisan vendor:publish --tag=netflex-config

Set the minimum environment first — an API key and app identifier are almost always required before anything resolves:

NETFLEX_API_KEY=...
NETFLEX_APP_ID=...
NETFLEX_API_ENDPOINT=https://api.netflexapp.com/v1

Where to look first:

1. The monorepo packages/ directory in the repo — each subpackage has its own README and its own src/ tree. The framework package is mostly glue: a service provider, a config file, and a facade.
2. config/netflex.php after publishing — this is the source of truth for endpoint, auth, cache, and connection settings.
3. The service provider's register()/boot() — it tells you exactly which singletons are bound (API client, query builder, cache repository) and which facades you can type-hint.
4. The Types / model classes — these map Netflex resources (structures, entries, templates, users) to PHP objects, and they're what you'll actually touch day to day.

First use case: read a structure and its entries. Typically this looks Eloquent-ish:

use Netflex\Structure\Structure;
use Netflex\Structure\Entry;

// enumerate structures the API key can see
$structures = Structure::all();

// query entries on a structure
$entries = Entry::where('structure_id', $structureId)
    ->where('published', true)
    ->limit(20)
    ->get();

foreach ($entries as $entry) {
    echo $entry->name;           // field access via magic getters / types
    echo $entry->url();         // helper methods defined on the typed model
}

If that runs, your auth, endpoint, and HTTP layer are wired correctly. Everything else is incremental.

Implementation Patterns

Eloquent-shaped resource access. The dominant pattern is treating Netflex resources as models with a fluent query builder: Model::where(...)->orderBy(...)->limit(...)->get(), lazy iteration via cursor(), and relation-style traversal where the API supports it. Because this mimics Eloquent, developers typically wrap it in repository classes so controllers and jobs never touch the static model API directly — that keeps the static call sites greppable and makes swapping in fixtures for tests tractable.

API client for anything outside the model layer. When the SDK hasn't typed an endpoint yet (and there will be some), drop to the underlying client and issue raw requests. Bind it from the container rather than new-ing it:

use Netflex\Api\Client;

public function __construct(private Client $api) {}

public function sync(): array
{
    return $this->api->get('structures/123/entries', ['limit' => 1000]);
}

This same client is what backs the model layer, so auth, retries, and middleware apply uniformly.

Cache-as-a-first-class concern. Netflex sits behind an HTTP API, so response latency is real. The idiomatic pattern is to cache read-heavy queries with a tagged repository keyed on structure/entry ID, and invalidate on write or on a webhook from the Netflex admin. Most production apps define a NetflexCache decorator around repositories:

Cache::tags(['netflex', "structure:{$id}"])->remember(
    "entries:{$id}:{$page}",
    now()->addMinutes(10),
    fn () => Entry::where('structure_id', $id)->get()
);

Keep the tag vocabulary centralized so a webhook handler can flush a single structure's slice instead of nuking everything.

Blade and frontend integration. The framework is designed so templates and structures are addressable from Blade. The pattern that scales is resolving a structure once in a view composer or a layout-level service, then passing typed entry objects down — avoid calling Entry::where(...) directly inside Blade partials, since that turns every render into an unpredictable N+1 against the API.

Jobs and scheduled syncs. Bulk reads, imports, and cache warming belong in queued jobs with $timeout tuned above expected API latency and $tries kept low (API failures are rarely transient). Schedule cache warming with withoutOverlapping() so a slow API day doesn't stack workers.

Testing seams. Because models are static, the highest-leverage move early on is a thin repository layer plus the container bindings — that's the difference between an app you can test with mocked clients and one you can only test against the live API.

Gotchas and Tips

The monorepo is not the install target. Installing netflex/framework directly works but drags in every sibling package. If Composer resolution gets noisy or you need a specific subpackage version, require the subpackage (netflex/api, etc.) and let the framework be a dev-only or transitively-resolved dependency. Read the monorepo's root composer.json before assuming one package owns the config file.

Static models and the container don't mix well in tests. Static resource calls bypass the container, so $this->mock() won't intercept them. Either use the client/respository seams for anything you intend to test, or reach for whatever fake/swap hook the framework exposes — check the service provider for a swap-style binding before writing your own.

Config caching eats env vars. After php artisan config:cache, env() calls inside the package's config may return null if they're resolved lazily. Publish the config and reference config('netflex.*') in your own code, never env('NETFLEX_*') outside the config file. This is the single most common "it worked locally" failure with Laravel API integrations.

Rate limits and pagination are your problem. The SDK gives you a client; it does not automatically back off. Wrap calls in a retry with exponential backoff, and always drive large reads with pagination or cursor() rather than a large limit. Watch for endpoints that cap page size at 100 — passing limit=1000 often silently truncates rather than erroring.

Cache invalidation via webhooks. Netflex admin writes won't invalidate your local cache. Wire the webhook endpoint, verify its signature, and translate each payload into a targeted tag flush. Without this you'll find yourself setting TTLs to minutes, which defeats the purpose.

Debugging the HTTP layer. When a call returns an unexpected shape, enable the SDK's HTTP logging (or attach Guzzle middleware via the client binding) and inspect the raw response before blaming the typed model. Most "field is null" bugs are actually a field name mismatch between your structure definition and what the API returns — dump the raw array alongside the model.

Extension points worth knowing. Before writing wrappers, check for: custom casts/types for your own field shapes, query-builder macros (often registered in the service provider), model events, and the client's middleware stack. Adding a cast is usually cheaper and more durable than post-processing arrays in a repository.

Version pinning matters more than usual here. With zero dependents and a single-maintainer signal, breaking changes can ship without a wide ecosystem buffer. Pin exact versions in composer.json and read the changelog on every bump — you're the early adopter, so treat minor versions as potentially breaking.