Sulu Abbreviations Bundle Laravel Package

Technical Evaluation

Architecture fit

Despite being a PHP package, sulu/abbreviations-bundle is a Sulu CMS bundle built on Symfony, not a Laravel package. It depends on sulu/content-bundle ^0.8.3, Doctrine ORM with XML mappings, Symfony routing via #[Route] attributes, Symfony event subscribers, PHPCR (for routes/workspaces), and Twig. There is no service provider, no Eloquent, no Laravel HTTP kernel integration. Architecture fit against a Laravel application is therefore poor to non-existent unless the target system is a Sulu/Symfony application.

For a Sulu-based stack, the fit is strong: 2.0.0 aligns the bundle with Sulu's modern content architecture (draft/live dimension contents), which is the correct long-term direction and removes the legacy translation-entity model.

Integration feasibility

• Greenfield Sulu installs: high feasibility. Single bundle, attribute routes, services.yaml, shipped structure template abbreviation_default, and functional tests with an in-memory SQLite + PHPCR kernel suggest a clean install path.
• Existing 1.x installs: feasible but non-trivial. Requires schema additions (abbr_abbreviations, abbr_abbreviation_dimension_contents, abbr_abbreviation_versions), an integer→UUID identity migration, and rewriting of page content, text-editor <sulu-link> references, bookmarks, and selection content types. Two dedicated migration commands exist (sulu:abbreviations:migrate-to-content, sulu:abbreviations:migrate-page-references), both idempotent and dry-run capable — a meaningful de-risking factor.
• Laravel applications: not feasible as a drop-in. Any reuse would be conceptual (the abbr Twig filter logic, the data model) rather than functional.

Technical risk

• Framework lock-in (high): hard dependency on Sulu content bundle ^0.8.3, which is itself pre-1.0 and may break. Version pinning is essential.
• Data migration risk (high): UUID re-keying touches routes, page content, blocks, link properties, and bookmarks. The page-reference migrator covers workspace draft and live, but any custom storage of the old integer IDs (exports, third-party integrations, search indexes, analytics) is out of scope and must be handled separately.
• Removed extension points (high for anyone who customized): Entity\Models, Entity\Interfaces, Mapper\AbbreviationDataMapper, Routing\AbbreviationsRouteDefaultsProvider, Preview\AbbreviationsObjectProvider, own task handlers, own website controller, and sulu_abbreviations.objects config are all gone. Any downstream code subclassing or referencing these must be rewritten.
• Symfony 7.4 behavioral change (medium): the route remover had to be reimplemented because Symfony 7.4 no longer registers the content bundle's Doctrine event subscriber. Suggests framework-version sensitivity; test on the exact Symfony minor we intend to run.
• Rendering change (medium): website output moves from a controller to a template (@SuluAbbreviations/abbreviation.html.twig) with content replacing abbreviation as the variable. Any theme overrides must be updated.
• Link provider alias rename (medium): abbreviation → abbreviations, propagating into stored link markup — silent breakage risk if migration is partially run.
• Optional-dependency surface (low-medium): sulu/automation-bundle is now suggest; automation tab and scheduled publish silently disappear if absent. Cache invalidation degrades gracefully without sulu/http-cache-bundle, which is good, but means cache correctness depends on that bundle being present and configured.

Key questions

1. Is the consuming application actually Sulu/Symfony, or Laravel? If Laravel, this evaluation should end here.
2. Do we have custom code touching any removed namespace, mapper, route defaults provider, preview object provider, task handler, or controller?
3. Does anything outside the CMS persist legacy integer abbreviation IDs (search index, analytics, exports, PIM/ERP feeds, mobile API)?
4. Is sulu/automation-bundle required for our editorial workflow, and is it installed and supported?
5. Is sulu/http-cache-bundle in use, and is the abbreviations reference alias resolvable by our cache manager?
6. What is the rollback story if migrate-to-content or migrate-page-references produces bad data — is there a tested database restore, given the migrators are one-way and legacy tables are read-only?
7. Do we rely on more than 20 versions per abbreviation/locale, or need versioning disabled entirely (max_versions: 0)?

Integration Approach

Stack fit

