Sulu Abbreviations Bundle Laravel Package

Product Decisions This Supports

• Platform modernization / ecosystem alignment: This release moves the abbreviation management onto Sulu's content-bundle and content workflow. If the roadmap already tracks Sulu upgrades (or a move to Sulu 2.x-era admin/content APIs), this package is now aligned rather than a legacy outlier — a data point for standardizing content features on the content bundle.
• Editorial workflow investment (draft/live, publish, unpublish, remove draft per locale): Supports a product bet that content governance — staged drafts, scheduled publishing, locale-specific publishing — is a platform capability, not a per-feature build. Abbreviations stop being a special case and inherit the same workflow as pages.
• Localization / translation roadmap: Per-locale draft and live content, “copy to locale,” and “delete translation” (without deleting the whole entity) directly enable multilingual glossaries/abbreviation lists. Useful evidence when prioritizing i18n work or scoping a language rollout.
• Audit, versioning, and recovery as a product requirement: Version snapshots on every publish (configurable retention, default 20), restore-into-draft, insights/activity log, and domain events give editorial safety and traceability. This supports decisions about “undo/restore” UX and compliance-ish audit expectations without custom builds.
• Build vs. buy (internal build vs. adopt the package): The release adds the surrounding "platform plumbing" teams usually underestimate: teaser provider, link provider, sitemap provider, smart content data provider, search metadata/reindex, reference tracking, HTTP cache invalidation, and admin UI actions. That shifts the build-vs-buy call toward adopting/upgrading rather than maintaining a fork.
• Performance/SEO decisions: HTTP cache invalidation keyed to abbreviation references, response tagging, sitemap and link providers, and search reindexing support decisions about caching strategy and public-site SEO behavior.
• Content API/rendering strategy: Templated website rendering (abbreviation_default structure template + Twig), normalized live content arrays, resolver and Twig helpers (sulu_get_abbreviations(), optional abbr filter) enable a headless-ish/API-first or template-first choice; the selection content type being a ReferenceContentTypeInterface means pages show up in an abbreviation’s references list.
• Migration/upgrade cost estimation: The breaking changes and two migration commands (migrate-to-content, migrate-page-references, both idempotent, with --dry-run) give a concrete upgrade workstream to schedule and size, rather than an open-ended rewrite.

When to Consider This Package

Consider adoption when:

• You run Sulu CMS and need first-class abbreviation/glossary entities with editorial workflow, per-locale draft/live content, and front-end rendering.
• You want abbreviation content to behave like other Sulu content: publish/unpublish/remove draft, scheduled publishing (with sulu/automation-bundle), version history with restore, and references to media/contacts/categories/tags.
• You need multilingual abbreviation management, including copying content between locales and deleting a single translation without losing the entity.
• You need integration with the rest of the content stack: link provider (abbreviations), teaser provider, sitemap, smart content, search indexing, and HTTP cache invalidation for pages containing abbreviations.
• You are on 1.x and want the maintained path forward — 2.0 provides migration tooling and an upgrade guide, so upgrading is realistic rather than a rewrite.
• You’re willing to build/maintain a small amount of custom template work: website rendering is now template-based (@SuluAbbreviations/abbreviation.html.twig), not a bundle-provided controller.

Look elsewhere / defer when:

• You are not on Sulu (the package is deeply tied to Sulu content bundle, PHPCR/Doctrine, admin UI, and Sulu routing/security). This is not a Laravel/Laravel-package-shaped dependency.
• You cannot absorb a breaking upgrade: 2.0 changes storage model (content bundle entities instead of translation entities), changes abbreviation IDs from integers to UUIDs, removes entities/namespaces/services/configuration (sulu_abbreviations.objects, AbbreviationDataMapper, custom controllers, task handlers), and changes link provider alias from abbreviation to abbreviations.
• You rely on removed/relocated dependencies or behaviors: manuxi/sulu-shared-tools-bundle and phpcr/phpcr-migrations-bundle are removed, sulu/automation-bundle is only a suggest, and the old copy toolbar action is replaced by copy_locale.
• You need abbreviation data to remain integer-keyed for downstream systems without doing the reference migration; page content, text editor links, and bookmarks referencing old integer ids must be migrated.
• You are not prepared to run data migrations and rewrite references: migrate-to-content (creates new UUIDs, keeps legacy_id, migrates draft/live content, routes) and migrate-page-references (rewrites abbreviation_selection / single_abbreviation_selection and <sulu-link provider="abbreviation"> in draft and live workspaces).
• You require the bundle to own front-end routing/controllers as before — that responsibility has moved to templates and route/content-bundle services.

How to Pitch It (Stakeholders)

For executives: This is a major, strategic upgrade of the abbreviation capability, not a cosmetic release. It brings abbreviation content under the same editorial workflow as the rest of the CMS — draft/live, publishing, scheduling, per-locale translation, version history with restore, and audit/insights — and it plugs into teasers, links, sitemaps, search, and HTTP caching. That reduces bespoke code and makes multilingual abbreviation/glossary content a supported platform feature. The cost is a one-time, planned migration: IDs change to UUIDs, storage moves to the Sulu content bundle, and references in pages and links must be rewritten. The release ships idempotent migration commands with dry-run support precisely to de-risk that. Net: higher editorial safety and less custom maintenance, at the price of a scheduled upgrade project.

For engineering leads: Treat 2.0 as a platform alignment release with real breaking changes. Plan for: (1) the content-bundle/Doctrine/PHPCR schema change and data migration (sulu:abbreviations:migrate-to-content, --dry-run first), (2) the integer→UUID identifier change and reference rewrite (sulu:abbreviations:migrate-page-references, covering block properties and link properties in draft and live), (3) removing dependencies on deleted entities/namespaces/configuration and updating the link provider alias to abbreviations, and (4) replacing any reliance on the old website controller with the abbreviation_default structure template and @SuluAbbreviations/abbreviation.html.twig. The upside is substantial out-of-the-box plumbing — content workflow, version recorder, reference store/subscriber/refresher, teaser/link/sitemap/smart-content providers, HTTP cache invalidation, and functional tests — which is exactly the code we would otherwise own. Confirm optional integrations explicitly: sulu/automation-bundle is only suggested, and cache invalidation degrades gracefully without sulu/http-cache-bundle. Budget for test coverage against the new normalized live-content return shapes and the changed Twig variables (content replaces abbreviation).