Pages Laravel Package

Getting Started

This package is a read-only subtree split of the Netflex Pages component. Do not install it in isolation expecting a self-contained library — the canonical source of truth, issues, and pull requests live in netflex/framework. Treat netflex/pages as a convenience artifact for Composer resolution only.

Minimal steps:

1. Decide your entry point. For a real Netflex project you almost always composer require netflex/framework and get Pages transitively. Only require netflex/pages directly if you are deliberately pinning a subcomponent or building tooling that introspects the split.
2. Read the framework, not this repo. Clone netflex/framework, locate the packages/pages (or similarly named) directory. That is where commits land; this repo is regenerated from it.
3. Register the provider. In a Laravel app, the provider is normally auto-discovered via composer.json extra.laravel.providers. Confirm it appears in php artisan about / bootstrap/cache/packages.php. If you are on an older Laravel or a non-standard skeleton, add it manually in config/app.php.
4. Find the config surface first. Look for a publishable config (php artisan vendor:publish --provider=...) covering route prefixes, template/view namespaces, and cache TTLs. Read it before writing code — most "why is my page not resolving" issues are config, not code.
5. First use case: resolve a page by URL path and render it. Route a catch-all (Route::get('/{path?}', ...)->where('path', '.*')), let the package's page resolver look up the structure for that path, and hand the resulting page object to a Blade view. Once that works end-to-end, layer in templates and content blocks.

If you are evaluating rather than adopting: the 0-star / 0-dependent signal means there is effectively no community support surface. Your documentation is the source code and the Netflex platform docs. Budget time for reading.

Implementation Patterns

Model-centric access. Expect a Page-style Eloquent model (or repository) exposed by the package. Day-to-day you will query pages by path/slug, by parent, or by template, then pass the model into views. Prefer the package's query scopes over raw where() calls so published/visible/scheduling filters stay applied.

Template binding. Pages typically map to a template identifier that resolves to a Blade view. Keep the mapping in config or a dedicated registry class rather than scattering view() calls — this is the seam you will most often need to extend when a client wants a custom layout.

Route + middleware integration. The common workflow is a single catch-all route guarded by package middleware (domain/host resolution, redirect handling, 404 fallback). Put your own middleware after the resolution middleware so $request already carries the resolved page; anything before it will see an unresolved request.

Content blocks / structure traversal. Pages are usually composed of nested structures. Recurse through the structure once in a view composer or presenter, and render partials per block type via a match/switch on block type. Avoid querying inside Blade loops — eager-load or pre-hydrate the structure before the view layer.

Caching as a first-class concern. Anything served by a CMS page component should be cached at the resolved-page level (path → page ID → rendered output). Wrap resolution in Cache::remember keyed on host + path + locale, and hook the package's save/delete events to bust those keys. Netflex apps typically also sit behind a CDN, so get cache tags/keys right early.

Extending via container bindings. Where the package exposes an interface (resolver, template registry, URL generator), bind your own implementation in a service provider rather than subclassing internals. Subclassing a subtree-split package is fragile across framework upgrades.

Local development loop. Because this is a split repo, test your changes by path-repository-ing netflex/framework into your app (composer config repositories.framework path ../framework) and working against the full source. Never patch vendor/netflex/pages — it will be blown away on the next composer update.

Gotchas and Tips

• Read-only means read-only. PRs, issues, and discussions opened here will be closed or ignored. File against netflex/framework. If you need a fix, fork the framework.
• Version lockstep. This split is tagged alongside the framework. Mixing a netflex/pages version with an incompatible netflex/framework version produces subtle autoload/API mismatches. Constrain both with the same caret range, or just require the framework alone.
• Autoload duplication. If both netflex/framework and netflex/pages are required and the framework also ships the Pages namespace, you can get class-map collisions or "cannot redeclare class" errors. Check composer why netflex/pages before debugging anything else.
• Config caching bites. php artisan config:cache will freeze route prefixes and template paths. A very common symptom — "changes to config/pages.php do nothing in staging" — is a stale config cache. php artisan optimize:clear first, always.
• Resolution failures are usually path normalization. Trailing slashes, URL-encoded characters, multi-byte slugs, and locale prefixes are the top causes of unexpected 404s. Log the normalized path the resolver receives, not the raw request URI.
• Redirect loops. Page-level redirects plus a catch-all route plus trailing-slash normalization is the classic loop recipe. Ensure redirects are resolved before your catch-all and that they emit a 301 only once.
• Cache invalidation across hosts. If one page ID serves multiple domains/locales, a naive page:{id} cache key will leak content between hosts. Always include host and locale in the key.
• Eager loading discipline. N+1s on structure traversal are the most common performance regression in page-rendered apps. Watch query counts in a debug toolbar on a deep page, not on the homepage.
• No community fallback. With zero dependents and zero stars, Stack Overflow and package blogs are not a resource. Establish a debugging baseline early: enable query logging, dump the resolved page object before rendering, and keep a scratch route that echoes the resolver's intermediate state.
• Extension points to prefer: container bindings for resolvers/registries, published views you can override in resources/views/vendor/..., and event listeners for cache busting. Avoid touching internals — the split is regenerated and internal classes are free to move.
• Upgrade strategy. Pin exact versions in composer.json for this component, upgrade deliberately alongside the framework, and re-read the framework changelog (not this repo's) before bumping.