Classification Bundle Laravel Package

Getting Started

This is a Symfony 2-era bundle that sits on top of sonata-project/classification-bundle; it does not replace it. Budget time for dependency archaeology before writing any feature code.

Minimal setup:

1. Confirm the project actually needs it. The repo is archived with no stars or dependents, so it will only exist in an existing legacy codebase. If you're starting fresh, use sonata-project/classification-bundle directly — the RZ layer adds nothing you can't replicate in a few lines.
2. Pin via VCS, not Packagist. composer require rz/classification-bundle is unreliable for archived Symfony 2 bundles. Add a repositories entry pointing at the GitHub URL and require an explicit tag or commit, then commit composer.lock. Never use dev-master here.
3. Register bundle order matters. In app/AppKernel.php, register SonataCoreBundle, SonataAdminBundle, SonataDoctrineORMAdminBundle, SonataClassificationBundle, then this bundle. Wrong order surfaces as missing sonata.admin.* services rather than a clear error.
4. Configure Sonata classification first. A sonata_classification block with at least one contexts entry is required before tags/categories will attach to anything. Without a context, the admin screens load but entity associations silently produce nothing usable.
5. Generate schema and inspect it. Run doctrine:schema:update --dump-sql and read the output before executing. This bundle may ship mappings that collide with Sonata's own tables, so verify the diff is additive.

Where to look first:

• DependencyInjection/ — the configuration tree tells you what's actually configurable (usually entity class overrides and admin service wiring).
• Entity/ — compare against Sonata's Tag, Category, Collection, and Context to see what was extended or duplicated.
• Admin/ — the day-to-day surface area; this is where the bundle's real opinion lives.
• Resources/config/ — service definitions and any Doctrine mapping overrides.

First use case: wire the bundle in a dev environment, confirm the Sonata admin dashboard shows the classification admin group, create one context, one category, and one tag through the UI, then verify the rows via doctrine:query:sql before touching any application code.

Implementation Patterns

Treat it as a thin layer over Sonata. The bundle's value is whatever admin customisation or entity extension it adds. Read the Admin/ classes and decide whether you're using them as-is or overriding them. Don't mix both approaches in the same project.

Override entities via configuration, not by editing the vendor bundle. SonataClassificationBundle exposes entity classes through sonata_classification.class config keys (tag, category, collection, context, and their managers). If you need extra fields, subclass the Sonata entity in your own bundle and point the config at it. Any edit made directly inside vendor/rz/ is lost on the next composer install.

Use the managers, not the repositories. TagManager, CategoryManager, and CollectionManager handle context resolution and slug generation. Injecting EntityManager directly and calling persist() means you reimplement slug and context logic, and you will get it subtly wrong — usually by omitting the context, which makes tags invisible to the front end.

For tag assignment, follow the Sonata pattern. Tags attach through a many-to-many with a join table; the join is context-scoped. When rendering tag inputs in your own forms, use sonata_type_model with the tag entity's class and a query builder filtered to the active context, rather than adding a plain EntityType.

Admin customisation workflow:

• Subclass the bundle's admin class, override configureFormFields() / configureDatagridFilters().
• Re-register the service with the same sonata.admin tag and manager_type: orm.
• Set calls for setTranslationDomain and addChild for nested categories if you want the tree view.
• Clear the cache after touching admin classes — Sonata compiles admin metadata.

Categories are a nested-set tree. For breadcrumbs or menu generation, use CategoryManager::getRootCategories() and then walk children. getTree() on the repository is expensive; cache the result in your own service layer for the request lifecycle.

Integrate with your own entities by adding a tags many-to-many association and an admin extension (Sonata\AdminBundle\Admin\AbstractAdminExtension) that appends a tag field to every relevant admin form. That's the cleanest way to make classification feel native across a large admin panel rather than touching each admin class individually.

Templates: the bundle may ship Twig overrides under Resources/views/. Check app/config/config.yml's twig.paths — Symfony 2 bundles register templates via the bundle name. To customise, create the same path inside app/Resources/RzClassificationBundle/views/ so it takes precedence without a fork.

Testing: if there are no tests, write a smoke test that boots the kernel, fetches the tag admin service, and asserts getNewInstance() returns the expected class. That single test catches the majority of breakages when you upgrade a transitive dependency.

Gotchas and Tips

Archived means frozen dependencies. Symfony 2 and the Sonata 2.x/3.x line are end-of-life. Assume no security patches for the bundle or its ecosystem, and isolate this application accordingly. If you're porting to Symfony 4/5, this bundle is a rewrite candidate, not an upgrade candidate — plan on dropping it and using sonata-project/classification-bundle directly with a thin local bundle for your customisations.

Entity mapping conflicts are the most common failure. If the bundle ships its own mapping for a table Sonata already maps, doctrine:schema:validate will complain or the schema tool will try to drop columns. Resolution: exclude one mapping explicitly via the bundle's config, or disable auto-mapping (doctrine.orm.auto_mapping: false) and register mappings per bundle.

Silent empty admin lists. Sonata's admin list views return zero rows without error when the underlying manager's query builder is misconfigured or when the datagrid's _sort field doesn't exist on the extended entity. Debug by calling the repository method directly from a console command — if it works there, the problem is datagrid config, not data.

Cache poisoning after config changes. Symfony 2's app/cache needs a full rm -rf (not just cache:clear) after changing entity classes or admin service definitions. Half-cleared caches produce fatal "cannot find class" errors that look like the bundle is genuinely broken.

Context is the number-one source of "tags don't show up". Tags, categories, and collections are all context-scoped. A tag created in the default context will not appear when your front end queries with a different context. Make the context explicit in every repository call and add it to your seed fixtures.

Entity class override ordering. If you override sonata_classification.class.tag in config.yml, that must happen in the sonata_classification block, not a custom rz_classification block — the RZ bundle delegates to Sonata's config. Verify with debug:container --parameter=sonata.classification.admin.tag.entity.

Admin assets. Symfony 2 Sonata admin requires sonata_admin asset installation via assets:install --symlink or a published web/bundles/ directory. Missing JS shows a blank dashboard with no console error pointing at the bundle.

Debugging entry points:

• debug:container | grep sonata.classification to see what's actually registered.
• debug:config sonata_classification (Symfony 3+) or inspect the resolved configuration in the profiler.
• Set sonata.admin.logging to debug level temporarily to see admin service resolution failures.

Extension points worth knowing: the admin extension mechanism (AbstractAdminExtension) and the entity class override parameters are the two supported customisation surfaces. Everything else is effectively a fork and should be vendored into your own bundle with a written justification, because there is no upstream to send patches to.

Migration strategy: treat this bundle as quarantined code. Wrap every call to it behind your own service or repository so that replacing it with plain Sonata (or with a simple own entity) later is a bounded refactor rather than a grep across the codebase.