Laravel Panneau Laravel Package

Product Decisions This Supports

• Build vs. buy for admin tooling: Still informs whether to adopt a Laravel-native dashboard, build a custom admin layer, or standardize on a mature ecosystem (Filament, Nova, Backpack, Orchid). The v5 line is a protocol-based admin framework, not a small dashboard package — a different comparison set and commitment level. alpha.4 adds a genuinely useful capability (global search) without changing that framing.
• Architecture direction — still the central decision: v5 is the reference implementation of the Panneau protocol, with a separate @panneau/* JavaScript client, a versioned OpenAPI definition, and contract tests run against a conformance kit. alpha.4 pins to panneau-js v5.x / 5.0.0-alpha.5 and reports every conformance check passing, including the new global search and fields.check endpoints. The real decision remains "adopt a protocol-defined admin layer with a decoupled JS frontend" versus both admin frameworks and headless/API-first admin approaches.
• Incremental adoption is now a real option (new): Panneau::uploadRoutes() and Panneau::resourceRoutes($resources, only: [...]) let a project with its own admin front mount only the slices it uses, without the app page. This converts the build-vs-buy question from "replace our admin" to "adopt the protocol for a subset of screens" — a lower-risk pilot shape and a cheaper spike.
• Platform/runtime standards: PHP 8.3+ and Laravel 12/13 remain hard requirements. Laravel ≤11 or PHP 8.1/8.2 forces a framework/PHP upgrade as a roadmap-level prerequisite. laravel/scout is now suggested, not required — no new mandatory dependency for search.
• Internal tooling roadmap: Supports prioritization of back-office CRUD, ops dashboards, and support consoles. Global search (GET {panneau.path}/api/search) now covers "find the record" workflows, scoped to resources the user can list and run through repositories or Scout. Still explicitly absent: auth flows (password reset, 2FA, passkeys, OAuth), the roles module, the broader media API, export/import with queued runs, and pages/menus.
• Multi-tenant back offices (new): Controllers now read route parameters by name, so routes under a prefix with its own parameter (tenants/{tenant}/...) work. This unblocks multi-tenant admin surfaces — but note it is route-parameter plumbing, not a tenancy/isolation feature. Confirm scoping enforcement is your own.
• Time-to-value vs. platform risk: Value continues to accrue: contract-tested resource/action layer plus search, slug validation, and media replacement. The release cadence (alpha.1 → alpha.4) is additive with documented, concrete upgrade steps (upgrade @panneau/* in lockstep; drop createOnly() on the mediatheque file field; set panneau.search.enabled to false to omit the search route). That is a better churn signal than "unknown," but it is still pre-release with a stated possibility of API change and no v4 migration guide.
• Vendor/package risk register: Low star count and zero dependents remain valid caution flags for a framework-level commitment. They are further offset by engineering evidence: OpenAPI-defined protocol, per-response contract tests, CI running the conformance kit against a pinned JS release, opt-in routes, and four alphas of steady additive work. Keep the distinction between "immature adoption" (still true) and "unstructured or unmaintained" (not supported by the evidence).
• Migration/upgrade budget: A rewrite with a breaking API and no v4 migration guide remains a distinct line item. Alpha-to-alpha upgrades are becoming cheap and documented; v4-to-v5 is still a re-implementation and cannot start until the guide ships.
• Feature gap analysis: The comparison baseline should now include protocol conformance, ETag/If-Match optimistic concurrency (412), application/problem+json errors, required policies, filter/sort declaration enforcement via ResourceQuery, authorization-aware global search, server-side slug uniqueness checks with a live form endpoint (POST resources/{resource}/fields/{field}/check), and original-file replacement on the mediatheque with 422 on rejection. Remaining gap versus mature admin packages: auth, roles, full media API, import/export, and menus/pages.
• Operational surface area (new): Search is behind a panneau-search rate limiter and on by default; slug checks add a per-keystroke endpoint on slug fields. Both are cheap but need capacity/rate-limit decisions and a "disable if unused" call (panneau.search.enabled). The mediatheque replacement path requires folklore/laravel-mediatheque 2.0.0-alpha.5+ — another alpha dependency to track.

When to Consider This Package

Consider it when:

• The application is on Laravel 12 or 13 and PHP 8.3+ (or an upgrade is already planned).
• The team wants a Laravel-native admin backend with a decoupled JS client, and values a versioned protocol contract over a batteries-included monolith.
• The requirement is an internal, non-critical back office — CRUD over resources, declared filters/sorts, row- and query-based bulk actions, and now cross-resource global search.
• Operators need to find records fast: global search over listable resources, repository-backed or Scout-backed, respects what the user may list. Good fit for support consoles and ops triage.
• Optimistic concurrency and typed API errors matter: ETag/If-Match with 412 conflicts and application/problem+json responses reduce edit-collision support cost in multi-operator back offices.
• Engineering wants strict, auditable resource definitions — repositories instead of models, serialization limited to declared fields, validation that only lets validated data reach the repository, and required policies — for teams with data-exposure or compliance concerns.
• Your admin lives under a parameterized route prefix (tenants/{tenant}/...) or you only need part of the API mounted (uploadRoutes(), resourceRoutes(..., only: [...])) alongside an existing frontend.
• You need content-editor-friendly slugs: live availability checks in the form, per-locale uniqueness, parent-scoped uniqueness, and read-only/disabled cases like a home page.
• You can absorb alpha instability: an API that may still change before 5.0.0, plus auth, roles, full media API, import/export, and menus to come in Phase 2 betas.
• Engineering is comfortable patching or forking, and a time-boxed spike is appropriate before any long-term commitment.

Look elsewhere when:

• You need a stable, documented admin surface now, or your roadmap depends on auth flows, roles, import/export, or menu/page management — none of these are in this alpha.
• You need a full media/media-library API rather than original-file replacement on the mediatheque; the broader media work is still Phase 2.
• You are on Laravel ≤11 or PHP <8.3 and a framework upgrade is not on the table.
• You have an existing v4 deployment and need a supported upgrade path — the migration guide is not yet published, so the honest answer today is still "wait."
• You need advanced search (faceting, relevance tuning, custom ranking) beyond q/limit/resources plus Scout.
• You need a mature plugin ecosystem, community support, long-term maintenance guarantees, or enterprise SLAs.
• The admin surface requires deep customization or workflows beyond what the resource/field/layout/action builders express.
• The dashboard is core to the product or revenue path rather than internal tooling.
• The team is not Laravel-native, or prefers a single integrated stack over maintaining a Laravel API plus a @panneau/* JS client.
• Adoption signals still matter: low visible adoption and few or no dependents remain valid caution flags for a framework-level commitment. Re-check them at 5.0.0 GA, not at this alpha.

How to Pitch It (Stakeholders)

For executives: This is a ground-up rewrite of a Laravel admin package, now in its fourth alpha. It is the reference implementation of a versioned, spec-defined admin protocol with automated contract and conformance testing, and it keeps shipping capability — this release adds permission-aware global search, live slug validation, media file replacement, and the ability to mount only part of the API. Those last two matter commercially: partial mounting lets us pilot it on a slice of admin surface instead of a wholesale replacement. The caveats are unchanged and material: pre-release with a potentially changing API, requires PHP 8.3+ and Laravel 12/13, and authentication, roles, the full media API, import/export, and menus are not yet built. Recommend a time-boxed pilot on one non-critical internal dashboard, using partial route mounting, with a decision gate at 5.0.0 GA and a mature alternative benchmarked in parallel. Do not make it an organization-wide standard on an alpha.

For engineering: alpha.4 keeps the v5 architecture (repository-backed ResourceRepository/EloquentRepository, ResourceQuery-constrained filters and orders, builders generating the protocol definition, mandatory policies, validated-data-only writes, ETag/If-Match 412, application/problem+json) and adds: GET {panneau.path}/api/search with q/limit/resources, scoped to listable resources via repositories or Scout, behind the panneau-search limiter and disableable via panneau.search.enabled; Slug::unique() (per locale, optionally parent-scoped) with POST resources/{resource}/fields/{field}/check for live form validation and a ChecksSlugs contract for non-Eloquent repositories; Mediatheque::replaceOriginal() with 422 on rejected or wrong-type files and replace() for libraries that allow type changes (requires laravel-mediatheque 2.0.0-alpha.5+); Panneau::uploadRoutes() / resourceRoutes(..., only: [...]) for partial mounting; and named route-parameter reads so prefix parameters like tenants/{tenant} work. Protocol conformance passes against panneau-js 5.0.0-alpha.5, including the new search and fields.check endpoints. Trade-offs: API can still change before 5.0.0; no v4 migration guide; auth, roles, and import/export are Phase 2; alpha-to-alpha upgrades require syncing @panneau/* and the mediatheque pin, and the search route is on by default. You now own a Laravel backend plus a @panneau/* JS frontend. Spike it on one real internal screen, read docs/ and the roadmap, and treat missing auth and roles as the gating work items.

Recommendation: Treat v5 as a new package, not an upgrade. Pilot on one non-critical internal dashboard for a fixed window — partial route mounting makes this cheaper than in alpha.1 — and define exit criteria: API churn across the remaining alphas/betas (alpha.4's documented, additive upgrade path is an encouraging data point, not yet a guarantee), Phase 2 auth and roles availability, and a published v4 migration guide. Benchmark against a mature alternative before standardizing. Any team currently on v4 should stay put until the migration guide ships.