Stimulus Bundle Laravel Package

Technical Evaluation

Architecture Fit

• Symfony-Native Integration: StimulusBundle is architecturally aligned with Symfony’s ecosystem, leveraging Twig, AssetMapper, and Symfony UX components. It avoids reinventing Stimulus integration (e.g., manual Webpack configs, Twig extensions) while maintaining compatibility with Symfony’s conventions.
• Progressive Enhancement: Supports gradual adoption—teams can replace jQuery plugins or vanilla JS with Stimulus controllers incrementally, without rewriting templates or backend logic.
• Symfony UX Compatibility: Seamlessly integrates with Turbo (SPA-like navigation), Mercure (real-time updates), and Dropzone (file uploads), enabling modern frontend patterns without vendor lock-in.
• Twig-Driven Workflow: Provides declarative Twig functions (stimulus_controller, stimulus_action, stimulus_target) to embed Stimulus behavior directly in templates, reducing boilerplate and improving maintainability.
• Service Layer Abstraction: The helper service for generating Stimulus data attributes from PHP services enables tight backend-frontend coupling without custom JavaScript, ideal for dynamic UIs (e.g., real-time dashboards).

Technical Risk

Key Questions for TPM

1. Symfony Ecosystem Alignment:

   • Are we already using Symfony UX (Turbo, Mercure, Dropzone)? If so, StimulusBundle will integrate natively.
   • Do we rely on Webpack Encore or AssetMapper? StimulusBundle requires AssetMapper (v6.4+) for v3.0.0.

2. Migration Strategy:

   • Which StimulusBundle version to adopt? (v3.0.0 for Symfony 7.4+; v2.x for legacy support).
   • Should we phase adoption (e.g., start with modals/tooltips before complex UX)?

3. Team Readiness:

   • Does the team have Twig/Symfony templating expertise? StimulusBundle tightens coupling to Twig.
   • Is there Stimulus.js experience? If not, budget for a 1–2 day training session.

4. Performance Impact:

   • Will Stimulus controllers replace heavy jQuery plugins? Measure bundle size and runtime performance.
   • Does the asset pipeline support ES Modules (required for StimulusBundle v2.13.0+)?

5. Long-Term Viability:

   • Are we committed to Symfony’s frontend roadmap (e.g., Turbo, Mercure)? StimulusBundle is tightly coupled to it.
   • Do we need hybrid architectures (e.g., Stimulus + React)? StimulusBundle may not support this natively.

6. Alternatives:

   • Should we consider standalone Stimulus (no Symfony integration) or Alpine.js for simpler use cases?
   • Is Symfony Webpack Encore or Vite already in use? StimulusBundle works best with AssetMapper.

Integration Approach

Stack Fit

• Symfony Core: Requires Symfony 6.4+ (v2.x) or 7.4+ (v3.0.0). Ideal for teams already using Symfony’s modern stack (e.g., Flex, UX components).
• Asset Pipeline:
  • AssetMapper (Recommended): StimulusBundle v3.0.0+ requires AssetMapper ≥6.4. Configure excluded_patterns to avoid conflicts with existing assets.
  • Webpack Encore: Supported but may require manual tweaks (e.g., ES Modules support for Stimulus controllers).
• Frontend Tools:
  • Twig: Mandatory for stimulus_* functions. Templates must be refactored to use declarative Stimulus attributes.
  • TypeScript/JavaScript: Stimulus controllers can be written in either. TypeScript support requires build tool configuration.
  • Symfony UX: Native integration with Turbo, Mercure, and Dropzone. Enables advanced patterns like real-time updates or SPA-like navigation.
• Database/Backend: No direct dependencies, but StimulusBundle’s helper service can generate data attributes from PHP services (e.g., for dynamic UI states).

Migration Path

1. Preparation Phase:

   • Audit Symfony version (upgrade to 6.4+ or 7.4+ if needed).
   • Inventory existing JS dependencies (jQuery, vanilla JS) to identify candidates for Stimulus replacement.
   • Review asset pipeline (AssetMapper/Webpack Encore) for compatibility.

2. Core Integration:

   • Install StimulusBundle:

     composer require symfony/stimulus-bundle
     

   • Configure AssetMapper (if using v3.0.0):

     # config/packages/asset_mapper.yaml
     framework:
         asset_mapper:
             excluded_patterns:
                 - '*/controllers.json'  # Updated in v2.33+
     

   • Enable the bundle in config/bundles.php:

     return [
         // ...
         Symfony\UX\StimulusBundle\StimulusBundle::class => ['all' => true],
     ];
     

3. Template Migration:

   • Replace inline JS (e.g., onclick) with Twig functions:

     {# Before: #}
     <button onclick="showModal()">Open</button>
     
     {# After: #}
     <button {{ stimulus_controller('modal') }} data-action="click->modal#show">Open</button>
     

   • Use stimulus_action for dynamic parameters:

     {{ stimulus_action('modal#show', { id: 'user-123' }) }}
     

4. Controller Development:

   • Create Stimulus controllers in assets/controllers/ (or a custom path):

     // assets/controllers/modal_controller.js
     import { Controller } from '@hotwired/stimulus';
     
     export default class extends Controller {
       show() {
         this.element.showModal();
       }
     }
     

   • For TypeScript, ensure build tools (e.g., Webpack Encore) are configured.

5. Advanced Integration (Optional):

   • Symfony UX Turbo: Add Turbo links for SPA-like navigation.
   • Mercure: Use Stimulus controllers to handle real-time updates from Mercure hubs.
   • PHP Service Integration: Use the helper service to generate data attributes dynamically:

     {{ stimulus_data({ user: app.service('user').getCurrentUser() }) }}
     

6. Testing & Optimization:

   • Test Stimulus controllers in isolation (e.g., using @stimulus/test).
   • Profile asset pipeline performance (AssetMapper adds ~500ms to builds).
   • Audit templates for deprecated Twig functions (e.g., ux_controller_link_tags in v3.0.0).

Compatibility