feature #4236 Deprecate the spaceless filter (fabpot)

This PR was merged into the 3.x branch.

Discussion
----------

Deprecate the spaceless filter

Closes #3576

Deprecate the `spaceless` filter for the following reasons:

* The performance is bad (as the work is done at runtime via a regexp)
* Optimizing the size of an HTML doc server side is "almost never" a good idea (compression is better and enough)
* There are some edge cases where you want to keep some spaces (see #3576)
* Controlling whitespace is possible and fine-grained via the dedicated Twig modifiers on `{{ }}`

If someone find it useful, re-creating it is trivial (`return trim(preg_replace('/>\s+</', '><', $content ?? ''));`),
but with so many caveats and not so many use cases, I think it does not belong to core.

Commits
-------

9fd4c487 Deprecate the spaceless filter

CHANGELOG

@@ -1,5 +1,6 @@
 # 3.12.0 (2024-XX-XX)
 
+ * Deprecate the `spaceless` filter
  * Deprecate some internal methods from `Parser`: `getBlockStack()`, `hasBlock()`, `getBlock()`, `hasMacro()`, `hasTraits()`, `getParent()`
  * Deprecate passing `null` to `Twig\Parser::setParent()`
  * Update `Node::__toString()` to include the node tag if set

doc/deprecated.rst

@@ -180,3 +180,9 @@ Templates
   in ``Environment::resolveTemplate()``, ``Environment::load()``, and
   ``Template::loadTemplate()``); pass instances of ``Twig\TemplateWrapper``
   instead.
+
+Filters
+-------
+
+* The ``spaceless`` filter is deprecated as of Twig 3.12 and will be removed in
+  Twig 4.0.

doc/filters/spaceless.rst

@@ -1,6 +1,10 @@
 ``spaceless``
 =============
 
+.. warning::
+
+    The ``spaceless`` filter is deprecated as of Twig 3.12.
+
 Use the ``spaceless`` filter to remove whitespace *between HTML tags*, not
 whitespace within HTML tags or whitespace in plain text:
 

src/Extension/CoreExtension.php

@@ -215,7 +215,7 @@ final class CoreExtension extends AbstractExtension
             new TwigFilter('striptags', [self::class, 'striptags']),
             new TwigFilter('trim', [self::class, 'trim']),
             new TwigFilter('nl2br', [self::class, 'nl2br'], ['pre_escape' => 'html', 'is_safe' => ['html']]),
-            new TwigFilter('spaceless', [self::class, 'spaceless'], ['is_safe' => ['html']]),
+            new TwigFilter('spaceless', [self::class, 'spaceless'], ['is_safe' => ['html'], 'deprecated' => '3.12', 'deprecating_package' => 'twig/twig']),
 
             // array helpers
             new TwigFilter('join', [self::class, 'join']),

tests/Fixtures/filters/spaceless.legacy.test

@@ -0,0 +1,16 @@
+--TEST--
+"spaceless" filter
+--DEPRECATION--
+Since twig/twig 3.12: Twig Filter "spaceless" is deprecated in index.twig at line 2.
+Since twig/twig 3.12: Twig Filter "spaceless" is deprecated in index.twig at line 3.
+Since twig/twig 3.12: Twig Filter "spaceless" is deprecated in index.twig at line 4.
+--TEMPLATE--
+{{ "    <div>   <div>   foo   </div>   </div>"|spaceless }}
+*{{ ""|spaceless }}*
+*{{ null|spaceless }}*
+--DATA--
+return []
+--EXPECT--
+<div><div>   foo   </div></div>
+**
+**

tests/Fixtures/filters/spaceless.test

@@ -1,12 +0,0 @@
---TEST--
-"spaceless" filter
---TEMPLATE--
-{{ "    <div>   <div>   foo   </div>   </div>"|spaceless }}
-*{{ ""|spaceless }}*
-*{{ null|spaceless }}*
---DATA--
-return []
---EXPECT--
-<div><div>   foo   </div></div>
-**
-**

tests/Fixtures/macros/macro_with_capture.test

@@ -4,11 +4,11 @@ macro
 {{ _self.some_macro() }}
 
 {% macro some_macro() %}
-    {% apply spaceless %}
+    {% apply upper %}
         {% if true %}foo{% endif %}
     {% endapply %}
 {% endmacro %}
 --DATA--
 return []
 --EXPECT--
-foo
+FOO

tests/Fixtures/tags/apply/scope.test

@@ -2,7 +2,7 @@
 "apply" tag does not create a new scope
 --TEMPLATE--
 {% set foo = 'baz' %}
-{% apply spaceless %}
+{% apply upper %}
     {% set foo = 'foo' %}
     {% set bar = 'bar' %}
 {% endapply %}