Sulu Abbreviations Bundle Laravel Package

Getting Started

1. composer require manuxi/sulu-abbreviations-bundle and enable the bundle in config/bundles.php (Sulu bundles are usually auto-discovered, verify in the admin).
2. Check docs/ first — it ships English and German docs covering publishing, translations, versions, references, teaser, http cache, smart content, selection fields, twig, settings, and the 1.x → 2.0 upgrade. If you're coming from 1.x, read UPGRADE.md before touching code.
3. Configure config/packages/sulu_abbreviations.yaml:
   • sulu_abbreviations.versioning.max_versions (default 20, 0 disables)
   • sulu_abbreviations.twig.auto_abbr (enables the abbr Twig filter)
4. Run the Doctrine migrations for abbr_abbreviations, abbr_abbreviation_dimension_contents, abbr_abbreviation_versions. A migration template is provided at docs/templates/doctrine-migration.php.dist.
5. Ship the structure template abbreviation_default (already in src/Resources/config/templates/abbreviations/) into your webspace, and add a page template that renders @SuluAbbreviations/abbreviation.html.twig.
6. First use case: log into the admin, create an abbreviation (name, url, explanation, description, image, link), publish it for a locale, then render it on the front end via sulu_resolve_abbreviation() in your controller or the abbr filter in body copy.

Implementation Patterns

Admin content workflow Every locale has independent draft/live content. Create → edit draft → publish. The controller (Controller\Admin\AbbreviationController, attribute-routed) exposes list/get/create/update/delete/publish/unpublish/remove-draft/copy-locale. Toolbar actions in the edit dropdown: “copy to locale” (only with >1 locale), “remove draft”, “unpublish”. The delete action is a dropdown: “delete” and “delete translation”.

Rendering

• Page template is selected via the structure template abbreviation_default; the Twig template receives content (replaces the old abbreviation variable).
• sulu_resolve_abbreviation() returns a normalized live content array, not an entity, and registers the abbreviation in the abbreviations reference store (for cache tags).
• sulu_get_abbreviations() also returns arrays and marks the response as a list of abbreviations.
• {{ text|abbr }} wraps known abbreviations in <abbr title="..."> — only registered when sulu_abbreviations.twig.auto_abbr: true.

Content types and links

• Selection fields abbreviation_selection / single_abbreviation_selection now store UUID strings. They implement ReferenceContentTypeInterface, so pages appear in an abbreviation's references list.
• Link provider alias is now abbreviations: use <sulu-link provider="abbreviations" ...>. Old provider="abbreviation" links must be rewritten.

Integrations

• Teaser provider alias abbreviations (Teaser\AbbreviationTeaserProvider); falls back to the abbreviation image when no excerpt image is set.
• Smart content data provider Content\AbbreviationsDataProvider.
• Sitemap provider and search metadata / reindex provider based on the content bundle services.
• Resolver\AbbreviationResolver for programmatic lookups.

Versioning and references

• Every publish (admin or automation) records a snapshot in abbr_abbreviation_versions, keeping the newest max_versions per abbreviation + locale.
• Restore via the Versions tab (restore_version list item action) or POST /admin/api/abbreviations/{id}/versions/{version}?action=restore&locale=xx. Restoring writes into the draft, requires EDIT, fires AbbreviationVersionRestoredEvent.
• Reference\AbbreviationReferenceUpdater stores draft references in the admin context, live in website. The subscriber keeps them in sync on publish/unpublish/remove-draft. Run bin/console sulu:reference:refresh abbreviations after bulk imports.

HTTP caching EventSubscriber\AbbreviationCacheInvalidationSubscriber purges pages referencing the abbreviation (alias abbreviations), plus tag and category references and abbreviation list pages. Runs after flush, on publish/unpublish/remove/restore/translation-delete. The cache manager is optional — it silently no-ops without sulu/http-cache-bundle.

Automation Scheduled publish/unpublish requires sulu/automation-bundle (now in suggest). Install it explicitly if you want the Automation tab.

Domain events to hook AbbreviationDraftRemovedEvent, AbbreviationTranslationRemovedEvent, AbbreviationVersionRestoredEvent, AbbreviationCopiedLanguageEvent.

Gotchas and Tips

• Migration order matters. Run sulu:abbreviations:migrate-to-content --dry-run first, then for real. It creates new UUIDs (old id kept in abbr_abbreviations.legacy_id), builds draft + live content per locale, moves routes, drops routes of unpublished translations. Idempotent, legacy tables are read-only — safe to re-run.
• Then run sulu:abbreviations:migrate-page-references --dry-run. This rewrites integer ids inside abbreviation_selection / single_abbreviation_selection (including inside blocks) and <sulu-link provider="abbreviation"> links in both draft and live workspaces. Anything not covered (custom block structures, hardcoded HTML, external bookmarks) you must fix yourself.
• Every removed class will fatal. Gone: Entity\Models, Entity\Interfaces, AbbreviationTranslation, AbbreviationSeo*, AbbreviationExcerpt*, old repositories, Common\DoctrineListRepresentationFactory, Mapper\AbbreviationDataMapper, Routing\AbbreviationsRouteDefaultsProvider, Preview\AbbreviationsObjectProvider, the old task handlers. grep -r your app/ before deploying.
• The sulu_abbreviations.objects config key is gone — remove it or the container will fail to compile.
• The custom website controller is gone. Rendering is template-based only. If you had routing/controller logic, replace it with the abbreviation_default structure + @SuluAbbreviations/abbreviation.html.twig page template.
• Variable rename: Twig now gets content, not abbreviation. Any overridden template silently renders empty.
• Two renames to sweep: link provider abbreviation → abbreviations; toolbar copy → copy_locale (and it now copies into another locale, not just duplicates).
• Settings route renamed to sulu_abbreviations.get_abbreviations_settings at /admin/api/abbreviations-settings. Anything using route() on the old name breaks.
• sulu_resolve_abbreviation() / sulu_get_abbreviations() return arrays now — update type hints, remove entity accessors, and use array access instead.
• abbr filter silently missing if twig.auto_abbr is false. Enable it before debugging a “filter not found” error.
• Deleting the last locale deletes the whole abbreviation (into trash). deleteLocale=true requires EDIT on that locale; you can restore from trash.
• Don't remove Route\AbbreviationRouteRemover. Symfony 7.4 no longer registers the content bundle's Doctrine event subscriber, so this bundle-level remover is what actually cleans routes on delete.
• Versioning is opt-out via max_versions: 0 — handy on large instances to avoid table growth, but you lose the restore action entirely.
• Cache invalidation is quiet about being unavailable. Without sulu/http-cache-bundle nothing purges and stale pages will serve old abbreviations; verify the bundle is present if you rely on it.
• phpcr/phpcr-migrations-bundle and manuxi/sulu-shared-tools-bundle were removed from dependencies — if your app relied on them transitively, require them directly.
• Debugging references: inspect admin (draft) vs website (live) contexts separately in the reference store; they diverge by design and only sync on publish/unpublish/remove-draft.
• Functional test harness is provided (tests/Functional, in-memory SQLite + PHPCR, test webspace in tests/App/config) — the fastest way to reproduce admin/API behaviour without spinning up a full instance.