Deprecate template fallback mechanism (sonata-project#3817)

There does not seem to be a valid use for that. Deprecating it will help us make sure no one actually relies on it before removing it.
SirEOF · May 14, 2016 · d8b6b3d · d8b6b3d
1 parent e1936bf
commit d8b6b3d
Show file tree

Hide file tree

Showing 4 changed files with 76 additions and 9 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -13,6 +13,7 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 - Deprecated `BaseFieldDescription::camelize()`
 - Deprecated `AdminHelper::camelize()`
 - Deprecated `Admin` class
+- Deprecated default template loading on exception mechanism
 
 ### Fixed
 - Fix detection of path when using nested properties with underscores in `AdminHelper:getElementAccessPath` method

diff --git a/Tests/Twig/Extension/SonataAdminExtensionTest.php b/Tests/Twig/Extension/SonataAdminExtensionTest.php
@@ -293,30 +293,81 @@ public function testRenderListElement($expected, $type, $value, array $options)
         );
     }
 
-    public function getRenderListElementTests()
+    /**
+     * @dataProvider getDeprecatedRenderListElementTests
+     * @group legacy
+     */
+    public function testDeprecatedRenderListElement($expected, $value, array $options)
+    {
+        $this->admin->expects($this->any())
+            ->method('isGranted')
+            ->will($this->returnValue(true));
+
+        $this->admin->expects($this->any())
+            ->method('getTemplate')
+            ->with($this->equalTo('base_list_field'))
+            ->will($this->returnValue('SonataAdminBundle:CRUD:base_list_field.html.twig'));
+
+        $this->fieldDescription->expects($this->any())
+            ->method('getValue')
+            ->will($this->returnValue($value));
+
+        $this->fieldDescription->expects($this->any())
+            ->method('getType')
+            ->will($this->returnValue('nonexistent'));
+
+        $this->fieldDescription->expects($this->any())
+            ->method('getOptions')
+            ->will($this->returnValue($options));
+
+        $this->fieldDescription->expects($this->any())
+            ->method('getOption')
+            ->will($this->returnCallback(function ($name, $default = null) use ($options) {
+                return isset($options[$name]) ? $options[$name] : $default;
+            }));
+
+        $this->fieldDescription->expects($this->any())
+            ->method('getTemplate')
+            ->will($this->returnValue('SonataAdminBundle:CRUD:list_nonexistent_template.html.twig'));
+
+        $this->assertSame(
+            $this->removeExtraWhitespace($expected),
+            $this->removeExtraWhitespace($this->twigExtension->renderListElement(
+                $this->environment,
+                $this->object,
+                $this->fieldDescription
+            ))
+        );
+    }
+
+    public function getDeprecatedRenderListElementTests()
     {
         return array(
             array(
-                '<td class="sonata-ba-list-field sonata-ba-list-field-string" objectId="12345"> Example </td>',
-                'string',
+                '<td class="sonata-ba-list-field sonata-ba-list-field-nonexistent" objectId="12345"> Example </td>',
                 'Example',
                 array(),
             ),
             array(
-                '<td class="sonata-ba-list-field sonata-ba-list-field-string" objectId="12345"> </td>',
-                'string',
+                '<td class="sonata-ba-list-field sonata-ba-list-field-nonexistent" objectId="12345"> </td>',
                 null,
                 array(),
             ),
+        );
+    }
+
+    public function getRenderListElementTests()
+    {
+        return array(
             array(
-                '<td class="sonata-ba-list-field sonata-ba-list-field-nonexistent" objectId="12345"> Example </td>',
-                'nonexistent',
+                '<td class="sonata-ba-list-field sonata-ba-list-field-string" objectId="12345"> Example </td>',
+                'string',
                 'Example',
                 array(),
             ),
             array(
-                '<td class="sonata-ba-list-field sonata-ba-list-field-nonexistent" objectId="12345"> </td>',
-                'nonexistent',
+                '<td class="sonata-ba-list-field sonata-ba-list-field-string" objectId="12345"> </td>',
+                'string',
                 null,
                 array(),
             ),
@@ -1093,6 +1144,9 @@ class="x-editable"
         );
     }
 
+    /**
+     * @group legacy
+     */
     public function testRenderListElementNonExistentTemplate()
     {
         $this->admin->expects($this->once())
@@ -1132,6 +1186,7 @@ public function testRenderListElementNonExistentTemplate()
     /**
      * @expectedException        Twig_Error_Loader
      * @expectedExceptionMessage Unable to find template "base_list_nonexistent_field.html.twig"
+     * @group                    legacy
      */
     public function testRenderListElementErrorLoadingTemplate()
     {

diff --git a/Twig/Extension/SonataAdminExtension.php b/Twig/Extension/SonataAdminExtension.php
@@ -437,6 +437,12 @@ protected function getTemplate(
         try {
             $template = $environment->loadTemplate($templateName);
         } catch (\Twig_Error_Loader $e) {
+            @trigger_error(
+                'Relying on default template loading on field template loading exception '.
+                'is deprecated since 3.x and will be removed in 4.0. '.
+                'A \Twig_Error_Loader exception will be thrown instead',
+                E_USER_DEPRECATED
+            );
             $template = $environment->loadTemplate($defaultTemplate);
 
             if (null !== $this->logger) {

diff --git a/UPGRADE-3.x.md b/UPGRADE-3.x.md
@@ -4,3 +4,8 @@ UPGRADE 3.x
 ## Deprecated Admin class
 
 The `Admin` class is deprecated. Use `AbstractAdmin` instead.
+
+## Deprecated template fallback mechanism
+
+The Twig extension method that fallback to a default template when the specified one does not exist.
+You can no longer rely on that and should always specify templates that exist.