Sulu Content Extra Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Sulu CMS 3.x Native Extension: The bundle leverages Sulu’s mapped-superclass entities (via PrependExtensionInterface) to extend core Page/Article classes without breaking existing associations. This aligns with Sulu’s dimensioned-content model (e.g., PageDimensionContent), ensuring compatibility with localization, preview, and admin workflows.
• JSON Field Flexibility: Provides a generic JSON storage layer for additional data, avoiding the need for custom Doctrine entities or schema migrations. Ideal for structured metadata (e.g., SEO tags, campaign IDs, API payloads) without over-engineering.
• Navigation Enhancements: Integrates with Sulu’s link-type pages via NavigationLinkEnhancer, adding sourceLink/sourceUuid markers to template data. This enables dynamic routing logic (e.g., conditional UI based on linked content) without modifying core Sulu templates.
• Form System Integration: Uses Sulu’s XML-based form definitions, allowing teams to define custom fields (select, text, etc.) without PHP code. The PreviewFormViewBuilder auto-registers the "Additional Data" tab, reducing frontend integration effort.

Integration Feasibility

• Zero-Config for Basic Use: Auto-registers entities and tabs for Pages/Articles with no project-specific entities required. Only requires:
  1. Composer install (alengo/sulu-content-extra-bundle).
  2. Bundle registration in bundles.php.
  3. Custom form XML files (e.g., page_additional_data.xml).
• Config-Driven Localization: YAML configuration (alengo_content_extra.yaml) maps fields to unlocalized (shared across languages) or localized (per-dimension) storage, aligning with Sulu’s multilingual architecture.
• Template Compatibility: NavigationLinkTypeResolver exposes sourceLink/sourceUuid to templates via the navlink section, bypassing Sulu’s TemplateResolver to avoid key filtering. Works with Twig/Symfony templates out of the box.
• Doctrine Compatibility: Requires Sulu 3.0.6+ for mapped-superclass fixes, but avoids custom Doctrine configurations. The bundle’s resolve_target_entities replaces Sulu’s original class references at container build time, enabling auto_generate_proxy_classes: false in production.

Technical Risk

Key Questions for Stakeholders

1. Content Strategy:
   • Which fields (e.g., template_theme, campaign_id, seo_overrides) should be stored in the "Additional Data" tab? Are any localized or shared across languages?
   • Will this replace existing custom entities, or supplement them for specific use cases (e.g., marketing metadata)?
2. Technical Debt:
   • Is the team comfortable with XML-based form definitions (vs. PHP/YAML)? If not, custom form builders may be needed.
   • Should we validate JSON fields at the form level (e.g., required fields, data types) or defer validation to business logic?
3. Navigation Use Cases:
   • How will sourceLink/sourceUuid markers be used in templates? Examples:
     • Conditional UI logic (e.g., "Show a banner if this page links to a product").
     • Analytics tracking (e.g., log redirects in Google Analytics).
4. Performance:
   • Is the team willing to disable proxy generation in production (auto_generate_proxy_classes: false) for the performance benefits?
   • Should we benchmark JSON storage impact on high-traffic Pages/Articles?
5. Future-Proofing:
   • Are there plans to extend this to custom content types (e.g., Media, Block)? The bundle’s architecture supports this via configuration.
   • Should we abstract the form definitions into a shared library if reused across projects?

Integration Approach

Stack Fit

• Sulu CMS 3.x: Native support for Pages, Articles, and dimensioned content. The bundle extends Sulu’s core entities without forks.
• Symfony 7.x: Compatible with Symfony’s dependency injection and Doctrine ORM (PHP 8.2+ features like enums are unused but supported).
• Doctrine ORM: Uses mapped-superclass entities and JSON columns (additionalData), requiring no custom migrations.
• Twig/Symfony Templates: NavigationLinkTypeResolver exposes markers to templates via the navlink section, ensuring compatibility with Sulu’s templating system.
• Form System: Leverages Sulu’s XML form definitions, allowing teams to define fields (select, text, etc.) without PHP code.

Migration Path

1. Prerequisites:
   • Upgrade to Sulu 3.0.6+ (if not already on it) for Doctrine/Gedmo compatibility.
   • Ensure Symfony 7.x and PHP 8.2+ are in use.
2. Installation:

   composer require alengo/sulu-content-extra-bundle
   

   Register the bundle in config/bundles.php:

   Alengo\SuluContentExtraBundle\AlengoContentExtraBundle::class => ['all' => true],
   

3. Configuration:
   • Define field mapping in config/packages/alengo_content_extra.yaml:

     alengo_content_extra:
         page:
             unlocalized_keys: [template_theme]
             localized_keys: [notes]
         article:
             enabled: true
     

   • Create custom form XML files (e.g., config/forms/page_additional_data.xml):

     <form xmlns="...">
         <key>page_additional_data</key>
         <properties>
             <property name="template_theme" type="select" mandatory="false">
                 <meta><title lang="en">Theme</title></meta>
                 <params><param name="values" type="collection"><param name="default" type="collection"><param name="title" value="Default"/><param name="name" value="default"/></param></param></params>
             </property>
         </properties>
     </form>
     

4. Production Optimization:
   • Disable proxy generation in config/packages/prod/doctrine.yaml:

     when@prod:
         doctrine:
             orm:
                 auto_generate_proxy_classes: false
     

   • Run php bin/console cache:warmup to generate proxies during deploy.

Compatibility

• Backward Compatibility: The bundle extends (not replaces) Sulu’s core entities. Existing Page/Article data remains intact.
• Template Compatibility: NavigationLinkTypeResolver ensures sourceLink/sourceUuid are available in templates without modifying Sulu’s TemplateResolver.
• Form Compatibility: Uses Sulu’s standard form XML schema, so existing form tools (e.g., Sulu’s admin UI) work unchanged.
• Doctrine Compatibility: No custom migrations or entity listeners are required. The bundle’s resolve_target_entities handles class replacements at container build time.

Sequencing

1. Phase 1: Core Integration (1–2 sprints):
   • Install the bundle and configure alengo_content_extra.yaml.
   • Define basic forms (e.g., page_additional_data.xml with 2–3 fields).
   • Test the "Additional Data" tab in the Sulu admin panel.
2. Phase 2: Localization Validation (1 sprint):
   • Verify that unlocalized (shared) and localized fields sync correctly across languages.
   • Test preview and publish workflows.
3. Phase 3: Navigation Enhancements (1 sprint):
   • Implement sourceLink/sourceUuid usage in templates (e.g., conditional logic for link-type pages).
   • Validate with real-world examples (e.g., redirect tracking).
4. Phase 4: Performance Tuning (0.5 sprint):
   • Disable proxy generation in production and test deployments.
   • Monitor JSON storage impact on entity hydration.
5. Phase 5: Expansion (Optional