Make TemplateRegistry not mutable

UPGRADE-3.x.md

@@ -1,6 +1,21 @@
 UPGRADE 3.x
 ===========
 
+UPGRADE FROM 3.x to 3.x
+=========================
+
+### Template registry structure and responsibilities.
+
+The `Sonata\AdminBundle\Templating\TemplateRegistry` class has been splitted into 3 classes:
+   - `TemplateRegistry`, implementing `Sonata\AdminBundle\Templating\TemplateRegistryInterface`
+   - `MutableTemplateRegistry`, implementing `Sonata\AdminBundle\Templating\MutableTemplateRegistryInterface`
+   - `AbstractTemplateRegistry`, implementing `Sonata\AdminBundle\Templating\TemplateRegistryInterface`. You MUST extend this class if you want to create your own template registry.
+
+The interface `Sonata\AdminBundle\Templating\TemplateRegistryAwareInterface` was updated in order to handle instances of `TemplateRegistryInterface`.
+The interface `Sonata\AdminBundle\Templating\MutableTemplateRegistryAwareInterface` was added to provide a simple contract for classes depending on a `MutableTemplateRegistryInterface`.
+
+`TemplateRegistry` will stop implementing `MutableTemplateRegistryInterface` in version 4.0. If you are using `setTemplate()` or `setTemplates()` methods, you MUST use `MutableTemplateRegistry` instead.
+
 ### Deprecated `Sonata\AdminBundle\Model\DatagridManagerInterface` interface.
 
 This interface has been deprecated without replacement.

src/Admin/Pool.php

@@ -80,6 +80,8 @@ class Pool
     protected $propertyAccessor;
 
     /**
+     * NEXT_MAJOR: change to TemplateRegistryInterface.
+     *
      * @var MutableTemplateRegistryInterface
      */
     private $templateRegistry;
@@ -469,6 +471,9 @@ public function getAdminClasses()
         return $this->adminClasses;
     }
 
+    /**
+     * NEXT_MAJOR: change to TemplateRegistryInterface.
+     */
     final public function setTemplateRegistry(MutableTemplateRegistryInterface $templateRegistry): void
     {
         $this->templateRegistry = $templateRegistry;

src/Resources/config/core.php

@@ -238,6 +238,7 @@
 
         ->alias(TemplateRegistry::class, 'sonata.admin.global_template_registry')
 
+        // NEXT_MAJOR: remove this alias, global template registry SHOULD NOT be mutable
         ->alias(MutableTemplateRegistryInterface::class, 'sonata.admin.global_template_registry')
     ;
 };

src/Templating/AbstractTemplateRegistry.php

@@ -0,0 +1,66 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the Sonata Project package.
+ *
+ * (c) Thomas Rabaix <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Sonata\AdminBundle\Templating;
+
+abstract class AbstractTemplateRegistry implements TemplateRegistryInterface
+{
+    /**
+     * @var array<string, string>
+     */
+    protected $templates = [];
+
+    /**
+     * @param string[] $templates
+     */
+    public function __construct(array $templates = [])
+    {
+        $this->templates = $templates;
+    }
+
+    public function getTemplates(): array
+    {
+        return $this->templates;
+    }
+
+    public function hasTemplate(string $name): bool
+    {
+        return isset($this->templates[$name]);
+    }
+
+    /**
+     * NEXT_MAJOR: add type hint.
+     *
+     * @param string $name
+     */
+    public function getTemplate($name): ?string
+    {
+        if ($this->hasTemplate($name)) {
+            return $this->templates[$name];
+        }
+
+        @trigger_error(sprintf(
+            'Passing a nonexistent template name as argument 1 to %s() is deprecated since'
+            .' sonata-project/admin-bundle 3.52 and will throw an exception in 4.0.',
+            __METHOD__
+        ), E_USER_DEPRECATED);
+
+        // NEXT_MAJOR : remove the previous `trigger_error()` call, the `return null` statement, uncomment the following exception and declare string as return type
+        // throw new \InvalidArgumentException(sprintf(
+        //    'Template named "%s" doesn\'t exist.',
+        //    $name
+        // ));
+
+        return null;
+    }
+}

