Deprecate template fallback mechanism (#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.

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

Tests/Twig/Extension/SonataAdminExtensionTest.php

@@ -293,30 +293,81 @@ class SonataAdminExtensionTest extends \PHPUnit_Framework_TestCase
         );
     }
 
-    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 @@ EOT
         );
     }
 
+    /**
+     * @group legacy
+     */
     public function testRenderListElementNonExistentTemplate()
     {
         $this->admin->expects($this->once())
@@ -1132,6 +1186,7 @@ EOT
     /**
      * @expectedException        Twig_Error_Loader
      * @expectedExceptionMessage Unable to find template "base_list_nonexistent_field.html.twig"
+     * @group                    legacy
      */
     public function testRenderListElementErrorLoadingTemplate()
     {

Twig/Extension/SonataAdminExtension.php

@@ -437,6 +437,12 @@ EOT;
         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) {

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.