feature #3883 Deprecate internal extension functions in favor of meth…

…ods on the extension classes (fabpot) This PR was squashed before being merged into the 3.x branch. Discussion ---------- Deprecate internal extension functions in favor of methods on the extension classes ~~PoC on a simple extension for now.~~ Commits ------- aa7c454 Fix CS 54d34b9 Move functions for CoreExtension 72071e8 Move functions for EscaperExtension 196e91d Move functions for StringLoaderExtension d4d0160 Move functions for DebugExtension 69a89e0 Move functions for MarkdownExtension e07e9b5 Move functions for InkyExtension bff189f Move functions for CssInlinerExtension 6a18cda Move functions for HtmlExtension 16abb69 Deprecate internal extension functions in favor of methods on the extension classes
twigphp · Dec 10, 2023 · 804cb1b · 804cb1b
2 parents d602a55 + aa7c454
commit 804cb1b
Show file tree

Hide file tree

Showing 60 changed files with 2,611 additions and 1,630 deletions.
diff --git a/CHANGELOG b/CHANGELOG
@@ -1,7 +1,9 @@
-# 3.8.1 (2023-XX-XX)
+# 3.9.0 (2023-XX-XX)
 
  * Add return type for Symfony 7 compatibility
  * Fix premature loop exit in Security Policy lookup of allowed methods/properties
+ * Deprecate all internal extension functions in favor of methods on the extension classes
+ * Mark all extension functions as @internal
 
 # 3.8.0 (2023-11-21)
 

diff --git a/composer.json b/composer.json
@@ -26,6 +26,7 @@
     "require": {
         "php": ">=7.2.5",
         "symfony/polyfill-php80": "^1.22",
+        "symfony/deprecation-contracts": "^2.5|^3",
         "symfony/polyfill-mbstring": "^1.3",
         "symfony/polyfill-ctype": "^1.8"
     },
@@ -34,6 +35,12 @@
         "psr/container": "^1.0|^2.0"
     },
     "autoload": {
+        "files": [
+            "src/Resources/core.php",
+            "src/Resources/debug.php",
+            "src/Resources/escaper.php",
+            "src/Resources/string_loader.php"
+        ],
         "psr-4" : {
             "Twig\\" : "src/"
         }

diff --git a/doc/deprecated.rst b/doc/deprecated.rst
@@ -10,3 +10,10 @@ Functions
 
  * The `twig_test_iterable` function is deprecated; use the native
    `is_iterable` instead.
+
+Extensions
+----------
+
+* All functions defined in Twig extensions are marked as internal as of Twig
+  3.9.0, and will be removed in Twig 4.0. They have been replaced by internal
+  methods on their respective extension classes.
diff --git a/extra/cssinliner-extra/CssInlinerExtension.php b/extra/cssinliner-extra/CssInlinerExtension.php
@@ -20,17 +20,20 @@ class CssInlinerExtension extends AbstractExtension
     public function getFilters()
     {
         return [
-            new TwigFilter('inline_css', 'Twig\\Extra\\CssInliner\\twig_inline_css', ['is_safe' => ['all']]),
+            new TwigFilter('inline_css', [self::class, 'inlineCss'], ['is_safe' => ['all']]),
         ];
     }
-}
 
-function twig_inline_css(string $body, string ...$css): string
-{
-    static $inliner;
-    if (null === $inliner) {
-        $inliner = new CssToInlineStyles();
-    }
+    /**
+     * @internal
+     */
+    public static function inlineCss(string $body, string ...$css): string
+    {
+        static $inliner;
+        if (null === $inliner) {
+            $inliner = new CssToInlineStyles();
+        }
 
-    return $inliner->convert($body, implode("\n", $css));
+        return $inliner->convert($body, implode("\n", $css));
+    }
 }
