Sulu Glossary Bundle Laravel Package

Getting Started

First, the framework reality check: despite being a Composer package, this is a Sulu 3 / Symfony bundle, not a Laravel package. There is no service provider auto-discovery, no Eloquent, no Blade, no php artisan. If your app is Laravel, this only makes sense as a separate Sulu-powered content application (or a headless Sulu instance you query over HTTP) — do not attempt to install it into a Laravel codebase.

Minimal steps in a Sulu 3 skeleton:

1. composer require the bundle, then register it in config/bundles.php and import its routing/config.
2. Run the Doctrine migration template from docs/templates/doctrine-migration.php.dist (MySQL) before doctrine:migrations:migrate on any non-fresh install.
3. Clear cache and confirm the Glossary navigation appears in the admin; grant the security contexts sulu.glossary.entries and sulu.glossary.settings to your role or you'll get empty/403 views.
4. Create one entry: title, explanation, description, image, link, plus the unlocalized type (abbreviation / acronym / term). Publish it (draft → live per locale).
5. Render it. First use case is almost always: a glossary term referenced from page/article content via the single_glossary_entry_selection content type, resolved in Twig with sulu_resolve_glossary_entry, or an overview page built with sulu_get_glossary_entries + load_glossary_settings.

Where to look first: the English/German docs in docs/, then GlossaryEntryDimensionContent to understand which fields are localized, then the provider list (smart content, teaser, link, sitemap, route defaults) depending on which surface you're integrating.

Implementation Patterns

• Content type wiring. Add glossary_entry_selection (multi-select) or single_glossary_entry_selection in your template XML. This is the primary authoring pattern — editors pick entries in the page form, you resolve UUIDs in the template.
• Resource loader. Use glossary_entry to load entries like any other Sulu resource; good for custom controllers and API-ish endpoints.
• Route defaults. Providers register routes with the key glossary_entries; your overview controller receives entries from request attributes rather than querying the repository itself. Follow that pattern so sitemap/preview/cache providers keep working.
• Overview page. Use the bundled settings (header, hero, breadcrumbs, overview page) so the glossary index is editable in admin instead of hardcoded in Twig; load_glossary_settings exposes them.
• Inline term help. sulu_get_glossary_entries for lists, sulu_resolve_glossary_entry for a single UUID. The abbr filter (sulu_glossary.twig.auto_abbr) is the "auto-abbreviation" convenience — opt-in, apply narrowly.
• Localization workflow. Dimensions are draft and live per locale. Use copy-to-locale, delete-translation, and translation-restore as the editorial pattern rather than duplicating entries. Restores and version restores create new dimension versions — treat custom listeners as potentially re-firing.
• Migrations from 2.x. Two-step: sulu:glossary:migrate-from-2x (data) then sulu:glossary:migrate-page-references (page references from SuluAbbreviationsBundle 2.0). Run against a snapshot; the reference migration assumes entities already exist.
• Scheduled publishing. If you already run sulu/automation-bundle, publish/unpublish scheduling comes for free — no extra wiring on your side.
• Caching and search. SEAL reindex providers for admin and website, HTTP cache tagging/invalidation, reference refresher, and trash handler are all registered. You get correct purge-on-publish and reindex-on-change behaviour as long as your templates go through the provided providers/loaders rather than raw Doctrine queries.
• Activity log. Domain events (created, modified, removed, restored, published, unpublished, draft_removed, copied_language, translation_removed, translation_restored, version_restored) give you a clean hook for audit trails, webhooks, or Slack notifications — subscribe to these instead of diffing entities.
• Version retention. sulu_glossary.versioning.max_versions defaults to 20. Tune per environment.

Gotchas and Tips

• Do not bring Laravel idioms. No app(), no facades, no Blade directives, no php artisan vendor:publish. Configuration lives in Symfony config YAML; DI overrides are done by decorating services or replacing parameters.
• type is unlocalized. It lives on the entry, not the dimension content. Changing it changes every locale, and it will not appear where you expect if you're iterating dimension content fields.
• Draft vs live is the #1 frontend bug. Public routes must resolve live content; preview resolves draft. If a term renders in preview but not on the site (or vice versa), you're on the wrong dimension.
• UUID v7 primary keys. Any custom SQL, import script, or external integration must handle UUIDs — no auto-increment assumptions, and joins against legacy 2.x integer IDs need the migration to have run.
• The abbr filter rewrites text. It's a string filter; running it over rich HTML can produce broken markup or wrap text inside attributes. Restrict it to plain explanation/short fields and test with nested tags and existing <abbr> elements.
• Missing security context = silent emptiness. If admin views load but lists stay blank, check role permissions for sulu.glossary.entries first.
• Smart content and teasers lag if you bypass the bundle. Entries created through the admin fire reindex and cache invalidation; data seeded directly into the DB does not. Backfill/reindex explicitly after imports.
• max_versions: 0 means unlimited. Fine for low-volume glossaries, risky for heavily edited ones; watch the dimensions table growth.
• Migration order matters on existing installs: migration template → migrate → page references. Snapshot first; the 2.x bundle name changed, so don't run both bundles' migrations simultaneously.
• Route default key is glossary_entries — a typo here yields an empty overview with no error, since the controller just receives nothing.
• Extension points are standard Sulu/Symfony: override admin templates and Twig templates via app resource paths, decorate the SEAL/route/teaser providers to add custom resolution logic, and hook domain events for integrations. Prefer decoration over editing vendor code so patch releases stay clean.
• Tooling baseline: PHP 8.2–8.4, PHPStan level 6, PHPUnit, PHP CS Fixer — mirror that in your own customizations if you plan to contribute or maintain a fork.