feature #211 [WIP] Deprecating the stimulus functionality in favor of…

… an upcoming StimulusBundle (weaverryan)

This PR was squashed before being merged into the main branch.

Discussion
----------

[WIP] Deprecating the stimulus functionality in favor of an upcoming StimulusBundle

Hi!

This isn't ready yet, but a new StimulusBundle is being created that will now be the home of the `stimulus_` Twig functions 🎆 . This PR is to deprecate those functions and only load them if the StimulusBundle is not present.

Cheers!

Commits
-------

2a15b75 [WIP] Deprecating the stimulus functionality in favor of an upcoming StimulusBundle

.github/workflows/static.yml

@@ -49,7 +49,7 @@ jobs:
           composer-options: "--working-dir=tools/php-cs-fixer"
 
       - name: PHP-CS-Fixer
-        run: tools/php-cs-fixer/vendor/bin/php-cs-fixer fix --dry-run --format=checkstyle | cs2pr
+        run: tools/php-cs-fixer/vendor/bin/php-cs-fixer fix --dry-run
 
   psalm:
     name: Psalm

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## v1.17.0
+
+- Deprecated the `stimulus_controller()`, `stimulus_action()` and `stimulus_target`
+  functions and related classes. Install `symfony/stimulus-bundle` instead.
+
 ## [v1.16.0](https://github.com/symfony/webpack-encore-bundle/releases/tag/v1.16.0)
 
 *October 18th, 2022*

doc/index.rst

@@ -204,160 +204,11 @@ different ways:
 Stimulus / Symfony UX Helper
 ----------------------------
 
-stimulus_controller
-~~~~~~~~~~~~~~~~~~~
-
-This bundle also ships with a special ``stimulus_controller()`` Twig function
-that can be used to render `Stimulus Controllers & Values`_ and `CSS Classes`_.
-See `stimulus-bridge`_ for more details.
-
-For example:
-
-.. code-block:: html+twig
-
-    <div {{ stimulus_controller('chart', { 'name': 'Likes', 'data': [1, 2, 3, 4] }) }}>
-        Hello
-    </div>
-
-    <!-- would render -->
-    <div
-       data-controller="chart"
-       data-chart-name-value="Likes"
-       data-chart-data-value="&#x5B;1,2,3,4&#x5D;"
-    >
-       Hello
-    </div>
-
-If you want to set CSS classes:
-
-.. code-block:: html+twig
-
-    <div {{ stimulus_controller('chart', { 'name': 'Likes', 'data': [1, 2, 3, 4] }, { 'loading': 'spinner' }) }}>
-        Hello
-    </div>
-
-    <!-- would render -->
-    <div
-       data-controller="chart"
-       data-chart-name-value="Likes"
-       data-chart-data-value="&#x5B;1,2,3,4&#x5D;"
-       data-chart-loading-class="spinner"
-    >
-       Hello
-    </div>
-
-    <!-- or without values -->
-    <div {{ stimulus_controller('chart', controllerClasses = { 'loading': 'spinner' }) }}>
-        Hello
-    </div>
-
-Any non-scalar values (like ``data: [1, 2, 3, 4]``) are JSON-encoded. And all
-values are properly escaped (the string ``&#x5B;`` is an escaped
-``[`` character, so the attribute is really ``[1,2,3,4]``).
-
-If you have multiple controllers on the same element, you can chain them as there's also a ``stimulus_controller`` filter:
-
-.. code-block:: html+twig
-
-    <div {{ stimulus_controller('chart', { 'name': 'Likes' })|stimulus_controller('other-controller') }}>
-        Hello
-    </div>
-
-You can also retrieve the generated attributes as an array, which can be helpful e.g. for forms:
-
-.. code-block:: twig
-
-    {{ form_start(form, { attr: stimulus_controller('chart', { 'name': 'Likes' }).toArray() }) }}
-
-stimulus_action
-~~~~~~~~~~~~~~~
-
-The ``stimulus_action()`` Twig function can be used to render `Stimulus Actions`_.
-
-For example:
-
-.. code-block:: html+twig
-
-    <div {{ stimulus_action('controller', 'method') }}>Hello</div>
-    <div {{ stimulus_action('controller', 'method', 'click') }}>Hello</div>
-
-    <!-- would render -->
-    <div data-action="controller#method">Hello</div>
-    <div data-action="click->controller#method">Hello</div>
-
-If you have multiple actions and/or methods on the same element, you can chain them as there's also a
-``stimulus_action`` filter:
-
-.. code-block:: html+twig
-
-    <div {{ stimulus_action('controller', 'method')|stimulus_action('other-controller', 'test') }}>
-        Hello
-    </div>
-
-    <!-- would render -->
-    <div data-action="controller#method other-controller#test">
-        Hello
-    </div>
-
-You can also retrieve the generated attributes as an array, which can be helpful e.g. for forms:
-
-.. code-block:: twig
-
-    {{ form_row(form.password, { attr: stimulus_action('hello-controller', 'checkPasswordStrength').toArray() }) }}
-
-You can also pass `parameters`_ to actions:
-
-.. code-block:: html+twig
-
-    <div {{ stimulus_action('hello-controller', 'method', 'click', { 'count': 3 }) }}>Hello</div>
-
-    <!-- would render -->
-    <div data-action="click->hello-controller#method" data-hello-controller-count-param="3">Hello</div>
-
-stimulus_target
-~~~~~~~~~~~~~~~
-
-The ``stimulus_target()`` Twig function can be used to render `Stimulus Targets`_.
-
-For example:
-
-.. code-block:: html+twig
-
-    <div {{ stimulus_target('controller', 'a-target') }}>Hello</div>
-    <div {{ stimulus_target('controller', 'a-target second-target') }}>Hello</div>
-
-    <!-- would render -->
-    <div data-controller-target="a-target">Hello</div>
-    <div data-controller-target="a-target second-target">Hello</div>
-
-If you have multiple targets on the same element, you can chain them as there's also a `stimulus_target` filter:
-
-.. code-block:: html+twig
-
-    <div {{ stimulus_target('controller', 'a-target')|stimulus_target('other-controller', 'another-target') }}>
-        Hello
-    </div>
-
-    <!-- would render -->
-    <div data-controller-target="a-target" data-other-controller-target="another-target">
-        Hello
-    </div>
-
-You can also retrieve the generated attributes as an array, which can be helpful e.g. for forms:
-
-.. code-block:: twig
-
-    {{ form_row(form.password, { attr: stimulus_target('hello-controller', 'a-target').toArray() }) }}
-
-Ok, have fun!
-
+The ``stimulus_controller()``, ``stimulus_action()`` and ``stimulus_target()``
+Twig functions are deprecated in WebpackEncoreBundle 1.17.0. Install and
+use `symfony/stimulus-bundle`_ for that functionality.
 
 .. _`Webpack Encore`: https://symfony.com/doc/current/frontend.html
 .. _`enable the bundle manually`: https://symfony.com/doc/current/bundles.html
 .. _`"splits" your files`: https://webpack.js.org/plugins/split-chunks-plugin/
-.. _`Stimulus Controllers & Values`: https://stimulus.hotwired.dev/reference/values
-.. _`CSS Classes`: https://stimulus.hotwired.dev/reference/css-classes
-.. _`stimulus-bridge`: https://github.com/symfony/stimulus-bridge
-.. _`Stimulus Actions`: https://stimulus.hotwired.dev/reference/actions
-.. _`parameters`: https://stimulus.hotwired.dev/reference/actions#action-parameters
-.. _`Stimulus Targets`: https://stimulus.hotwired.dev/reference/targets
+.. _`symfony/stimulus-bundle`: https://symfony.com/bundles/StimulusBundle/current/index.html

src/CacheWarmer/EntrypointCacheWarmer.php

@@ -24,9 +24,6 @@ public function __construct(array $cacheKeys, string $phpArrayFile)
         parent::__construct($phpArrayFile);
     }
 
