Sonata Auto Configure Bundle Laravel Package

Getting Started

1. Install with Composer and let Flex register it (or add it manually to config/bundles.php):

   composer require nucleos/sonata-auto-configure-bundle
   

   Check the installed version: 1.4.0 added Symfony 8 support, so the bundle is current with the latest Symfony line — but confirm the PHP/Symfony constraint intersection with your own sonata-project/admin-bundle version before upgrading, since the release is a compatibility bump and not an API change.

2. Make sure your app has a normal Sonata Admin setup (sonata-project/admin-bundle, a sonata_admin.yaml, and a sonata_admin firewall), because this bundle only replaces the service tagging/configuration layer — not Sonata itself.

3. Point the bundle at your admin directory in config/packages/sonata_auto_configure.yaml:

   sonata_auto_configure:
       admin:
           directory: '%kernel.project_dir%/src/Admin'
           namespace: 'App\Admin'
   

   Confirm the exact keys with bin/console config:dump-reference sonata_auto_configure — the package is small and its config surface is the first thing to verify in the installed version.

4. Create a first admin class and decorate it with the bundle’s attribute (historically an annotation, so watch the import):

   namespace App\Admin;
   
   use Nucleos\SonataAutoConfigureBundle\Attribute\Admin;
   use Sonata\AdminBundle\Admin\AbstractAdmin;
   
   #[Admin(
       label: 'Posts',
       group: 'Content',
       managerType: 'orm',
       adminCode: 'app.admin.post',
   )]
   final class PostAdmin extends AbstractAdmin
   {
   }
   

5. Verify the result rather than trusting the scan:

   bin/console cache:clear
   bin/console debug:container --tag=sonata.admin
   

   You should see app.admin.post listed with the expected tag attributes and no manual services.yaml entry. That is the first real use case: stop hand-writing sonata.admin tags for every CRUD admin.

Implementation Patterns

Attribute-per-admin as the source of truth. Keep each admin’s metadata (label, group, managerType, adminCode, icon, roles, translation domain) on the class itself. This keeps the admin definition, its base class, and its group/label together and makes new admins a single-file operation.

Convention-based service discovery. Treat src/Admin as the canonical admin namespace and rely on autoconfigure/autowiring in services.yaml:

App\Admin\:
    resource: '../src/Admin/'
    autoconfigure: true
    autowire: true

The bundle then only needs to add the sonata.admin tag; constructor dependencies for admins continue to be autowired normally.

Multiple manager types in one project. If you use both ORM and ODM (or several entity managers), set managerType explicitly per admin rather than relying on a global default. This is where the bundle saves the most boilerplate in mixed projects.

Coexistence with hand-written tags. Leave existing explicit sonata.admin tags alone for admins that need unusual tag options (custom pcode, non-standard manager, legacy codes). Do not tag the same class both manually and via the bundle — see Gotchas.

Dashboard groups by attribute. Let group on the attribute be the only place you name a Sonata group, and keep the dashboard/group configuration in sonata_admin.yaml as the display policy. If a group appears empty, the mismatch is almost always between the attribute string and the YAML group name.

Child admins stay manual. Auto-configuration tags services; it does not infer parent/child relationships. Use addChild() in a service or admin method as you would normally, then confirm both services have sonata.admin tags.

Verification workflow for every new admin. After adding or renaming an admin:

bin/console cache:clear
bin/console debug:container --tag=sonata.admin | grep -i app.admin
bin/console sonata:admin:list

This catches admin-code collisions, wrong manager types, and missing tags before a browser test.

Testing pattern. Use a KernelTestCase and assert the container contains the service and that it is tagged:

self::assertTrue($container->has('app.admin.post'));
self::assertArrayHasKey('sonata.admin', $container->getDefinition('app.admin.post')->getTags());

For functional coverage, hit the Sonata dashboard and an admin list route; a badly configured tag usually fails at dashboard group rendering rather than at container compile time.

Prefer the bundle’s compiler pass as the extension point. If you need derived metadata (for example, a label based on a class constant), wrap it in your own compiler pass that runs after the bundle’s pass rather than duplicating scanning logic. Inspect the bundle’s DependencyInjection directory in vendor/ to see the pass priority and attribute class name for the installed version.

Gotchas and Tips

• Compile-time, not runtime. Tagging happens in a compiler pass, so attribute changes require a cache rebuild in production. In dev, if behavior looks stale, clear cache before debugging.
• Duplicate sonata.admin tags. If _instanceof or an explicit tag already applies to your admin base class, the bundle can add a second tag. Sonata may then treat the service oddly or log duplicate-admin warnings. Remove the manual tag before enabling auto-configuration for that class.
• Admin code uniqueness. Two admins with the same adminCode cause confusing dashboard overrides rather than a clean error. Use fully qualified codes (app.admin.post) and verify with sonata:admin:list.
• Manager type mismatches. Setting managerType: orm for an ODM-mapped class (or vice versa) fails deep inside Sonata’s model manager setup. The tag is correct but the admin cannot resolve its class. Check the tag’s manager_type first when an admin page 500s.
• Service visibility and instantiation. Sonata resolves admins from the container; if auto-configured admins are private/lazy in your setup, routing or dashboard rendering can fail to retrieve them. Keep the bundle’s defaults, and only override visibility if you know Sonata’s service locator expectations for your version.
• Scan scope. Never include tests/, var/, or generated directories in the scan path. Accidental matches create services for abstract or test admin classes and produce compile-time errors.
• Group/label translation. Attribute labels are not automatically translated unless you also set the translation domain (or rely on Sonata’s default domain). If labels appear as raw keys, the domain is configured in the wrong place.
• Group names must match exactly. Empty dashboard groups are usually a typo between the attribute group and sonata_admin.yaml. Case and whitespace matter.
• Version and framework matrix. 1.4.0 is a compatibility release: it adds Symfony 8 support and changes nothing in the attribute or config surface, so it is a safe upgrade if your Sonata bundle supports Symfony 8 too. Treat the attribute API and config keys as still unstable across minor releases — pin the version, read the changelog on upgrade, and keep the bundle’s DependencyInjection and Attribute directories bookmarked. The source is the documentation.
• Debugging order. For any “admin missing” problem: (1) debug:container --tag=sonata.admin, (2) check the service is not excluded by resource/exclude, (3) check compiler pass ordering with debug:container --deprecations or a deliberately failing pass, (4) only then inspect Sonata config.
• Extension point. If the bundle exposes an interface or event for post-configuration, prefer that over subclassing the compiler pass; compiler passes are internal and the class name can change between releases.