Sulu Site Configuration Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Sulu CMS Alignment: The bundle is tightly coupled with Sulu CMS (v3.0+) and leverages its webspace, locale, and media handling systems. This makes it a natural fit for projects already using Sulu, but misaligned for standalone Laravel/PHP applications without Sulu.
• Flexible JSON Storage: The use of Doctrine ORM for JSON-based configuration storage aligns with Laravel’s Eloquent but introduces schema rigidity (migrations required). Laravel’s dynamic config() system may offer more flexibility for non-Sulu projects.
• Twig/PHP Integration: The bundle provides Twig helpers (site_config()) and PHP services, which mirror Laravel’s Blade/Service Container patterns but require Sulu’s dependency injection (Symfony-based).

Integration Feasibility

• Sulu Dependency: The bundle hardcodes Sulu dependencies (e.g., sulu/sulu, symfony/uid), making it non-portable to vanilla Laravel. A wrapper layer would be needed to abstract Sulu-specific services (e.g., WebspaceResolver, MediaService).
• Doctrine ORM: Laravel’s Eloquent is not directly compatible with this bundle’s Doctrine-based migrations. A custom migration adapter or Eloquent model would be required to replicate functionality.
• Form System: The XML-based form configuration (config/forms/webspace_configs/*.xml) is Sulu-specific. Laravel’s Form Requests or Spatie Laravel Forms would need to be adapted or replaced.

Technical Risk

• High Coupling Risk: The bundle’s reliance on Sulu’s admin UI, routing, and services introduces tight integration risks. Customizing or extending it without Sulu would require significant refactoring.
• Migration Complexity: Doctrine migrations for JSON entities may conflict with Laravel’s existing migrations, requiring manual resolution or a hybrid migration strategy.
• Locale/Webspace Handling: Sulu’s multi-webspace/multi-locale architecture is non-trivial to replicate in Laravel. The bundle’s SiteConfigurationService would need adaptation to work with Laravel’s config() or a custom multi-tenant/locale store.
• Media Handling: The single_media_selection field type depends on Sulu’s media system. Replacing this with Laravel’s filesystem or Vapor/AWS would require custom field types.

Key Questions

1. Is Sulu CMS a Hard Requirement?
   • If yes, proceed with minimal adaptation (focus on form/config alignment).
   • If no, evaluate rewriting core services (e.g., SiteConfigurationService) to work with Laravel’s ecosystem.
2. What’s the Data Model Strategy?
   • Should configurations be stored as JSON in a Laravel model (e.g., SiteConfig) or Doctrine entities (requiring Symfony’s ORM)?
3. How Will Locales/Webspaces Be Managed?
   • Laravel lacks built-in multi-webspace support. Will you use tenancy packages (e.g., Stancl/Tenancy) or custom middleware?
4. What’s the UI Approach?
   • Will configurations be managed via Laravel Nova, Filament, or a custom admin panel? The bundle’s Sulu admin UI would need replacement.
5. Media Handling Alternative
   • How will single_media_selection fields be replaced? Options:
     • Laravel’s Vapor/S3.
     • A custom media library (e.g., Spatie Media Library).
6. Performance Implications
   • JSON storage in Doctrine may bloat queries. Will Laravel’s cached config or database indexing be sufficient?

Integration Approach

Stack Fit

• Sulu CMS Projects: Direct integration with minimal changes (focus on form/config alignment).
  • Pros: Leverages Sulu’s admin, media, and webspace systems natively.
  • Cons: Limited to Sulu’s feature set.
• Laravel Projects: Partial integration with significant abstraction.
  • Core Components to Replace:
    • Sulu’s Doctrine ORM → Laravel Eloquent.
    • Sulu’s admin UI → Laravel Nova/Filament.
    • Sulu’s media system → Spatie Media Library or custom solution.
    • Sulu’s routing → Laravel’s Route::prefix() or middleware.
  • Pros: Flexibility to adapt to Laravel’s ecosystem.
  • Cons: High refactoring effort; potential for feature gaps.

Migration Path

1. Assess Dependency Overlap
   • Audit existing Laravel stack for conflicts with symfony/uid, doctrine/orm, etc.
   • Mitigation: Use Symfony’s Console component for migrations if Doctrine is unavoidable.
2. Database Schema Adaptation
   • Option 1: Drop Doctrine, create a Laravel model (e.g., SiteConfig) with JSON column.

     Schema::create('site_configs', function (Blueprint $table) {
         $table->id();
         $table->string('webspace_key');
         $table->string('locale');
         $table->json('config');
         $table->timestamps();
     });
     

   • Option 2: Keep Doctrine, configure Laravel to use Symfony’s ORM via symfony/orm-pack.
3. Service Layer Abstraction
   • Create a facade for SiteConfigurationService:

     class LaravelSiteConfigService {
         public function get(string $webspace, string $locale, string $key, $default = null) {
             return SiteConfig::where('webspace_key', $webspace)
                 ->where('locale', $locale)
                 ->value('config->'.$key) ?? $default;
         }
     }
     

4. Form System Replacement
   • Replace XML forms with Laravel Form Requests or Filament Forms.
   • Example:

     namespace App\Forms;
     use Filament\Forms\Components\TextInput;
     use Filament\Forms\Form;
     
     class SiteConfigForm extends Form {
         public function form() {
             return [
                 TextInput::make('website_email')
                     ->label('Email')
                     ->required(),
             ];
         }
     }
     

5. Twig Integration
   • Replace site_config() helper with a custom Twig extension:

     // app/Providers/AppServiceProvider.php
     public function register() {
         Twig::getInstance()->addFunction(new \Twig\TwigFunction(
             'site_config',
             [$this->app->make(LaravelSiteConfigService::class), 'get']
         ));
     }
     

Compatibility

Sequencing

1. Phase 1: Proof of Concept
   • Set up the bundle in a Sulu sandbox to validate core functionality.
   • Test SiteConfigurationService and Twig integration.
2. Phase 2: Laravel Adaptation
   • Replace Doctrine with Eloquent.
   • Abstract SiteConfigurationService into a Laravel-compatible layer.
3. Phase 3: UI Migration
   • Replace Sulu admin forms with Filament/Nova.
   • Adapt media uploads to Spatie Media Library.
4. Phase 4: Testing
   • Validate locale/webspace isolation.
   • Test performance (JSON queries vs. cached configs).
5. Phase 5: Deployment
   • Migrate existing Sulu configs to Laravel’s schema.
   • Roll out incrementally (e.g., per-webspace).

Operational Impact

Maintenance

• Sulu Projects:
  • Low effort: Follows Sulu’s update cycles (e.g., Doctrine/Symfony versions).
  • High coupling: Updates to Sulu may break the bundle.
• Laravel Projects:
  • High effort: Custom abstractions require ongoing sync with Sulu changes.
  • Dependency bloat: Symfony/Doctrine components may complicate Laravel’s stack.
• Form Management:
  • XML forms are hard to maintain. Migrating to Filament/Nova **reduces technical debt