Admin Bundle Laravel Package

Getting Started

Install and register. Add the package with composer require zicht/admin-bundle, then register Zicht\Bundle\AdminBundle\ZichtAdminBundle in your kernel's bundle list (in Symfony 4+ this is config/bundles.php; in the legacy AppKernel it's registerBundles()). Confirm the bundle's required Symfony version before you start — Zicht bundles were largely built for Symfony 2/3, so on a modern app you will likely need Flex shims or a compatibility fork.

Where to look first.

1. README.md in the repo root — often the only real documentation, and frequently out of date.
2. Resources/config/ — routing, services, and DI parameters. This tells you what the bundle actually wires up, which is more reliable than the README.
3. DependencyInjection/Configuration.php — the canonical list of config keys, their defaults, and required values.
4. Controller/ and Resources/views/ — the admin controllers and Twig templates you'll be overriding or extending.

Import routing. Add the bundle's routing to your app:

# config/routes.yaml
zicht_admin:
    resource: "@ZichtAdminBundle/Resources/config/routing.xml"
    prefix: /admin

First use case. The realistic day-one job is standing up an admin landing area: a dashboard plus one or two list/detail screens over a doctrine entity. Start by getting the bundle's default route to render, then layer your own controller and template on top. Don't try to configure every option up front — the config surface is thin and the defaults are the intended path.

Implementation Patterns

Extend the base admin controller. The bundle's controllers are designed to be subclassed. Create your own src/Controller/Admin/FooController.php that extends the bundle's admin controller, and override only the methods you need (list, detail, form handling). This keeps you on the upgrade path while letting you shape behavior.

Template override by path. Twig resolves bundle views through the standard @ZichtAdmin/... namespace. The cheapest customization is to copy a template into templates/bundles/ZichtAdminBundle/ at the same relative path — Symfony picks it up automatically, no config needed. Prefer this over editing the vendor tree.

Menu/dashboard configuration. Where the bundle exposes menu or dashboard items, define them in config or via a compiler-pass-style service tag rather than hardcoding in templates. Keep menu definitions in one YAML file per environment so staging and production don't drift.

Service wiring for admin screens. Register each admin controller/service with an explicit tag or alias. If the bundle auto-collects admins by tag, use that — it means adding a new screen is: create controller, add tag, add route, done. Avoid manual container manipulation.

Security integration. Wire the admin prefix into your security.yaml access_control with an explicit role (e.g. ROLE_ADMIN) before you build any screens. Zicht's admin bundle doesn't impose an auth model, so this is your responsibility and it's easy to forget until you notice /admin is public.

Asset and form theming. If the bundle ships form themes or JS, register them in config/packages/twig.yaml under form_themes and include assets via your normal Webpack/Encore pipeline rather than the bundle's static paths — that way the admin UI matches the rest of the app and stays cache-busted.

Gotchas and Tips

Version compatibility is the first blocker. This is a Symfony-era package with essentially no adoption (zero dependents, no stars signal). Verify composer.json's require block against your Symfony version before committing. On Symfony 5+ expect deprecation noise or outright breakage around container aliases, Controller base classes, and templating.

Thin docs, so read the source. With low community usage, there are no blog posts, no Stack Overflow answers, and no issue history to lean on. When something misbehaves, the fastest path is vendor/zicht/admin-bundle/ — services YAML first, then the controller. Treat the README as a hint, not a spec.

Config keys may not do what the name implies. Verify each option in Configuration.php and trace where it's consumed. Zicht bundles sometimes accept a config value but only read it in one narrow code path (usually routing or a menu builder), so setting it and assuming broad effect is a common trap.

Route prefix collisions. Importing the bundle's routing with a fixed /admin prefix can clash with your own admin routes. Either nest the bundle under /admin/zicht or scope your routes so ordering in routes.yaml is deterministic — Symfony matches first-wins, and a catch-all {slug} in the bundle will shadow your routes.

Debugging DI failures. If the container won't compile, run bin/console debug:container --tag=<tag> and debug:config zicht_admin (config key may differ — check Configuration::getConfigTreeBuilder for the root name). Compiler-pass errors from this bundle typically surface as "service not found" for a class you never referenced — that's an auto-collected admin with a missing dependency.

Extension points to reach for. Base controller subclassing and Twig path overrides are the supported seams. If you need to change list queries or form building, override the controller method rather than patching vendor code — that keeps composer update survivable. For anything deeper (custom menu providers, permission checks), look for service tags in Resources/config/services.xml; tags are the intended extension mechanism and are more stable than class internals.

Plan an exit. Given the adoption level, encapsulate your usage behind your own admin controllers and templates from day one. If you eventually swap to EasyAdmin or Sonata, you want the migration to be "rewrite the controllers," not "unpick the bundle from everywhere." Budget for this as a risk, not a hypothetical.