Structures Laravel Package

Getting Started

netflex/structures is a read-only subtree split. Don't composer require it directly in an application — it exists so that netflex/framework can be consumed as smaller packages and so that tooling/composer can resolve it transitively. In practice:

composer require netflex/framework

…and let the framework pull netflex/structures (plus netflex/php-sdk) in at a matching version. If you ever do require it explicitly (e.g. in a package of your own that only needs structure models), pin it to the exact same version constraint as netflex/framework — mismatched splits are the single most common source of "class exists but method doesn't" errors with subtree-split packages.

Where to look first:

1. composer.json — check the netflex/php-sdk constraint and the PHP/Laravel version range. That tells you which API surface and which Laravel idioms (casts, attribute accessors, Collections) you can rely on.
2. src/ root — the structure model base class and its query/builder counterpart are the entry points; everything else (field casting, relations, caching) hangs off them.
3. The netflex/framework docs and the Netflex editor — the schema lives in the CMS, not in this repo. Reading the PHP source without the corresponding structure definition in the Netflex admin UI is confusing.

Minimal first use case — map a CMS structure to a class and read entries:

namespace App\Structures;

use Netflex\Structure\Structure;

class Article extends Structure
{
    protected $directory = 'articles'; // the structure's directory/slug in Netflex
}

$articles = Article::where('published', true)
    ->orderBy('published_at', 'desc')
    ->limit(10)
    ->get();

foreach ($articles as $article) {
    echo $article->title;        // field values come back as attributes
    echo $article->published_at; // cast according to the structure's field type
}

Credentials and connection config live in config/netflex.php / env (NETFLEX_PUBLIC_KEY, NETFLEX_PRIVATE_KEY, and the API base URL). Get one structure rendering in a Blade view before touching anything else — it validates credentials, the directory slug, and the field mapping in one shot.

Implementation Patterns

One class per structure, directory as the identity. Treat $directory like a table name. Keep structure classes in app/Structures and mirror the CMS naming exactly; a typo yields an empty result set rather than an exception, so it's worth an assertion in a test or a boot-time check.

Treat it as an API-backed repository, not Eloquent. The mental model that causes the fewest bugs: your structure class is a thin, cached read model over a remote content API. Writes (if supported at all in your version) go through the CMS/editor, not through the model. Design your app so content is authored in Netflex and consumed read-only in Laravel.

Query in the API, not in PHP. Push filtering, ordering, and pagination down to the query builder so you're not pulling hundreds of entries to slice them locally:

$page = Article::where('category', 'news')
    ->orderBy('published_at', 'desc')
    ->paginate(12);

Wrap structures in your own application layer. Don't let App\Structures\* leak into controllers. Add a repository/service or a view-model that returns plain DTOs or arrays. This is what makes the package swappable, testable, and insulated from schema drift:

final class ArticleFeed
{
    public function latest(int $limit = 10): Collection
    {
        return Cache::remember("articles.latest.$limit", 300, fn () =>
            Article::where('published', true)->orderBy('published_at', 'desc')->limit($limit)->get()
                ->map(fn ($a) => new ArticleSummary($a->title, $a->slug, $a->published_at))
        );
    }
}

Cache aggressively, invalidate on write. Every uncached call is an HTTP round trip. Cache at the query level with a short TTL (60–300s) and additionally hook the Netflex webhook/refresh endpoint (or your deploy pipeline) to bust tags. Tag your cache keys per structure directory so a single structure's content change doesn't nuke the whole site cache.

Blade components for content-builder blocks. If you're using Netflex's content builder, the natural pattern is: one Blade component per block type, receiving a structure entry, with a match/component-resolution map in the page template. Keep the markup tolerant of missing fields — editors leave things blank constantly.

Testing. Because the data source is remote, abstract the query behind an interface and bind a fake in tests. For integration-ish tests, record real API responses once (fixtures/JSON) and replay them; that gives you regression coverage over field-casting behaviour without hitting the network in CI. Never let the suite hit the live API — it's slow, rate-limited, and non-deterministic as editors change content.

Local development. Point at a staging Netflex project with a small, stable content set. A local dump of production content will rot within days and make your tests flaky.

Gotchas and Tips

• Never open a PR against this repo. It's a subtree split; changes are overwritten on the next split. File issues and patches against netflex/framework. If you need a local patch, use a vcs repository entry with a fork and a replace/alias, and document it — it's a maintenance burden you should be able to find again.
• Version skew is silent. Because the split is published per-component, it's possible (via a hand-edited lockfile or a package that pins an old split) to get a structures version that doesn't match framework. If you see missing methods or "call to undefined" on classes that clearly exist, run composer show netflex/* and compare versions before debugging anything else.
• Schema drift between CMS and code. Fields added in the Netflex editor appear as attributes automatically; fields removed become null without warning. There's no compile-time contract. Guard against it: validate critical fields in your DTO mapping layer, and fail loudly (throw on a missing required field) in non-production so you catch it before an editor does.
• Missing structure ≠ error. A wrong $directory typically returns an empty collection rather than throwing. If a page is mysteriously blank, check the directory string and the project/environment the credentials point at, not your Blade.
• Casting surprises. Field types defined in the CMS determine PHP types. published_at may be a Carbon instance, a string, or null. Booleans may be 0/1, "true", or true. Normalise at the boundary (in your DTO) rather than sprinkling (bool) casts through templates.
• N+1 over HTTP. Iterating entries and calling a relation/associated structure per item is far worse than the DB equivalent — each is a network call. Batch or eager-load where the builder supports it, otherwise fetch the related set once and join in PHP.
• Caching + preview. Editors expect to see changes immediately. Make sure your cache is bypassed for preview/draft requests (usually a header or query param) and that the cache key includes that flag — otherwise "it's not updating" tickets are guaranteed.
• Debugging the wire. When data looks wrong, dump the raw API response before it hits the model. Most bugs are either credentials/environment, a stale cache, or a field name mismatch — not the package. Wrap the SDK client in a small decorator that logs method, path, status, and timing behind a config flag.
• Extension points to prefer: overriding $directory and adding accessor/cast methods on your own subclass is safe and upgrade-friendly. Subclassing deep internals of the query builder is not — the split's internals move between minor versions and there are effectively zero dependents and zero stars on this package, i.e. no community pressure to keep them stable. Pin exact versions in composer.json and review the split's changelog on upgrade.
• Bus factor. With no dependents and no visible test/issue activity on the split itself, treat every upgrade as a small migration: read the netflex/framework changelog, run your fixture-backed tests, and smoke-test one structure-rendering page per content type.