deprecated Twig_Error::getTemplateFile() and Twig_Error::setTemplateFile()

CHANGELOG

@@ -1,5 +1,6 @@
 * 1.27.0 (2016-XX-XX)
 
+ * deprecated Twig_Error::getTemplateFile() and Twig_Error::setTemplateFile() in favor of Twig_Error::getTemplateName() and Twig_Error::setTemplateName()
  * deprecated Parser::getFilename()
  * fixed template paths when a template name contains a protocol like vfs://
  * improved debugging with Twig_Sandbox_SecurityError exceptions for disallowed methods and properties

doc/deprecated.rst

@@ -180,3 +180,8 @@ Miscellaneous
 * As of Twig 1.x, ``Twig_Template::getEnvironment()`` and
   ``Twig_TemplateInterface::getEnvironment()`` are deprecated and will be
   removed in 2.0.
+
+* As of Twig 1.27, ``Twig_Error::getTemplateFile()`` and
+  ``Twig_Error::setTemplateFile()`` are deprecated. Use
+  ``Twig_Error::getTemplateName()`` and ``Twig_Error::setTemplateName()``
+  instead.

lib/Twig/Environment.php

@@ -704,7 +704,7 @@ class Twig_Environment
         try {
             return $this->compile($this->parse($this->tokenize($source, $name)));
         } catch (Twig_Error $e) {
-            $e->setTemplateFile($name);
+            $e->setTemplateName($name);
             throw $e;
         } catch (Exception $e) {
             throw new Twig_Error_Syntax(sprintf('An exception has been thrown during the compilation of a template ("%s").', $e->getMessage()), -1, $name, $e);

lib/Twig/Error.php

@@ -25,8 +25,8 @@
  * and line number) yourself by passing them to the constructor. If some or all
  * these information are not available from where you throw the exception, then
  * this class will guess them automatically (when the line number is set to -1
- * and/or the filename is set to null). As this is a costly operation, this
+ * and/or the name is set to null). As this is a costly operation, this
- * can be disabled by passing false for both the filename and the line number
+ * can be disabled by passing false for both the name and the line number
  * when creating a new instance of this class.
  *
  * @author Fabien Potencier <fabien@symfony.com>