diff --git a/extra/cssinliner-extra/Resources/functions.php b/extra/cssinliner-extra/Resources/functions.php
@@ -0,0 +1,24 @@
+<?php
+
+/*
+ * This file is part of the Symfony 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 Twig\Extra\CssInliner;
+
+/**
+ * @internal
+ *
+ * @deprecated since Twig 3.9.0
+ */
+function twig_inline_css(string $body, string ...$css): string
+{
+    trigger_deprecation('twig/cssinliner-extra', '3.9.0', 'Using the internal "%s" function is deprecated.', __FUNCTION__);
+
+    return CssInlinerExtension::inlineCss($body, ...$css);
+}
diff --git a/extra/cssinliner-extra/Tests/LegacyFunctionsTest.php b/extra/cssinliner-extra/Tests/LegacyFunctionsTest.php
@@ -0,0 +1,28 @@
+<?php
+
+/*
+ * This file is part of Twig.
+ *
+ * (c) Fabien Potencier
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Twig\Extra\CssInliner\Tests;
+
+use PHPUnit\Framework\TestCase;
+use Twig\Extra\CssInliner\CssInlinerExtension;
+
+use function Twig\Extra\CssInliner\twig_inline_css;
+
+/**
+ * @group legacy
+ */
+class LegacyFunctionsTest extends TestCase
+{
+    public function testInlineCss()
+    {
+        $this->assertSame(CssInlinerExtension::inlineCss('<p>body</p>', 'p { color: red }'), twig_inline_css('<p>body</p>', 'p { color: red }'));
+    }
+}
diff --git a/extra/cssinliner-extra/composer.json b/extra/cssinliner-extra/composer.json
@@ -16,13 +16,15 @@
     ],
     "require": {
         "php": ">=7.2.5",
+        "symfony/deprecation-contracts": "^2.5|^3",
         "tijsverkoyen/css-to-inline-styles": "^2.0",
         "twig/twig": "^3.0"
     },
     "require-dev": {
         "symfony/phpunit-bridge": "^6.4|^7.0"
     },
     "autoload": {
+        "files": [ "Resources/functions.php" ],
         "psr-4" : { "Twig\\Extra\\CssInliner\\" : "" },
         "exclude-from-classmap": [
             "/Tests/"

diff --git a/extra/html-extra/HtmlExtension.php b/extra/html-extra/HtmlExtension.php
@@ -9,8 +9,10 @@
  * file that was distributed with this source code.
  */
 
-namespace Twig\Extra\Html {
+namespace Twig\Extra\Html;
+
 use Symfony\Component\Mime\MimeTypes;
+use Twig\Error\RuntimeError;
 use Twig\Extension\AbstractExtension;
 use Twig\TwigFilter;
 use Twig\TwigFunction;
@@ -34,7 +36,7 @@ public function getFilters(): array
     public function getFunctions(): array
     {
         return [
-            new TwigFunction('html_classes', 'twig_html_classes'),
+            new TwigFunction('html_classes', [self::class, 'htmlClasses']),
         ];
     }
 
@@ -45,6 +47,8 @@ public function getFunctions(): array
      * be done before calling this filter.
      *
      * @return string The generated data URI
+     *
+     * @internal
      */
     public function dataUri(string $data, string $mime = null, array $parameters = []): string
     {
@@ -79,33 +83,31 @@ public function dataUri(string $data, string $mime = null, array $parameters = [
 
         return $repr;
     }
-}
-}
-
-namespace {
-use Twig\Error\RuntimeError;
 
-function twig_html_classes(...$args): string
-{
-    $classes = [];
-    foreach ($args as $i => $arg) {
-        if (\is_string($arg)) {
-            $classes[] = $arg;
-        } elseif (\is_array($arg)) {
-            foreach ($arg as $class => $condition) {
-                if (!\is_string($class)) {
-                    throw new RuntimeError(sprintf('The html_classes function argument %d (key %d) should be a string, got "%s".', $i, $class, \gettype($class)));
-                }
-                if (!$condition) {
-                    continue;
+    /**
+     * @internal
+     */
+    public static function htmlClasses(...$args): string
+    {
+        $classes = [];
+        foreach ($args as $i => $arg) {
+            if (\is_string($arg)) {
+                $classes[] = $arg;
+            } elseif (\is_array($arg)) {
+                foreach ($arg as $class => $condition) {
+                    if (!\is_string($class)) {
+                        throw new RuntimeError(sprintf('The html_classes function argument %d (key %d) should be a string, got "%s".', $i, $class, \gettype($class)));
+                    }
+                    if (!$condition) {
+                        continue;
+                    }
+                    $classes[] = $class;
                 }
-                $classes[] = $class;
+            } else {
+                throw new RuntimeError(sprintf('The html_classes function argument %d should be either a string or an array, got "%s".', $i, \gettype($arg)));
             }
-        } else {
-            throw new RuntimeError(sprintf('The html_classes function argument %d should be either a string or an array, got "%s".', $i, \gettype($arg)));
         }
-    }
 
-    return implode(' ', array_unique($classes));
-}
+        return implode(' ', array_unique($classes));
+    }
 }
diff --git a/extra/html-extra/Resources/functions.php b/extra/html-extra/Resources/functions.php
@@ -0,0 +1,24 @@
+<?php
+
+/*
+ * This file is part of Twig.
+ *
+ * (c) Fabien Potencier
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+use Twig\Extra\Html\HtmlExtension;
+
+/**
+ * @internal
+ *
+ * @deprecated since Twig 3.9.0
+ */
+function twig_html_classes(...$args): string
+{
+    trigger_deprecation('twig/html-extra', '3.9.0', 'Using the internal "%s" function is deprecated.', __FUNCTION__);
+
+    return HtmlExtension::htmlClasses(...$args);
+}
diff --git a/extra/html-extra/Tests/LegacyFunctionsTest.php b/extra/html-extra/Tests/LegacyFunctionsTest.php
@@ -0,0 +1,26 @@
+<?php
+
+/*
+ * This file is part of Twig.
+ *
+ * (c) Fabien Potencier
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Twig\Extra\Html\Tests;
+
+use PHPUnit\Framework\TestCase;
+use Twig\Extra\Html\HtmlExtension;
+
+/**
+ * @group legacy
+ */
+class LegacyFunctionsTest extends TestCase
+{
+    public function testHtmlToMarkdown()
+    {
+        $this->assertSame(HtmlExtension::htmlClasses(['charset' => 'utf-8']), \twig_html_classes(['charset' => 'utf-8']));
+    }
+}
diff --git a/extra/html-extra/composer.json b/extra/html-extra/composer.json
@@ -16,13 +16,15 @@
     ],
     "require": {
         "php": ">=7.2.5",
+        "symfony/deprecation-contracts": "^2.5|^3",
         "symfony/mime": "^5.4|^6.0|^7.0",
         "twig/twig": "^3.0"
     },
     "require-dev": {
         "symfony/phpunit-bridge": "^6.4|^7.0"
     },
     "autoload": {
+        "files": [ "Resources/functions.php" ],
         "psr-4" : { "Twig\\Extra\\Html\\" : "" },
         "exclude-from-classmap": [
             "/Tests/"

diff --git a/extra/inky-extra/InkyExtension.php b/extra/inky-extra/InkyExtension.php
@@ -20,12 +20,15 @@ class InkyExtension extends AbstractExtension
     public function getFilters()
     {
         return [
-            new TwigFilter('inky_to_html', 'Twig\\Extra\\Inky\\twig_inky', ['is_safe' => ['html']]),
+            new TwigFilter('inky_to_html', [self::class, 'inky'], ['is_safe' => ['html']]),
         ];
     }
-}
 
-function twig_inky(string $body): string
-{
-    return false === ($html = Pinky\transformString($body)->saveHTML()) ? '' : $html;
+    /**
+     * @internal
+     */
+    public static function inky(string $body): string
+    {
+        return false === ($html = Pinky\transformString($body)->saveHTML()) ? '' : $html;
+    }
 }
diff --git a/extra/inky-extra/Resources/functions.php b/extra/inky-extra/Resources/functions.php
@@ -0,0 +1,24 @@
+<?php
+
+/*
+ * This file is part of the Symfony 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 Twig\Extra\Inky;
+
+/**
+ * @internal
+ *
+ * @deprecated since Twig 3.9.0
+ */
+function twig_inky(string $body): string
+{
+    trigger_deprecation('twig/inky-extra', '3.9.0', 'Using the internal "%s" function is deprecated.', __FUNCTION__);
+
+    return InkyExtension::inky($body);
+}
diff --git a/extra/inky-extra/Tests/LegacyFunctionsTest.php b/extra/inky-extra/Tests/LegacyFunctionsTest.php
@@ -0,0 +1,28 @@
+<?php
+
+/*
+ * This file is part of Twig.
+ *
+ * (c) Fabien Potencier
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Twig\Extra\Inky\Tests;
+
+use PHPUnit\Framework\TestCase;
+use Twig\Extra\Inky\InkyExtension;
+
+use function Twig\Extra\Inky\twig_inky;
+
+/**
+ * @group legacy
+ */
+class LegacyFunctionsTest extends TestCase
+{
+    public function testInlineCss()
+    {
+        $this->assertSame(InkyExtension::inky('<p>Foo</p>'), twig_inky('<p>Foo</p>'));
+    }
+}
diff --git a/extra/inky-extra/composer.json b/extra/inky-extra/composer.json
@@ -16,13 +16,15 @@
     ],
     "require": {
         "php": ">=7.2.5",
+        "symfony/deprecation-contracts": "^2.5|^3",
         "lorenzo/pinky": "^1.0.5",
         "twig/twig": "^3.0"
     },
     "require-dev": {
         "symfony/phpunit-bridge": "^6.4|^7.0"
     },
     "autoload": {
+        "files": [ "Resources/functions.php" ],
         "psr-4" : { "Twig\\Extra\\Inky\\" : "" },
         "exclude-from-classmap": [
             "/Tests/"