feature #1886 deprecated Twig_ExtensionInterface::initRuntime() (fabpot)

This PR was merged into the 1.x branch.

Discussion
----------

deprecated Twig_ExtensionInterface::initRuntime()

I'm working on splitting Twig extensions into 2 different phases: compilation and runtime. The goal is to avoid having to load the runtime environment of an extension when compiling templates. That also opens the way to be able to lazy-load Twig extensions.

While working on the split, I realized that the `initRuntime()` method on `Twig_ExtensionInterface` is not needed anymore. It was added at a time `needs_environment` did not exist and was a way to keep the environment around for custom filters/tests/functions. But nowadays, that's not needed anymore. I did a quick search on Github, and most of the implementation I found just store the environment in a local property, which is not needed anymore. So, I propose to deprecate it in 1.x and remove it in 2.0.

Commits
-------

9774f4f deprecated Twig_ExtensionInterface::initRuntime()

CHANGELOG

@@ -1,5 +1,6 @@
 * 1.23.0 (2015-XX-XX)
 
+ * deprecated Twig_ExtensionInterface::initRuntime() (added Twig_Extension_InitRuntimeInterface for BC)
  * deprecated Twig_Environment::computeAlternatives()
 
 * 1.22.3 (2015-10-13)

doc/advanced.rst

@@ -553,6 +553,8 @@ An extension is a class that implements the following interface::
          * This is where you can load some file that contains filter functions for instance.
          *
          * @param Twig_Environment $environment The current Twig_Environment instance
+         *
+         * @deprecated since 1.23 (to be removed in 2.0)
          */
         function initRuntime(Twig_Environment $environment);
 

doc/deprecated.rst

@@ -26,6 +26,13 @@ Extensions
 * As of Twig 1.x, the ability to remove an extension is deprecated and the
   ``Twig_Environment::removeExtension()`` method will be removed in 2.0.
 
+* As of Twig 1.23, the ``Twig_ExtensionInterface::initRuntime()`` method is
+  deprecated. You have two options to avoid the deprecation notice: if you
+  implement this method to store the environment for your custom filters,
+  functions, or tests, use the ``needs_environment`` option instead; if you
+  have more complex needs, explicitly implement
+  ``Twig_Extension_InitRuntimeInterface`` (not recommended).
+
 PEAR
 ----
 

lib/Twig/Environment.php

@@ -725,12 +725,22 @@ public function getCharset()
 
     /**
      * Initializes the runtime environment.
+     *
+     * @deprecated since 1.23 (to be removed in 2.0)
      */
     public function initRuntime()
     {
         $this->runtimeInitialized = true;
 
         foreach ($this->getExtensions() as $extension) {
+            if (!$extension instanceof Twig_Extension_InitRuntimeInterface) {
+                $m = new ReflectionMethod($extension, 'initRuntime');
+
+                if ('Twig_Extension' !== $m->getDeclaringClass()->getName()) {
+                    @trigger_error(sprintf('Defining the initRuntime() method in an extension is deprecated. Use the `needs_environment` option to get the Twig_Environment instance in filters, functions, or tests; or explicitly implement Twig_Extension_InitRuntimeInterface if needed (not recommended).', $name), E_USER_DEPRECATED);
+                }
+            }
+
             $extension->initRuntime($this);
         }
     }

lib/Twig/Extension.php

@@ -12,6 +12,8 @@ abstract class Twig_Extension implements Twig_ExtensionInterface
 {
     /**
      * {@inheritdoc}
+     *
+     * @deprecated since 1.23 (to be removed in 2.0)
      */
     public function initRuntime(Twig_Environment $environment)
     {

lib/Twig/Extension/InitRuntimeInterface.php

@@ -0,0 +1,22 @@
+<?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.
+ */
+
+/**
+ * Declares the deprecated Twig_Extension::initRuntime() method.
+ *
+ * Explicitely implement this interface if you really need to implement the
+ * deprecated initRuntime() method in your extensions.
+ *
+ * @author Fabien Potencier <fabien@symfony.com>
+ */
+interface Twig_Extension_InitRuntimeInterface
+{
+}

lib/Twig/ExtensionInterface.php

@@ -22,6 +22,8 @@ interface Twig_ExtensionInterface
      * This is where you can load some file that contains filter functions for instance.
      *
      * @param Twig_Environment $environment The current Twig_Environment instance
+     *
+     * @deprecated since 1.23 (to be removed in 2.0)
      */
     public function initRuntime(Twig_Environment $environment);
 

test/Twig/Tests/EnvironmentTest.php

@@ -308,6 +308,40 @@ public function testAddMockExtension()
         $this->assertTrue($twig->isTemplateFresh('page', time()));
     }
 
+    public function testInitRuntimeWithAnExtensionUsingInitRuntimeNoDeprecation()
+    {
+        $twig = new Twig_Environment($this->getMock('Twig_LoaderInterface'));
+        $twig->addExtension(new Twig_Tests_EnvironmentTest_ExtensionWithoutDeprecationInitRuntime());
+
+        $twig->initRuntime();
+    }
+
+    /**
+     * @requires PHP 5.3
+     */
+    public function testInitRuntimeWithAnExtensionUsingInitRuntimeDeprecation()
+    {
+        $twig = new Twig_Environment($this->getMock('Twig_LoaderInterface'));
+        $twig->addExtension(new Twig_Tests_EnvironmentTest_ExtensionWithDeprecationInitRuntime());
+
+        $this->deprecations = array();
+        set_error_handler(array($this, 'handleError'));
+
+        $twig->initRuntime();
+
+        $this->assertCount(1, $this->deprecations);
+        $this->assertContains('Defining the initRuntime() method in an extension is deprecated.', $this->deprecations[0]);
+
+        restore_error_handler();
+    }
+
+    public function handleError($type, $msg)
+    {
+        if (E_USER_DEPRECATED === $type) {
+            $this->deprecations[] = $msg;
+        }
+    }
+
     protected function getMockLoader($templateName, $templateContent)
     {
         $loader = $this->getMock('Twig_LoaderInterface');
@@ -411,3 +445,27 @@ public function getPriority()
         return 0;
     }
 }
+
+class Twig_Tests_EnvironmentTest_ExtensionWithDeprecationInitRuntime extends Twig_Extension
+{
+    public function initRuntime(Twig_Environment $env)
+    {
+    }
+
+    public function getName()
+    {
+        return 'with_deprecation';
+    }
+}
+
+class Twig_Tests_EnvironmentTest_ExtensionWithoutDeprecationInitRuntime extends Twig_Extension implements Twig_Extension_InitRuntimeInterface
+{
+    public function initRuntime(Twig_Environment $env)
+    {
+    }
+
+    public function getName()
+    {
+        return 'without_deprecation';
+    }
+}