Sonata Annotation Bundle Laravel Package

Getting Started

1. Install alongside Sonata Admin (this bundle is a thin layer over it, not a replacement):

   composer require kunicmarko/sonata-annotation-bundle
   

   The package is archived and the codebase has not had PHP 8.x / Sonata Admin 4–5 compatibility work, so expect to pin a version and possibly relax transitive constraints on a modern stack. Note that releases are still trickling out (1.2.1 adds a datagrid position option), so pin an exact version rather than a range you have not tested.
2. Register the bundle in your kernel (bundles.php or AppKernel), after SonataAdminBundle.
3. Configure the directories the bundle should scan for annotated classes (typically your src/Entity or src/Model paths) in the bundle config. If the config key is not obvious, copy the block from the package's Resources/config or its test fixture.
4. Annotate one small entity:

   use KunicMarko\SonataAnnotationBundle\Annotation as Sonata;
   
   /**
    * @Sonata\Admin("Product", group="Catalog")
    */
   class Product
   {
       /**
        * @Sonata\DatagridField(position=1)
        * @Sonata\FormField
        */
       private $name;
   
       /**
        * @Sonata\DatagridField(position=2, sortable=true)
        * @Sonata\FormField(type="integer")
        */
       private $price;
   }
   

5. Clear the cache (bin/console cache:clear) so the compiler pass re-scans, then open /admin/dashboard. If the entry appears, the wiring works.

Where to look first: the README for the annotation catalogue, then src/Annotation/ for the exact attributes each annotation accepts (DatagridField, DatagridAssociationField, FormField, ShowField, Admin), and tests/ for a working annotated model plus its expected admin output. Those two directories are more reliable than the docs for edge cases, and they are the only place you will see options like position documented.

First use case: an internal back-office CRUD screen for a small entity whose list/form/show are 90% scalar fields. That is exactly what the annotations cover cheaply; anything more elaborate will push you back to a hand-written AbstractAdmin.

Implementation Patterns

• Class-level @Admin declares the admin: first argument is the label, plus options such as group for dashboard grouping, manager type, controller, and templates. One annotation per model class.
• Field-level annotations (@DatagridField, @FormField, @ShowField, and @DatagridAssociationField for to-one/to-many columns) are placed on properties or accessors. Combine them on the same property so datagrid, form, and show stay in sync; annotate accessors when the value is computed rather than stored.
• Column ordering: as of 1.2.1 both @DatagridField and @DatagridAssociationField accept a position option. Use it to pin the datagrid order instead of relying on property declaration order, keep the numbers spaced (10, 20, 30) so you can insert a column later without renumbering, and remember it only affects the datagrid — form and show order are still driven by annotation order.
• Options are passed as annotation arguments, e.g. @FormField(type="choice", options={"required"=false}), @DatagridField(label="Unit price", sortable=true, position=30). Anything the annotation does not expose must be set in a real admin class.
• Grouping by menu section via group on @Admin is the main day-to-day lever for keeping a large dashboard navigable.
• Relations: use @DatagridAssociationField for association columns, and the bundle's child/parent annotations for one-to-many nesting if your version supports it; otherwise declare the child admin separately and attach it with addChild in a normal admin class.
• Escape hatch pattern: keep the annotated model for the common case, and for entities that need custom queries, batch actions, or non-standard form types, write a conventional AbstractAdmin subclass instead of fighting the annotations. Mixing both in one codebase is normal and supported by Sonata itself.
• Override without forking: because admins are generated, find the generated service in bin/console debug:container --tag=sonata.admin, note its id, and either alias/replace it or extend its class to override configureDatagridFields() / configureFormFields().

Gotchas and Tips

• Archived and effectively unmaintained. No PHP 8.x or Sonata Admin 4/5 compatibility work has happened since 2019; the 1.2.1 position addition is a small feature patch, not evidence of active maintenance. On a modern stack, verify composer resolution before committing; on legacy Sonata 3.x/PHP 7.x it is fine.
• Upgrade check for 1.2.1: the change is add-only (a new position option on the datagrid annotations), so it is safe to bump within 1.x. Confirm you are not already setting column order via a custom configureDatagridFields() override — if you are, the annotation and the override will race and the override wins, making position look broken.
• Annotation caching: changes to annotations require a cache clear because scan results are compiled into the container. If a new field or a changed position does not appear, that is almost always the cause.
• Only annotated fields are included. There is no auto-discovery fallback, so a forgotten @DatagridField simply yields a missing column rather than an error — easy to miss in review. The same applies to position: an unpositioned field is not an error, it just lands wherever the traversal put it.
• Private properties need accessors. Doctrine can read the annotation via reflection, but Sonata still calls getters to render values; add them or annotate the getter instead.
• Complex form types are the weak spot. Collections, embedded forms, sonata_type_model_autocomplete, and custom types generally need a hand-written admin; the annotation option array is not a full substitute for configureFormFields().
• Annotation import clashes. Always alias the bundle namespace (use ... as Sonata;) so @Admin does not collide with other packages' annotations or Doctrine's own.
• Inheritance and traits may not be traversed depending on version; if fields from a mapped superclass vanish, flatten them onto the concrete class or configure them manually.
• Debugging path: debug:container --tag=sonata.admin to find the generated service, then dump the admin's getDatagridBuilder/getFormBuilder/getListBuilder in a throwaway test to see what the annotations actually produced — including the resolved column order. Faster than guessing.
• No formal extension points. Custom annotations are not pluggable; treat the bundle as a boilerplate reducer for simple entities and compose with real admin classes everywhere else.