src/Templating/MutableTemplateRegistry.php

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the Sonata Project package.
+ *
+ * (c) Thomas Rabaix <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Sonata\AdminBundle\Templating;
+
+/**
+ * @author Wojciech Błoszyk <[email protected]>
+ */
+final class MutableTemplateRegistry extends AbstractTemplateRegistry implements MutableTemplateRegistryInterface
+{
+    // NEXT_MAJOR: change method declaration for new one
+    // public function setTemplates(array $templates): void
+    public function setTemplates(array $templates)
+    {
+        $this->templates = $templates;
+    }
+
+    // NEXT_MAJOR: change method declaration for new one
+    // public function setTemplate(string $name, string $template): void
+    public function setTemplate($name, $template)
+    {
+        $this->templates[$name] = $template;
+    }
+}

src/Templating/MutableTemplateRegistryAwareInterface.php

@@ -0,0 +1,30 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the Sonata Project package.
+ *
+ * (c) Thomas Rabaix <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Sonata\AdminBundle\Templating;
+
+/**
+ * @author Wojciech Błoszyk <[email protected]>
+ *
+ * @method MutableTemplateRegistryInterface getTemplateRegistry()
+ * @method bool                             hasTemplateRegistry()
+ * @method void                             setTemplateRegistry(MutableTemplateRegistryInterface $templateRegistry)
+ */
+interface MutableTemplateRegistryAwareInterface
+{
+    // NEXT_MAJOR: uncomment this method in 4.0
+    //public function getTemplateRegistry(): MutableTemplateRegistryInterface;
+
+    // NEXT_MAJOR: uncomment this method in 4.0
+    //public function setTemplateRegistry(MutableTemplateRegistryInterface $templateRegistry): void;
+}

src/Templating/MutableTemplateRegistryInterface.php

@@ -19,15 +19,26 @@
 interface MutableTemplateRegistryInterface extends TemplateRegistryInterface
 {
     /**
+     * NEXT_MAJOR: remove this method declaration with docblock and uncomment code below.
+     *
      * @param array<string, string> $templates 'name' => 'file_path.html.twig'
      */
     public function setTemplates(array $templates);
 
+    ///**
+    // * @param array<string, string> $templates 'name' => 'file_path.html.twig'
+    // */
+    //public function setTemplates(array $templates): void;
+
     /**
+     * NEXT_MAJOR: remove this method declaration with docblock and uncomment code below.
+     *
      * @param string $name
      * @param string $template
      *
      * @return void
      */
     public function setTemplate($name, $template);
+
+    //public function setTemplate(string $name, string $template): void;
 }

src/Templating/TemplateRegistry.php

@@ -15,109 +15,38 @@
 
 /**
  * @author Timo Bakx <[email protected]>
+ *
+ * NEXT_MAJOR: remove `MutableTemplateRegistryInterface` implementation.
  */
