Stimulus Bundle Laravel Package

Technical Evaluation

Release verdict (v3.6.0): Patch-level release. No new features, no deprecations, no API changes. The one material change is a declared conflict with symfony/asset-mapper 8.2+ (bug #3919). The remaining items are dev-tooling bumps and documentation clarifications. This does not require an architecture rethink, but it does affect upgrade sequencing — the bundle now caps how far the asset pipeline can be upgraded.

Architecture Fit

• Symfony-native, not Laravel-native. StimulusBundle is a Symfony UX package: it wires Twig, AssetMapper, and @hotwired/stimulus. There is no Laravel service provider, no Laravel package discovery, and no Blade integration. For a Laravel-first estate the package is not directly consumable; the transferable asset is the pattern (data-attribute-driven controllers + progressive enhancement), which Laravel teams already get from Livewire/Alpine + Vite.
• Where it fits: any Symfony 6.4+/7.x service in the estate, or a mixed Symfony/Laravel org where Symfony apps own customer-facing, Twig-rendered surfaces.
• Progressive enhancement: unchanged — the strongest argument for adoption. Controllers attach per-element, so jQuery/vanilla JS can be retired page by page without touching backend logic. This is the lowest-risk frontend modernization path available in the Symfony ecosystem.
• Twig-coupled by design: stimulus_controller / stimulus_action / stimulus_target move behavior into templates. High leverage for Twig-heavy apps; zero leverage for API+SPA frontends.
• AssetMapper is a hard dependency of the value proposition. The new conflict sharpens this: the bundle's usable envelope is now bounded by AssetMapper's version, not just Symfony's.

Integration Feasibility

• Install is trivial (composer require symfony/stimulus-bundle + one bundle registration). The real work is template refactoring and asset-pipeline alignment.
• Two viable pipelines: AssetMapper (recommended, and what the Twig helpers assume) or Webpack Encore with ES-module output. Both are supported; Encore requires manual config.
• Upgrade friction introduced by v3.6.0: teams currently on symfony/asset-mapper 8.2+ cannot install/upgrade to this release without downgrading AssetMapper or holding at the prior bundle version. That is a blocking constraint, not a warning — Composer will refuse the solve.
• Feasibility for a Laravel shop: low as a direct dependency; moderate as a reference architecture for a parallel Symfony app.

Technical Risk

Key Questions for TPM

1. Is this even our stack? Are we evaluating for a Symfony app, or trying to fit this into Laravel? If Laravel-only, close the evaluation and standardize on Livewire/Alpine + Vite.
2. Where are we on AssetMapper? If any service is on 8.2+, v3.6.0 is not installable — decide: pin AssetMapper, or hold the bundle at 3.5.x.
3. What is our asset-mapper upgrade cadence? This release makes the bundle a gating dependency for pipeline upgrades. Do we accept that coupling?
4. Do we already use Symfony UX (Turbo, Mercure, Dropzone)? If yes, the bundle is close to free; if no, we're buying into a roadmap.
5. Team readiness: Twig fluency and Stimulus familiarity. Missing either doubles the ramp-up estimate.
6. Exit cost: how many templates would carry stimulus_* calls after migration? That number is the switching cost.
7. Alternatives: standalone Stimulus, Alpine.js for simple cases, or staying on Encore + vanilla JS.

Integration Approach

Stack Fit

• Symfony 6.4+/7.x with Twig and AssetMapper: native fit, recommended path.
• Symfony + Webpack Encore: works, requires ES-module output config; the Twig helpers still apply.
• Symfony API-only / headless: poor fit — no templates to enhance.
• Laravel: no fit as a dependency. Reuse the pattern only.
• Backend coupling: no DB or domain dependencies; the helper service can hydrate data attributes from PHP services for dynamic UI state.

Migration Path

1. Constraint check first (new step, driven by v3.6.0): run composer why symfony/asset-mapper and confirm the resolved version is <8.2. If not, resolve that before anything else.
2. Install and register: composer require symfony/stimulus-bundle, then add StimulusBundle::class => ['all' => true] to config/bundles.php.
3. Configure AssetMapper: add controllers.json handling / excluded_patterns as needed in config/packages/asset_mapper.yaml.
4. Refactor templates: replace inline handlers with stimulus_controller / stimulus_action / stimulus_target.
5. Author controllers under assets/controllers/; keep them small and single-purpose.
6. Optional UX layer: Turbo for navigation, Mercure for real-time, Dropzone for uploads — only after the base integration is stable.
7. Verify and profile: controller unit tests, asset build timing, bundle-size delta vs. the jQuery it replaces.

Compatibility

Sequencing

1. Freeze the AssetMapper version at <8.2 across affected services (or defer this release).
2. Pilot on one low-risk surface (modals, tooltips, toggles).
3. Harden the pattern: controller conventions, testing harness, naming.
4. Expand to interactive components with backend-driven state.
5. Layer Turbo/Mercure only once the base is proven.
6. Retire jQuery/vanilla plugins incrementally; measure bundle size at each step.
7. Re-evaluate the AssetMapper ceiling each StimulusBundle release — a lifted conflict is the trigger to resume pipeline upgrades.

Operational Impact

Maintenance

• Low steady-state burden. The bundle is thin glue; most maintenance is in our controllers and templates, not the package.
• New ongoing task: the declared conflict makes StimulusBundle a gating dependency for AssetMapper upgrades. Someone must own tracking that pair, or upgrades will silently stall.
• Tooling dependency churn (#4086) is dev-only; it affects CI cache invalidation, not runtime.

Support

• Symfony-maintained, active release cadence, healthy contributor base (PR numbers in the 4000s). Reasonable bet.
• Support for Laravel-side questions does not exist — internal expertise must be built or hired.
• Documentation improved this release (debug:autowiring types described, #4037) — modest reduction in onboarding friction.

Scaling

• Scales fine technically: controllers are small, per-element, and lazily initialized.
• Organizational scaling is the constraint. Every new template author must know the stimulus_* helpers and the controller conventions. Without a written standard, template code drifts toward the inline JS you were replacing.
• Bundle size grows with controller count; enforce a review gate on new controller additions.

Failure Modes

Ramp-Up

• 1–2 days for Stimulus fundamentals (controllers, actions, targets, values).
• +2–3 days for the Twig helper layer and AssetMapper conventions.
• +1 day for the new upgrade-gating process and dependency runbook.
• Laravel-only teams: do not budget ramp-up — budget a substitution decision. The cost of forcing this package into a Laravel stack exceeds the cost of the native alternative.
• Recommended: one pilot pair (one backend, one frontend) becomes the internal owners; they write the template standard before broad rollout.