Stimulus Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle:

   composer require symfony/stimulus-bundle
   

   Ensure your config/bundles.php includes:

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

2. Enable AssetMapper (if not already configured):

   composer require symfony/asset-mapper-bundle
   

   Update config/packages/asset_mapper.yaml to include Stimulus controllers:

   framework:
       asset_mapper:
           excluded_patterns: ['*/controllers.json']
   

3. First Stimulus Controller: Create a controller in assets/controllers/ (e.g., hello_controller.js):

   import { Controller } from '@hotwired/stimulus';
   
   export default class extends Controller {
       connect() {
           this.element.textContent = 'Hello, Stimulus!';
       }
   }
   

4. Use in Twig:

   <div {{ stimulus_controller('hello') }}></div>
   

   This renders as:

   <div data-controller="hello"></div>
   

First Use Case: Dynamic Form Validation

1. Create a controller (assets/controllers/validation_controller.js):

   export default class extends Controller {
       static targets = ['field'];
       validate() {
           const value = this.fieldTarget.value;
           if (!value) {
               this.fieldTarget.setCustomValidity('This field is required');
           } else {
               this.fieldTarget.setCustomValidity('');
           }
       }
   }
   

2. Use in a form (templates/form.html.twig):

   <input
       type="text"
       {{ stimulus_controller('validation') }}
       {{ stimulus_target('validation.field') }}
       {{ stimulus_action('validation#validate', { trigger: 'blur' }) }}
   >
   

Implementation Patterns

Core Workflows

1. Twig Integration

• Controllers: Declare Stimulus controllers in Twig:

  {{ stimulus_controller('modal', { id: 'user-modal' }) }}
  

  Renders: <div data-controller="modal" data-modal-id-value="user-modal">.

• Actions: Trigger actions with parameters:

  {{ stimulus_action('modal#open', { userId: 42 }) }}
  

  Renders: <button data-action="modal#open" data-modal-open-user-id-value="42">.

• Targets: Reference DOM elements:

  {{ stimulus_target('modal.backdrop') }}
  

  Renders: <div data-modal-target="backdrop">.

• Combined Example:

  <div {{ stimulus_controller('modal', { id: 'user-modal' }) }}>
      <button {{ stimulus_action('modal#open', { userId: 42 }) }}>
          Open Modal
      </button>
      <div {{ stimulus_target('modal.backdrop') }}></div>
  </div>
  

2. Service Integration

Use the StimulusHelper service to generate data attributes dynamically:

// src/Controller/ExampleController.php
public function show(StimulusHelper $stimulusHelper): Response
{
    $data = $stimulusHelper->controller('modal', ['id' => 'user-modal']);
    return $this->render('modal.html.twig', ['stimulus_data' => $data]);
}

In Twig:

<div {{ stimulus_data(stimulus_data) }}></div>

3. Asset Pipeline

• AssetMapper: Ensure assets/controllers/ is scanned:

  # config/packages/asset_mapper.yaml
  framework:
      asset_mapper:
          packages:
              stimulus:
                  globs: ['assets/controllers/**/*.{js,ts}']
  

• Webpack Encore: If using Encore, configure entry points:

  // webpack.config.js
  Encore
      .addEntry('stimulus', './assets/controllers/index.js')
      .splitEntry('stimulus');
  

4. TypeScript Support

• Enable TypeScript controllers (v2.14.0+):

  // assets/controllers/hello_controller.ts
  import { Controller } from '@hotwired/stimulus';
  
  export default class extends Controller {
      connect() { /* ... */ }
  }
  

• Ensure package.json includes:

  {
      "type": "module",
      "scripts": {
          "build": "tsc && npm run build:js"
      }
  }
  

5. Symfony UX Integration

• Turbo: Use Stimulus with Turbo for SPA-like navigation:

  {{ stimulus_controller('turbo-modal') }}
  <turbo-frame id="modal-frame">
      {{ stimulus_target('turbo-modal.content') }}
  </turbo-frame>
  

• Mercure: Combine Stimulus with real-time updates:

  // assets/controllers/updates_controller.js
  export default class extends Controller {
      connect() {
          this.subscription = this.element.Mercure.subscribe('/updates', (event) => {
              this.element.textContent = event.data;
          });
      }
  }
  

Best Practices

1. Controller Organization:

   • Group controllers by feature (e.g., assets/controllers/forms/, assets/controllers/modals/).
   • Use a barrel file (assets/controllers/index.js) to export all controllers:

     export { default as HelloController } from './hello_controller';
     export { default as ValidationController } from './validation_controller';
     

2. Twig Template Structure:

   • Avoid mixing Stimulus and raw JavaScript in the same template.
   • Use partials for reusable Stimulus components:

     {% include 'components/modal.html.twig' with {
         'controller': 'modal',
         'id': 'user-modal'
     } %}
     

3. Debugging:

   • Use data-controller and data-action attributes in browser dev tools to inspect Stimulus events.
   • Log actions in controllers:

     log(event) {
         console.log('Action triggered:', event.detail);
     }
     

4. Testing:

   • Test Stimulus controllers with PHPUnit and Symfony’s DomCrawler:

     public function testModalController(): void
     {
         $crawler = $this->client->request('GET', '/modal');
         $controller = $crawler->filterXPath('//div[@data-controller="modal"]')->data('controller');
         $this->assertEquals('modal', $controller);
     }
     

Gotchas and Tips

Pitfalls

1. AssetMapper Exclusions:

   • Issue: Stimulus controllers may not load if excluded_patterns in asset_mapper.yaml is misconfigured.
   • Fix: Ensure excluded_patterns does not include */controllers.json (v2.33+):

     framework:
         asset_mapper:
             excluded_patterns: ['*/node_modules/**', '*/var/**']
     

2. Case Sensitivity in Parameters:

   • Issue: Parameters passed to stimulus_action are normalized to camelCase (v2.13.0 BC break).

     {{ stimulus_action('example#action', { bigCrocodile: 'value' }) }}
     

     Old: event.params.bigcrocodile (incorrect). New: event.params.bigCrocodile (correct).
   • Fix: Update controllers to expect camelCase:

     action(event) {
         console.log(event.detail.bigCrocodile); // Correct
     }
     

3. Windows Path Issues:

   • Issue: Stimulus controllers in subdirectories may fail to load on Windows due to path resolution.
   • Fix: Use forward slashes in imports or configure Node.js to handle paths consistently.

4. TypeScript Module System:

   • Issue: type: "module" in package.json may cause issues with older Node.js versions or misconfigured bundlers.
   • Fix: Revert to type: "commonjs" if needed (v2.13.2 reverted this change).

5. Stimulus Outlets:

   • Issue: Outlets (v2.10.0+) require double dashes in namespaced targets:

     {{ stimulus_target('modal--backdrop') }} <!-- Correct -->
     {{ stimulus_target('modal.backdrop') }}   <!-- Incorrect -->
     

6. Symfony UX Package Discovery:

   • Issue: StimulusBundle may fail to find UX packages if the project structure is non-standard.
   • Fix: Ensure assets/ is the root directory for UX packages or configure custom paths in config/packages/stimulus.yaml:

     stimulus:
         packages:
             - '@symfony/ux-stimulus'
             - './assets/packages'
     

Debugging Tips

1. Check Stimulus Data Attributes:
   • Inspect