-final class TemplateRegistry implements MutableTemplateRegistryInterface
+final class TemplateRegistry extends AbstractTemplateRegistry implements MutableTemplateRegistryInterface
 {
-    public const TYPE_ARRAY = 'array';
-    public const TYPE_BOOLEAN = 'boolean';
-    public const TYPE_DATE = 'date';
-    public const TYPE_TIME = 'time';
-    public const TYPE_DATETIME = 'datetime';
-    /**
-     * NEXT_MAJOR: Remove this constant.
-     *
-     * @deprecated since sonata-project/admin-bundle 3.68, to be removed in 4.0. Use Sonata\AdminBundle\Templating\TemplateRegistry::TYPE_STRING instead.
-     */
-    public const TYPE_TEXT = 'text';
-    public const TYPE_TEXTAREA = 'textarea';
-    public const TYPE_EMAIL = 'email';
-    public const TYPE_TRANS = 'trans';
-    public const TYPE_STRING = 'string';
-    /**
-     * NEXT_MAJOR: Remove this constant.
-     *
-     * @deprecated since sonata-project/admin-bundle 3.68, to be removed in 4.0. Use Sonata\AdminBundle\Templating\TemplateRegistry::TYPE_INTEGER instead.
-     */
-    public const TYPE_SMALLINT = 'smallint';
-    /**
-     * NEXT_MAJOR: Remove this constant.
-     *
-     * @deprecated since sonata-project/admin-bundle 3.68, to be removed in 4.0. Use Sonata\AdminBundle\Templating\TemplateRegistry::TYPE_INTEGER instead.
-     */
-    public const TYPE_BIGINT = 'bigint';
-    public const TYPE_INTEGER = 'integer';
     /**
-     * NEXT_MAJOR: Remove this constant.
+     * NEXT_MAJOR: remove this method.
      *
-     * @deprecated since sonata-project/admin-bundle 3.68, to be removed in 4.0. Use Sonata\AdminBundle\Templating\TemplateRegistry::TYPE_FLOAT instead.
+     * @deprecated since version sonata-project/admin-bundle 3.39.0 and will be removed in 4.0. Use Sonata\AdminBundle\Templating\MutableTemplateRegistry instead.
      */
-    public const TYPE_DECIMAL = 'decimal';
-    public const TYPE_FLOAT = 'float';
-    public const TYPE_IDENTIFIER = 'identifier';
-    public const TYPE_CURRENCY = 'currency';
-    public const TYPE_PERCENT = 'percent';
-    public const TYPE_CHOICE = 'choice';
-    public const TYPE_URL = 'url';
-    public const TYPE_HTML = 'html';
-    public const TYPE_MANY_TO_MANY = 'many_to_many';
-    public const TYPE_MANY_TO_ONE = 'many_to_one';
-    public const TYPE_ONE_TO_MANY = 'one_to_many';
-    public const TYPE_ONE_TO_ONE = 'one_to_one';
-
-    /**
-     * @var array<string, string>
-     */
-    private $templates = [];
-
-    /**
-     * @param string[] $templates
-     */
-    public function __construct(array $templates = [])
-    {
-        $this->templates = $templates;
-    }
-
-    public function getTemplates(): array
-    {
-        return $this->templates;
-    }
-
     public function setTemplates(array $templates)
     {
         $this->templates = $templates;
-    }
 
-    public function hasTemplate(string $name): bool
-    {
-        return isset($this->templates[$name]);
+        @trigger_error(sprintf(
+            'Method "%s()" is deprecated since sonata-admin/admin-bundle 3.39 and will be removed in 4.0.',
+            __METHOD__
+        ), E_USER_DEPRECATED);
     }
 
     /**
-     * @param string $name
+     * NEXT_MAJOR: remove this method.
+     *
+     * @deprecated since version sonata-project/admin-bundle 3.39.0 and will be removed in 4.0. Use Sonata\AdminBundle\Templating\MutableTemplateRegistry instead.
      */
-    public function getTemplate($name): ?string
+    public function setTemplate($name, $template)
     {
-        if (isset($this->templates[$name])) {
-            return $this->templates[$name];
-        }
+        $this->templates[$name] = $template;
 
         @trigger_error(sprintf(
-            'Passing a nonexistent template name as argument 1 to %s() is deprecated since'
-            .' sonata-project/admin-bundle 3.52 and will throw an exception in 4.0.',
+            'Method "%s()" is deprecated since sonata-admin/admin-bundle 3.39 and will be removed in 4.0.',
             __METHOD__
         ), E_USER_DEPRECATED);
-
-        // NEXT_MAJOR : remove the previous `trigger_error()` call, the `return null` statement, uncomment the following exception and declare string as return type
-        // throw new \InvalidArgumentException(sprintf(
-        //    'Template named "%s" doesn\'t exist.',
-        //    $name
-        // ));
-
-        return null;
-    }
-
-    public function setTemplate($name, $template)
-    {
-        $this->templates[$name] = $template;
     }
 }

src/Templating/TemplateRegistryAwareInterface.php

@@ -14,21 +14,20 @@
 namespace Sonata\AdminBundle\Templating;
 
 /**
- * /**
  * @author Wojciech Błoszyk <[email protected]>
  *
- * @method MutableTemplateRegistryInterface getTemplateRegistry()
- * @method bool                             hasTemplateRegistry()
- * @method void                             setTemplateRegistry(MutableTemplateRegistryInterface $templateRegistry)
+ * @method TemplateRegistryInterface getTemplateRegistry()
+ * @method bool                      hasTemplateRegistry()
+ * @method void                      setTemplateRegistry(TemplateRegistryInterface $templateRegistry)
  */
 interface TemplateRegistryAwareInterface
 {
     // NEXT_MAJOR: uncomment this method in 4.0
-    //public function getTemplateRegistry(): MutableTemplateRegistryInterface;
+    //public function getTemplateRegistry(): TemplateRegistryInterface;
 
     // NEXT_MAJOR: uncomment this method in 4.0
     //public function hasTemplateRegistry(): bool;
 
     // NEXT_MAJOR: uncomment this method in 4.0
-    //public function setTemplateRegistry(MutableTemplateRegistryInterface $templateRegistry): void;
+    //public function setTemplateRegistry(TemplateRegistryInterface $templateRegistry): void;
 }