Admin Bundle Laravel Package

Getting Started

This is a v0.1.0 pre-1.0 release — treat the API as unstable and pin the exact version in composer.json. The value proposition is zero-config CRUD admin panels generated from entity metadata, so budget time to read the source rather than expecting mature docs.

1. Require the package and confirm your persistence layer. The release notes describe Doctrine ORM coupling and #[Admin] attributes on Doctrine entities, plus LiveComponents (Symfony UX). Before anything else, verify how (or whether) it installs into your Laravel app. If you're Eloquent-only, this package will not drop in; you'll need a Doctrine bridge or a separate admin service. Decide this first — it's the gating question.
2. Read src/Attribute/Admin.php (or equivalent) first. It is the single entry point for configuration: entity label, list columns, form fields, filters, sort defaults, pagination size. Everything else is convention layered on top.
3. Register one entity. Add #[Admin] to a small, low-risk model (a lookup table such as Category or Tag), point the panel at it, and confirm the list view renders before touching forms.
4. Validate the round trip: list → filter → sort → paginate → create → edit → delete. The release notes call core CRUD the tested path; confirm it against your entity before scaling to tables with relations.

First realistic use case: an internal back-office for a handful of entities where you want a working CRUD screen in an afternoon, and you're willing to own the Doctrine integration and some rough edges. Not a fit for a customer-facing admin you must ship next week on Laravel with Eloquent.

Implementation Patterns

Attribute-first configuration. Keep admin config on the entity, not in a separate admin class, and keep it declarative — display label, list fields, form fields, default sort. Derive as much as possible from column metadata so new fields appear without edits. When you need behaviour the attribute doesn't express, override the template rather than forking the component.

Template override as the customization seam. The package exposes a template override system; use it for layout, column rendering, and action buttons. Mirror the package's directory structure exactly, override the smallest file that solves the problem, and record which templates you've shadowed in your repo — you'll need to diff them against package templates on every upgrade.

LiveComponent lifecycle discipline. CRUD screens are stateful. Treat filter/sort/page state as owned by the component, and make it URL-addressable (query string) so links to a filtered list survive a refresh — hugely useful for support and debugging. Keep entity mutation inside the component's action methods, not in templates; LiveComponent re-renders are frequent and side effects in templates bite.

Convention over configuration for filters and sorting. Expose filters only for indexed columns, and set sensible defaults (createdAt DESC, page size 25–50). Add filters incrementally per entity based on the questions people actually ask, not the full column list.

Integration tips.

• Wrap the panel behind your existing auth middleware and an authorization policy per entity. Zero-config CRUD means zero-config access if you don't add it.
• Seed a dev database and snapshot the list views; after each upgrade, a visual diff of the list pages catches most breakage faster than the test suite will at 48% coverage.
• Keep an upgrade log of attribute signatures you rely on. Pre-1.0 releases will change them; a one-line grep across entities tells you the blast radius.

Gotchas and Tips

• Doctrine coupling is the headline risk. The package is built against Doctrine entities and LiveComponents. Laravel's idiomatic stack is Eloquent and Blade/Livewire. Eloquent models will not carry #[Admin] in a way that just works. Confirm installability in your app before promising a delivery date; if decoupling is on the roadmap, do not architect around the current coupling expecting a painless future migration.
• #[Admin] attributes are reflection-driven and cached. After editing attributes, clear framework and attribute caches before concluding the change didn't work. "My column won't disappear" is almost always a cache.
• 48% coverage means edge cases are yours. Critical paths are tested; relations-heavy entities, soft deletes, composite keys, nullable/JSON columns, and unusual pagination are not guaranteed. Add your own feature tests around the entity shapes you actually have, especially anything with a foreign key.
• Template overrides break silently. A renamed template falls back to the package default without an error. If a customization seems to vanish after upgrading, check the override path and filename first, not your CSS.
• Docs cover basics only. Advanced scenarios — nested relations, custom actions, permission scoping — need source reading. Budget for reading the component and attribute classes; it's a small codebase and cheaper than guessing.
• Extension points, in order of safety: template override → attribute options → decorating the service/component → forking. Prefer the leftmost that works. Forking a pre-1.0 package guarantees a painful upgrade.
• Performance on large tables. Sorting and filtering are the obvious first bottlenecks; verify generated queries against an indexed table with realistic row counts before rolling out. Add indexes for every column you expose as a filter.
• Debugging strategy. Because it's metaprogrammed from metadata, log the resolved admin config (fields, filters, sort) for the entity at boot in dev. When a screen renders wrong, that dump usually explains it faster than stepping through the component.