Shuwee Admin Bundle Laravel Package

Getting Started

This is a Symfony bundle, not a Laravel package — there is no service provider or config/shuwee-admin.php. Treat it as a component you wire into a Symfony app; reaching for it from Laravel means porting the DI/config by hand, which is rarely worth it for a 4-star, single-maintainer bundle.

Minimal path:

1. composer require wanjee/shuwee-admin-bundle (PHP 8+, Symfony 5/6-era, Doctrine ORM, Twig, SecurityBundle).
2. Register the bundle in config/bundles.php:

   Wanjee\Shuwee\AdminBundle\ShuweeAdminBundle::class => ['all' => true],
   

3. Import its routing (check Resources/config/routing.* in the vendor dir for the exact resource name) under a secured prefix:

   shuwee_admin:
       resource: '@ShuweeAdminBundle/Resources/config/routing.xml'
       prefix: /admin
   

4. Create your first admin class extending the bundle's base admin, declaring the Doctrine entity and its list/form fields, and register it as a service (or via the bundle's admin auto-discovery config — read DependencyInjection/Configuration.php first).

Look here first: README.md → the bundle's Admin/ directory (base classes + interfaces) → DependencyInjection/Configuration.php (the real config surface) → Resources/views/ (what templates you can override). The demo/test app in the repo, if present, is the fastest way to see a working admin.

First use case: expose a read/write CRUD screen for one entity (e.g. PostAdmin) behind an ROLE_ADMIN firewall, then confirm list, create, edit, and delete routes resolve via bin/console debug:router | grep admin.

Implementation Patterns

Admin-per-entity. The core unit is an admin class bound to one Doctrine entity. You implement the field configuration methods (list columns, form fields, filters) and the base class handles routing, persistence, and rendering. Keep these classes declarative — no business logic, no queries.

Service registration + tagging. Admins are collected into a pool. Register each as a service with the bundle's admin tag (check the tag name in DependencyInjection/), and use debug:container --tag=<tag> to verify registration. If auto-registration exists via a namespace convention, prefer it to avoid tag drift.

CRUD controller extension. For non-CRUD screens (dashboards, importers, reports), extend the bundle's controller rather than fighting the admin base class. Subclass and add actions; don't monkey-patch the base.

Template overrides. Override list/form/show templates per admin or globally by placing files at the documented override paths and clearing cache. This is the sanctioned extension point for branding and custom columns.

Form integration. Delegate field definitions to Symfony Form types where the admin config gets complex. It keeps validation and data transformers reusable outside the admin.

Menus and navigation. Wire the menu via the bundle's menu event/builder so entries are driven by the admin pool rather than hardcoded Twig. Add role checks in the menu listener so users only see admins they can access.

Security. Guard each admin with a role/voter check in the admin class or via a security voter. The bundle gives you the structure; authorization is your responsibility.

Integration tips: keep admins thin and push logic into domain services; centralize filter definitions; use the pool service to build cross-entity dashboards; write a functional test per admin that hits list + create + edit routes.

Gotchas and Tips

Laravel mismatch. There is no Laravel adapter. The bundle assumes Symfony's container, routing, Twig, and Doctrine. Using it from Laravel means reimplementing the bundle's wiring — a strong reason to prefer a native Laravel admin (Filament, Nova, Backpack) unless you're already on Symfony.

Staleness. Last release mid-2022, very few stars, one maintainer. Pin the exact version, check compatibility against your Symfony/PHP versions before committing, and be prepared to fork. No dependents means few real-world bug reports to lean on.

Config surface is small and literal. The extension config in DependencyInjection/Configuration.php is the source of truth — read it rather than trusting README snippets, which may lag behind.

Routing order matters. Import the admin routes after your security firewall config, and ensure the prefix doesn't collide with app routes. Use debug:router to confirm.

Template cache. Overrides and Twig changes routinely require bin/console cache:clear, and in dev cache:pool:clear cache.app. If a template override "doesn't apply," it's almost always resolution order or cache.

Doctrine metadata. Schema/metadata caching bites when you change entity mappings — clear the metadata cache explicitly. Admin list columns silently break if an entity field is renamed.

Debugging recipe: debug:router (routes), debug:container --tag=... (admin registration), Symfony profiler (form/DB), and Twig's dump() in overridden templates. If an admin doesn't appear, it's usually a missing service tag or a namespace mismatch in auto-registration.

Extension points to rely on: base admin subclassing, per-admin template overrides, the admin pool service, menu event listeners, and controller subclassing. Avoid editing vendor code — you'll need those overrides after the next (rare) release.

Upgrade risk. With no active release cadence, budget for a fork if you depend on it long-term; keep your admin classes small so a replacement is feasible.