Query Builder Laravel Package

Getting Started

This package is a read-only subtree split; do not composer require netflex/query-builder in a Laravel app. Pull the parent package instead:

composer require netflex/framework

The subtree exists so tooling that expects a standalone repo (e.g. static analysis, PHPStan, monorepo explorers) can resolve it, but the canonical source of truth is netflex-sdk/framework. Any issue, PR, or docs lookup should be filed against the parent repo — changes made here are wiped on the next split.

Where to look first:

1. src/ in this repo — the Builder class and its traits are the fluent interface you'll actually call.
2. The parent framework's Query namespace — ServiceProvider wiring, connection/config classes, and model bindings live there, not here.
3. The Netflex API docs — the builder is a thin, Eloquent-flavoured facade over the Netflex REST endpoints; method names mostly mirror the API's query parameters.

First use case: fetch published entries of a given content type.

use Netflex\Query\QueryBuilder;

$entries = QueryBuilder::make('entry')
    ->where('directory_id', 1)
    ->where('published', true)
    ->orderBy('created', 'desc')
    ->limit(20)
    ->get();

If you're already on a framework model (e.g. an Entry model extending the base), you can usually reach the builder via Entry::query() / Entry::where(...) — the model proxies to the same builder, and that's the path you'll use most days.

Implementation Patterns

Fluent chaining like Eloquent. The builder's whole reason to exist is to give you where / orderBy / limit / offset / get / first / count without hand-rolling query strings against the Netflex REST API. Lean on it the way you'd lean on Eloquent — if a call feels like it should exist because Eloquent has it, check the builder traits first.

Model-scoped queries. Prefer the model entry points over instantiating QueryBuilder directly. Something like Entry::where('directory_id', $id)->get() keeps the resource type (entry, structure, etc.) and relation mappings consistent, and it plays nicely with Laravel's container resolution when your app has the Netflex ServiceProvider registered.

Repository / action wrappers. Because the builder returns paginated, API-backed collections (not Eloquent models hydrated from a DB), wrap it in a small repository so your controllers and jobs don't depend on the fluent chain directly. This matters when a query has to change shape (extra filters, caching layer, mock in tests) — you have one seam instead of dozens.

Pagination and chunking. Use limit/offset together for cursor-style loops over large result sets, and always cap the loop with a count() or the API's reported total. There's no chunk() in the Eloquent sense here; you're making real HTTP calls per page, so treat it like paginating an external service.

Caching at the query boundary. Wrap hot queries in Cache::remember(...) keyed by the serialized builder arguments. The builder itself doesn't cache, and every ->get() is a network round trip, so the cache belongs in your repository layer, not inside the query chain.

Jobs and queued sync. For anything that reads many Netflex resources (imports, sitemap generation, search indexing), run the builder in a queued job and keep the query construction in the job's handle(). Config for the API connection is resolved from the parent framework, so jobs need the same credentials — check config/netflex.php (published from the framework) is present in the worker environment.

Gotchas and Tips

It's a subtree split, not a package you own. Contributions, issues, and version tags all live in netflex-sdk/framework. If you open a PR here it disappears. Pin the parent package's version, not this one; the split's own tags are just mirrors.

Zero stars / zero dependents is a signal, not a bug. This is infrastructure for apps on the Netflex platform. If you're not building against Netflex, there's nothing here for you — reach for Laravel's own query builder or a dedicated API client instead.

Credentials are the parent framework's problem. NETFLEX_* env vars (or whatever the framework uses) must be set; a missing token typically surfaces as a 401 from the first ->get(), not at construction time. Debug by dumping the built request/URL before get() rather than assuming the chain is wrong.

No local model hydration. Unlike Eloquent, ->get() on the builder hits the API. There is no "lazy" mode. That means N+1-style loops (foreach ($ids as $id) { /* new query */ }) are real network cost — batch by building one query with whereIn-style filters where the API supports it.

first() still costs a round trip. It doesn't short-circuit client-side; it just limits the API call. Don't reach for it in a loop expecting it to be free.

Config quirks live upstream. If where() silently ignores a field, it's usually because the Netflex endpoint doesn't whitelist that query param — the builder passes through, the API drops it. Cross-check the endpoint docs before assuming a builder bug.

Extension points are traits on the builder, not service bindings. If you need to customise behaviour (default scope, logging of API calls), the practical route is decorating in your own repository/service rather than subclassing the builder — subclasses drift with the framework's internal refactors and you'll be rebasing against a read-only split.

Version skew. The split's composer.json version tracks the monorepo. If you see a mismatch between the framework you installed and this repo's code, trust the framework's vendor/netflex/framework/ copy — it's the one being autoloaded.