@@ -34,6 +34,7 @@
 class Twig_Error extends Exception
 {
     protected $lineno;
+    // to be renamed to name in 2.0
     protected $filename;
     protected $rawMessage;
     protected $previous;
@@ -41,21 +42,21 @@ class Twig_Error extends Exception
     /**
      * Constructor.
      *
-     * Set both the line number and the filename to false to
+     * Set both the line number and the name to false to
      * disable automatic guessing of the original template name
      * and line number.
      *
      * Set the line number to -1 to enable its automatic guessing.
-     * Set the filename to null to enable its automatic guessing.
+     * Set the name to null to enable its automatic guessing.
      *
      * By default, automatic guessing is enabled.
      *
      * @param string    $message  The error message
      * @param int       $lineno   The template line where the error occurred
-     * @param string    $filename The template file name where the error occurred
+     * @param string    $name     The template logical name where the error occurred
      * @param Exception $previous The previous exception
      */
-    public function __construct($message, $lineno = -1, $filename = null, Exception $previous = null)
+    public function __construct($message, $lineno = -1, $name = null, Exception $previous = null)
     {
         if (PHP_VERSION_ID < 50300) {
             $this->previous = $previous;
@@ -65,9 +66,9 @@ class Twig_Error extends Exception
         }
 
         $this->lineno = $lineno;
-        $this->filename = $filename;
+        $this->filename = $name;
 
-        if (-1 === $this->lineno || null === $this->filename) {
+        if (-1 === $lineno || null === $name) {
             $this->guessTemplateInfo();
         }
 
@@ -87,23 +88,53 @@ class Twig_Error extends Exception
     }
 
     /**
-     * Gets the filename where the error occurred.
+     * Gets the logical name where the error occurred.
      *
-     * @return string The filename
+     * @return string The name
+     *
+     * @deprecated since 1.27 (to be removed in 2.0). Use getTemplateName() instead.
      */
     public function getTemplateFile()
+    {
+        @trigger_error(sprintf('The "%s" method is deprecated since version 1.27 and will be removed in 2.0. Use getTemplateName() instead.', __METHOD__), E_USER_DEPRECATED);
+
+        return $this->filename;
+    }
+
+    /**
+     * Sets the logical name where the error occurred.
+     *
+     * @param string $name The name
+     *
+     * @deprecated since 1.27 (to be removed in 2.0). Use setTemplateName() instead.
+     */
+    public function setTemplateFile($name)
+    {
+        @trigger_error(sprintf('The "%s" method is deprecated since version 1.27 and will be removed in 2.0. Use setTemplateName() instead.', __METHOD__), E_USER_DEPRECATED);
+
+        $this->filename = $name;
+
+        $this->updateRepr();
+    }
+
+    /**
+     * Gets the logical name where the error occurred.
+     *
+     * @return string The name
+     */
+    public function getTemplateName()
     {
         return $this->filename;
     }
 
     /**
-     * Sets the filename where the error occurred.
+     * Sets the logical name where the error occurred.
      *
-     * @param string $filename The filename
+     * @param string $name The name
      */
-    public function setTemplateFile($filename)
+    public function setTemplateName($name)
     {
-        $this->filename = $filename;
+        $this->filename = $name;
 
         $this->updateRepr();
     }
@@ -182,11 +213,11 @@ class Twig_Error extends Exception
 
         if ($this->filename) {
             if (is_string($this->filename) || (is_object($this->filename) && method_exists($this->filename, '__toString'))) {
-                $filename = sprintf('"%s"', $this->filename);
+                $name = sprintf('"%s"', $this->filename);
             } else {
-                $filename = json_encode($this->filename);
+                $name = json_encode($this->filename);
             }
-            $this->message .= sprintf(' in %s', $filename);
+            $this->message .= sprintf(' in %s', $name);
         }
 
         if ($this->lineno && $this->lineno >= 0) {
@@ -227,7 +258,7 @@ class Twig_Error extends Exception
             }
         }
 
-        // update template filename
+        // update template name
         if (null !== $template && null === $this->filename) {
             $this->filename = $template->getTemplateName();
         }

lib/Twig/Node/CheckSecurity.php

@@ -56,7 +56,7 @@ class Twig_Node_CheckSecurity extends Twig_Node
             ->outdent()
             ->write("} catch (Twig_Sandbox_SecurityError \$e) {\n")
             ->indent()
-            ->write("\$e->setTemplateFile(\$this->getTemplateName());\n\n")
+            ->write("\$e->setTemplateName(\$this->getTemplateName());\n\n")
             ->write("if (\$e instanceof Twig_Sandbox_SecurityNotAllowedTagError && isset(\$tags[\$e->getTagName()])) {\n")
             ->indent()
             ->write("\$e->setTemplateLine(\$tags[\$e->getTagName()]);\n")

lib/Twig/Parser.php

@@ -108,8 +108,8 @@ class Twig_Parser implements Twig_ParserInterface
                 $body = new Twig_Node();
             }
         } catch (Twig_Error_Syntax $e) {
-            if (!$e->getTemplateFile()) {
+            if (!$e->getTemplateName()) {
-                $e->setTemplateFile($this->stream->getFilename());
+                $e->setTemplateName($this->stream->getFilename());
             }
 
             if (!$e->getTemplateLine()) {

lib/Twig/Template.php

@@ -107,7 +107,7 @@ abstract class Twig_Template implements Twig_TemplateInterface
                 $this->parents[$parent] = $this->loadTemplate($parent);
             }
         } catch (Twig_Error_Loader $e) {
-            $e->setTemplateFile(null);
+            $e->setTemplateName(null);
             $e->guess();
 
             throw $e;
@@ -188,8 +188,8 @@ abstract class Twig_Template implements Twig_TemplateInterface
             try {
                 $template->$block($context, $blocks);
             } catch (Twig_Error $e) {
-                if (!$e->getTemplateFile()) {
+                if (!$e->getTemplateName()) {
-                    $e->setTemplateFile($template->getTemplateName());
+                    $e->setTemplateName($template->getTemplateName());
                 }
 
                 // this is mostly useful for Twig_Error_Loader exceptions
@@ -307,8 +307,8 @@ abstract class Twig_Template implements Twig_TemplateInterface
 
             return $this->env->loadTemplate($template, $index);
         } catch (Twig_Error $e) {
-            if (!$e->getTemplateFile()) {
+            if (!$e->getTemplateName()) {
-                $e->setTemplateFile($templateName ? $templateName : $this->getTemplateName());
+                $e->setTemplateName($templateName ? $templateName : $this->getTemplateName());
             }
 
             if ($e->getTemplateLine()) {
@@ -381,8 +381,8 @@ abstract class Twig_Template implements Twig_TemplateInterface
         try {
             $this->doDisplay($context, $blocks);
         } catch (Twig_Error $e) {
-            if (!$e->getTemplateFile()) {
+            if (!$e->getTemplateName()) {
-                $e->setTemplateFile($this->getTemplateName());
+                $e->setTemplateName($this->getTemplateName());
             }
 
             // this is mostly useful for Twig_Error_Loader exceptions

lib/Twig/Test/IntegrationTestCase.php

@@ -174,7 +174,7 @@ abstract class Twig_Test_IntegrationTestCase extends PHPUnit_Framework_TestCase
                 }
 
                 if ($e instanceof Twig_Error_Syntax) {
-                    $e->setTemplateFile($file);
+                    $e->setTemplateName($file);
 
                     throw $e;
                 }
@@ -192,7 +192,7 @@ abstract class Twig_Test_IntegrationTestCase extends PHPUnit_Framework_TestCase
                 }
 
                 if ($e instanceof Twig_Error_Syntax) {
-                    $e->setTemplateFile($file);
+                    $e->setTemplateName($file);
                 } else {
                     $e = new Twig_Error(sprintf('%s: %s', get_class($e), $e->getMessage()), -1, $file, $e);
                 }

test/Twig/Tests/ErrorTest.php

@@ -14,7 +14,7 @@ class Twig_Tests_ErrorTest extends PHPUnit_Framework_TestCase
     public function testErrorWithObjectFilename()
     {
         $error = new Twig_Error('foo');
-        $error->setTemplateFile(new SplFileInfo(__FILE__));
+        $error->setTemplateName(new SplFileInfo(__FILE__));
 
         $this->assertContains('test'.DIRECTORY_SEPARATOR.'Twig'.DIRECTORY_SEPARATOR.'Tests'.DIRECTORY_SEPARATOR.'ErrorTest.php', $error->getMessage());
     }
@@ -22,7 +22,7 @@ class Twig_Tests_ErrorTest extends PHPUnit_Framework_TestCase
     public function testErrorWithArrayFilename()
     {
         $error = new Twig_Error('foo');
-        $error->setTemplateFile(array('foo' => 'bar'));
+        $error->setTemplateName(array('foo' => 'bar'));
 
         $this->assertEquals('foo in {"foo":"bar"}', $error->getMessage());
     }
@@ -40,7 +40,7 @@ class Twig_Tests_ErrorTest extends PHPUnit_Framework_TestCase
         } catch (Twig_Error_Runtime $e) {
             $this->assertEquals('Variable "foo" does not exist in "index.html" at line 3.', $e->getMessage());
             $this->assertEquals(3, $e->getTemplateLine());
-            $this->assertEquals('index.html', $e->getTemplateFile());
+            $this->assertEquals('index.html', $e->getTemplateName());
         }
 
         try {
@@ -50,7 +50,7 @@ class Twig_Tests_ErrorTest extends PHPUnit_Framework_TestCase
         } catch (Twig_Error_Runtime $e) {
             $this->assertEquals('An exception has been thrown during the rendering of a template ("Runtime error...") in "index.html" at line 3.', $e->getMessage());
             $this->assertEquals(3, $e->getTemplateLine());
-            $this->assertEquals('index.html', $e->getTemplateFile());
+            $this->assertEquals('index.html', $e->getTemplateName());
         }
     }
 
@@ -71,7 +71,7 @@ class Twig_Tests_ErrorTest extends PHPUnit_Framework_TestCase
         } catch (Twig_Error_Runtime $e) {
             $this->assertEquals(sprintf('Variable "foo" does not exist in "%s" at line %d.', $name, $line), $e->getMessage());
             $this->assertEquals($line, $e->getTemplateLine());
-            $this->assertEquals($name, $e->getTemplateFile());
+            $this->assertEquals($name, $e->getTemplateName());
         }
 
         try {
@@ -81,7 +81,7 @@ class Twig_Tests_ErrorTest extends PHPUnit_Framework_TestCase
         } catch (Twig_Error_Runtime $e) {
             $this->assertEquals(sprintf('An exception has been thrown during the rendering of a template ("Runtime error...") in "%s" at line %d.', $name, $line), $e->getMessage());
             $this->assertEquals($line, $e->getTemplateLine());
-            $this->assertEquals($name, $e->getTemplateFile());
+            $this->assertEquals($name, $e->getTemplateName());
         }
     }