Only viable on Sulu CMS with Symfony routing/DI and Doctrine ORM + PHPCR, plus Twig for front-end rendering. Confirm PHP and Symfony versions against the bundle and sulu/content-bundle ^0.8.3 constraints before committing. Treat this as not applicable to a Laravel codebase.

Migration path

1. Freeze content authoring; take a full database + PHPCR workspace backup.
2. Install 2.0.0, run Doctrine schema migration (use the shipped docs/templates/doctrine-migration.php.dist as the template).
3. Run sulu:abbreviations:migrate-to-content --dry-run, validate counts and spot-check draft/live content per locale, then run live. legacy_id on abbr_abbreviations is the reconciliation key.
4. Update theme templates to @SuluAbbreviations/abbreviation.html.twig and the content variable; update any custom link rendering to provider alias abbreviations.
5. Run sulu:abbreviations:migrate-page-references --dry-run, validate rewritten selection properties (including inside blocks) and <sulu-link> markup, then run live.
6. Rebuild search index and run bin/console sulu:reference:refresh abbreviations.
7. Purge HTTP cache; verify cache invalidation fires on publish/unpublish/remove-draft/translation-delete.

Compatibility

Re-verify every integration point that 2.0.0 changed: selection content types now return normalized live content arrays (not entities), sulu_resolve_abbreviation() and sulu_get_abbreviations() return arrays, the copy toolbar action is now copy_locale, and the settings route is /admin/api/abbreviations-settings. Any custom admin JS or API consumer coded against entity payloads will break.

Sequencing

Backup → schema → content migration → template/link updates → page-reference migration → reindex/refresh → cache purge → smoke test → authoring re-enabled. Do this in a staging environment with a production data copy first; the page-reference rewrite is the highest-regression step and should be validated by editorial QA on real pages, not fixtures.

Operational Impact

Maintenance

Ongoing maintenance is moderate: the bundle tracks Sulu's content bundle, which is pre-1.0 and therefore a recurring upgrade cost. Budget for a version-pin review each Sulu upgrade. The 2.0.0 line is a large net simplification (deletes entities, mappers, controllers, task handlers), which should reduce long-term custom-code surface — but only after our own customizations are removed. Versioning adds a growing table (abbr_abbreviation_versions) requiring a retention policy; default is 20 per abbreviation per locale, 0 disables.

Support

Documentation is a clear strength for 2.0.0: English and German docs in docs/, UPGRADE.md, and rewritten READMEs covering publishing, translations, versions, references, teaser, HTTP cache, smart content, selection types, Twig, settings, and the 1.x→2.0 upgrade. Functional tests exist with an in-memory SQLite kernel and PHPCR, plus a test webspace. Support risk shifts from the vendor to us: any custom code we wrote against removed extension points is now unsupported and undocumented.

Scaling

Content-side scaling is fine — Doctrine-backed tables, standard Sulu patterns. Two watch items: (1) versioning table growth under frequent automated publishing; (2) cache invalidation fan-out — publishing an abbreviation purges every cached page containing it, plus tag/category pages and abbreviation list pages. A widely used abbreviation becomes a broad purge event. Mitigate with max_versions tuning and monitoring of cache-purge latency/volume around bulk publishes.

Failure modes

• Partial migration → mixed integer/UUID references; link provider alias mismatch yields broken links and empty selection fields.
• Missing sulu/automation-bundle → scheduled publish silently unavailable; editors lose workflow with no error.
• Missing/misconfigured sulu/http-cache-bundle → stale pages after publish, no failure signal.
• Route removal regression (the Symfony 7.4 subscriber issue) → orphaned routes to deleted abbreviations.
• Custom code referencing removed namespaces → hard fatal errors at boot, caught only by a full smoke test.
• Migration without a validated backup → no automated rollback; recovery is restore-only.

Ramp-up

Developer ramp-up is high for anyone without Sulu experience: Symfony DI, Doctrine XML mappings, PHPCR workspaces, and the content-bundle draft/live dimension model are all prerequisites. Estimate 1–2 weeks for a Symfony-fluent developer new to Sulu to be productive, plus dedicated time on the migration tooling. Editorial ramp-up is low — the admin UX improves (versions tab, insights/activity log, delete-translation dropdown, copy-to-locale) — but requires a short training session on draft/live publish semantics and translation deletion, since deleting the last locale now deletes the whole abbreviation into the trash.