-    /**
-     * {@inheritdoc}
-     */
     protected function doWarmUp($cacheDir, ArrayAdapter $arrayAdapter): bool
     {
         foreach ($this->cacheKeys as $cacheKey => $path) {

src/DependencyInjection/Compiler/RemoveStimulusServicesPass.php

@@ -0,0 +1,24 @@
+<?php
+
+/*
+ * This file is part of the Symfony WebpackEncoreBundle package.
+ * (c) Fabien Potencier <fabien@symfony.com>
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\WebpackEncoreBundle\DependencyInjection\Compiler;
+
+use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
+use Symfony\Component\DependencyInjection\ContainerBuilder;
+
+class RemoveStimulusServicesPass implements CompilerPassInterface
+{
+    public function process(ContainerBuilder $container)
+    {
+        if ($container->hasDefinition('stimulus.helper')) {
+            // remove the Stimulus integration if StimulusBundle is installed
+            $container->removeDefinition('webpack_encore.twig_stimulus_extension');
+        }
+    }
+}

src/Dto/AbstractStimulusDto.php

@@ -15,6 +15,8 @@
 
 /**
  * @internal
+ *
+ * @deprecated since 1.17.0 - install symfony/stimulus-bundle instead.
  */
 abstract class AbstractStimulusDto implements \Stringable
 {

src/Dto/StimulusActionsDto.php

@@ -11,6 +11,9 @@
 
 namespace Symfony\WebpackEncoreBundle\Dto;
 
+/**
+ * @deprecated since 1.17.0 - install symfony/stimulus-bundle instead.
+ */
 final class StimulusActionsDto extends AbstractStimulusDto
 {
     private $actions = [];

src/Dto/StimulusControllersDto.php

@@ -11,6 +11,9 @@
 
 namespace Symfony\WebpackEncoreBundle\Dto;
 
+/**
+ * @deprecated since 1.17.0 - install symfony/stimulus-bundle instead.
+ */
 final class StimulusControllersDto extends AbstractStimulusDto
 {
     private $controllers = [];

src/Dto/StimulusTargetsDto.php

@@ -11,6 +11,9 @@
 
 namespace Symfony\WebpackEncoreBundle\Dto;
 
+/**
+ * @deprecated since 1.17.0 - install symfony/stimulus-bundle instead.
+ */
 final class StimulusTargetsDto extends AbstractStimulusDto
 {
     private $targets = [];

src/Twig/StimulusTwigExtension.php

@@ -17,6 +17,9 @@
 use Twig\TwigFilter;
 use Twig\TwigFunction;
 
+/**
+ * @deprecated since 1.17.0 - install symfony/stimulus-bundle instead.
+ */
 final class StimulusTwigExtension extends AbstractExtension
 {
     public function getFunctions(): array

src/WebpackEncoreBundle.php

@@ -9,8 +9,14 @@
 
 namespace Symfony\WebpackEncoreBundle;
 
+use Symfony\Component\DependencyInjection\ContainerBuilder;
 use Symfony\Component\HttpKernel\Bundle\Bundle;
+use Symfony\WebpackEncoreBundle\DependencyInjection\Compiler\RemoveStimulusServicesPass;
 
 final class WebpackEncoreBundle extends Bundle
 {
+    public function build(ContainerBuilder $container)
+    {
+        $container->addCompilerPass(new RemoveStimulusServicesPass());
+    }
 }