feature #2148 deprecated Twig_ExtensionInterface::getName() (fabpot)

This PR was merged into the 1.x branch.

Discussion
----------

deprecated Twig_ExtensionInterface::getName()

see #2147

Commits
-------

71f03df deprecated Twig_ExtensionInterface::getName()

CHANGELOG

@@ -1,6 +1,6 @@
-* 1.25.1 (2016-XX-XX)
+* 1.26.0 (2016-XX-XX)
 
- * n/a
+ * deprecated Twig_ExtensionInterface::getName()
 
 * 1.25.0 (2016-09-21)
 

composer.json

@@ -40,7 +40,7 @@
     },
     "extra": {
         "branch-alias": {
-            "dev-master": "1.25-dev"
+            "dev-master": "1.26-dev"
         }
     }
 }

doc/advanced.rst

@@ -613,32 +613,27 @@ An extension is a class that implements the following interface::
          * Returns the name of the extension.
          *
          * @return string The extension name
+         *
+         * @deprecated since 1.26 (to be removed in 2.0), not used anymore internally
          */
         function getName();
     }
 
-To keep your extension class clean and lean, it can inherit from the built-in
-``Twig_Extension`` class instead of implementing the whole interface. That
-way, you just need to implement the ``getName()`` method as the
-``Twig_Extension`` provides empty implementations for all other methods.
-
-The ``getName()`` method must return a unique identifier for your extension.
-
-Now, with this information in mind, let's create the most basic extension
-possible::
+To keep your extension class clean and lean, inherit from the built-in
+``Twig_Extension`` class instead of implementing the interface as it provides
+empty implementations for all methods:
 
     class Project_Twig_Extension extends Twig_Extension
     {
-        public function getName()
-        {
-            return 'project';
-        }
     }
 
+Of course, this extension does nothing for now. We will customize it in the
+next sections.
+
 .. note::
 
-    Of course, this extension does nothing for now. We will customize it in
-    the next sections.
+    Prior to Twig 1.26, you must implement the ``getName()`` method which must
+    return a unique identifier for the extension.
 
 Twig does not care where you save your extension on the filesystem, as all
 extensions must be registered explicitly to be available in your templates.
@@ -790,11 +785,6 @@ possible** (order matters)::
         {
             // do something different from the built-in date filter
         }
-
-        public function getName()
-        {
-            return 'project';
-        }
     }
 
     $twig = new Twig_Environment($loader);

doc/deprecated.rst

@@ -37,6 +37,9 @@ Extensions
   deprecated. Implement ``Twig_Extension_GlobalsInterface`` to avoid
   deprecation notices.
 
+* As of Twig 1.26, the ``Twig_ExtensionInterface::getName()`` method is
+  deprecated and it is not used internally anymore.
+
 PEAR
 ----
 

doc/filters/date.rst

@@ -54,6 +54,9 @@ dates and the second one is the default format for date intervals:
 .. code-block:: php
 
     $twig = new Twig_Environment($loader);
+    $twig->getExtension('Twig_Extension_Core')->setDateFormat('d/m/Y', '%d days');
+
+    // before Twig 1.26
     $twig->getExtension('core')->setDateFormat('d/m/Y', '%d days');
 
 Timezone
@@ -79,6 +82,9 @@ The default timezone can also be set globally by calling ``setTimezone()``:
 .. code-block:: php
 
     $twig = new Twig_Environment($loader);
+    $twig->getExtension('Twig_Extension_Core')->setTimezone('Europe/Paris');
+
+    // before Twig 1.26
     $twig->getExtension('core')->setTimezone('Europe/Paris');
 
 Arguments

doc/filters/escape.rst

@@ -97,6 +97,9 @@ used in the ``escape`` call) and the second one must be a valid PHP callable:
 .. code-block:: php
 
     $twig = new Twig_Environment($loader);
+    $twig->getExtension('Twig_Extension_Core')->setEscaper('csv', 'csv_escaper');
+
+    // before Twig 1.26
     $twig->getExtension('core')->setEscaper('csv', 'csv_escaper');
 
 When called by Twig, the callable receives the Twig environment instance, the

doc/filters/number_format.rst

@@ -30,6 +30,9 @@ These defaults can be easily changed through the core extension:
 .. code-block:: php
 
     $twig = new Twig_Environment($loader);
+    $twig->getExtension('Twig_Extension_Core')->setNumberFormat(3, '.', ',');
+
+    // before Twig 1.26
     $twig->getExtension('core')->setNumberFormat(3, '.', ',');
 
 The defaults set for ``number_format`` can be over-ridden upon each call using the

doc/functions/date.rst

@@ -41,6 +41,9 @@ If no argument is passed, the function returns the current date:
     .. code-block:: php
 
         $twig = new Twig_Environment($loader);
+        $twig->getExtension('Twig_Extension_Core')->setTimezone('Europe/Paris');
+
+        // before Twig 1.26
         $twig->getExtension('core')->setTimezone('Europe/Paris');
 
 Arguments

ext/twig/php_twig.h

@@ -15,7 +15,7 @@
 #ifndef PHP_TWIG_H
 #define PHP_TWIG_H
 
-#define PHP_TWIG_VERSION "1.25.1-DEV"
+#define PHP_TWIG_VERSION "1.26.0-DEV"
 
 #include "php.h"
 

ext/twig/twig.c

@@ -916,8 +916,8 @@ PHP_FUNCTION(twig_template_get_attributes)
 				return true;
 			}
 
-			if ($this->env->hasExtension('sandbox')) {
-				$this->env->getExtension('sandbox')->checkPropertyAllowed($object, $item);
+			if ($this->env->hasExtension('Twig_Extension_Sandbox')) {
+				$this->env->getExtension('Twig_Extension_Sandbox')->checkPropertyAllowed($object, $item);
 			}
 
 			return $object->$item;
@@ -935,8 +935,8 @@ PHP_FUNCTION(twig_template_get_attributes)
 				efree(item);
 				RETURN_TRUE;
 			}
-			if (TWIG_CALL_SB(TWIG_PROPERTY_CHAR(template, "env" TSRMLS_CC), "hasExtension", "sandbox" TSRMLS_CC)) {
-				TWIG_CALL_ZZ(TWIG_CALL_S(TWIG_PROPERTY_CHAR(template, "env" TSRMLS_CC), "getExtension", "sandbox" TSRMLS_CC), "checkPropertyAllowed", object, zitem TSRMLS_CC);
+			if (TWIG_CALL_SB(TWIG_PROPERTY_CHAR(template, "env" TSRMLS_CC), "hasExtension", "Twig_Extension_Sandbox" TSRMLS_CC)) {
+				TWIG_CALL_ZZ(TWIG_CALL_S(TWIG_PROPERTY_CHAR(template, "env" TSRMLS_CC), "getExtension", "Twig_Extension_Sandbox" TSRMLS_CC), "checkPropertyAllowed", object, zitem TSRMLS_CC);
 			}
 			if (EG(exception)) {
 				efree(item);
@@ -1052,14 +1052,14 @@ PHP_FUNCTION(twig_template_get_attributes)
 			RETURN_TRUE;
 		}
 /*
-	if ($this->env->hasExtension('sandbox')) {
-		$this->env->getExtension('sandbox')->checkMethodAllowed($object, $method);
+	if ($this->env->hasExtension('Twig_Extension_Sandbox')) {
+		$this->env->getExtension('Twig_Extension_Sandbox')->checkMethodAllowed($object, $method);
 	}
 */
 		MAKE_STD_ZVAL(zmethod);
 		ZVAL_STRING(zmethod, method, 1);
-		if (TWIG_CALL_SB(TWIG_PROPERTY_CHAR(template, "env" TSRMLS_CC), "hasExtension", "sandbox" TSRMLS_CC)) {
-			TWIG_CALL_ZZ(TWIG_CALL_S(TWIG_PROPERTY_CHAR(template, "env" TSRMLS_CC), "getExtension", "sandbox" TSRMLS_CC), "checkMethodAllowed", object, zmethod TSRMLS_CC);
+		if (TWIG_CALL_SB(TWIG_PROPERTY_CHAR(template, "env" TSRMLS_CC), "hasExtension", "Twig_Extension_Sandbox" TSRMLS_CC)) {
+			TWIG_CALL_ZZ(TWIG_CALL_S(TWIG_PROPERTY_CHAR(template, "env" TSRMLS_CC), "getExtension", "Twig_Extension_Sandbox" TSRMLS_CC), "checkMethodAllowed", object, zmethod TSRMLS_CC);
 		}
 		zval_ptr_dtor(&zmethod);
 		if (EG(exception)) {

lib/Twig/Environment.php

@@ -16,7 +16,7 @@
  */
 class Twig_Environment
 {
-    const VERSION = '1.25.1-DEV';
+    const VERSION = '1.26.0-DEV';
 
     protected $charset;
     protected $loader;
@@ -49,6 +49,7 @@ class Twig_Environment
     private $bcWriteCacheFile = false;
     private $bcGetCacheFilename = false;
     private $lastModifiedExtension = 0;
+    private $legacyExtensionNames = array();
 
     /**
      * Constructor.
@@ -771,29 +772,41 @@ public function initRuntime()
     /**
      * Returns true if the given extension is registered.
      *
-     * @param string $name The extension name
+     * @param string $class The extension class name
      *
      * @return bool Whether the extension is registered or not
      */
-    public function hasExtension($name)
+    public function hasExtension($class)
     {
-        return isset($this->extensions[$name]);
+        if (isset($this->legacyExtensionNames[$class])) {
+            $class = $this->legacyExtensionNames[$class];
+            @trigger_error(sprintf('Referencing the "%s" extension by its name (defined by getName()) is deprecated since 1.26 and will be removed in Twig 2.0. Use the Fully Qualified Extension Class Name instead.', $class), E_USER_DEPRECATED);
+        }
+
+        return isset($this->extensions[ltrim($class, '\\')]);
     }
 
     /**
-     * Gets an extension by name.
+     * Gets an extension by class name.
      *
-     * @param string $name The extension name
+     * @param string $class The extension class name
      *
      * @return Twig_ExtensionInterface A Twig_ExtensionInterface instance
      */
-    public function getExtension($name)
+    public function getExtension($class)
     {
-        if (!isset($this->extensions[$name])) {
-            throw new Twig_Error_Runtime(sprintf('The "%s" extension is not enabled.', $name));
+        if (isset($this->legacyExtensionNames[$class])) {
+            $class = $this->legacyExtensionNames[$class];
+            @trigger_error(sprintf('Referencing the "%s" extension by its name (defined by getName()) is deprecated since 1.26 and will be removed in Twig 2.0. Use the Fully Qualified Extension Class Name instead.', $class), E_USER_DEPRECATED);
+        }
+
+        $class = ltrim($class, '\\');
+
+        if (!isset($this->extensions[$class])) {
+            throw new Twig_Error_Runtime(sprintf('The "%s" extension is not enabled.', $class));
         }
 
-        return $this->extensions[$name];
+        return $this->extensions[$class];
     }
 
     /**
@@ -803,19 +816,25 @@ public function getExtension($name)
      */
     public function addExtension(Twig_ExtensionInterface $extension)
     {
-        $name = $extension->getName();
+        $class = get_class($extension);
 
         if ($this->extensionInitialized) {
-            throw new LogicException(sprintf('Unable to register extension "%s" as extensions have already been initialized.', $name));
+            throw new LogicException(sprintf('Unable to register extension "%s" as extensions have already been initialized.', $class));
         }
 
-        if (isset($this->extensions[$name])) {
-            @trigger_error(sprintf('The possibility to register the same extension twice ("%s") is deprecated since version 1.23 and will be removed in Twig 2.0. Use proper PHP inheritance instead.', $name), E_USER_DEPRECATED);
+        $m = new ReflectionMethod($extension, 'getName');
+        $legacyName = 'Twig_Extension' !== $m->getDeclaringClass()->getName() ? $extension->getName() : null;
+
+        if (isset($this->extensions[$class]) || (null !== $legacyName && isset($this->legacyExtensionNames[$legacyName]))) {
+            unset($this->extensions[$this->legacyExtensionNames[$legacyName]], $this->legacyExtensionNames[$legacyName]);
+            @trigger_error(sprintf('The possibility to register the same extension twice ("%s") is deprecated since version 1.23 and will be removed in Twig 2.0. Use proper PHP inheritance instead.', $class), E_USER_DEPRECATED);
         }
 
         $this->lastModifiedExtension = 0;
-
-        $this->extensions[$name] = $extension;
+        if ($legacyName !== $class) {
+            $this->legacyExtensionNames[$legacyName] = $class;
+        }
+        $this->extensions[$class] = $extension;
     }
 
     /**
@@ -831,11 +850,16 @@ public function removeExtension($name)
     {
         @trigger_error(sprintf('The %s method is deprecated since version 1.12 and will be removed in Twig 2.0.', __METHOD__), E_USER_DEPRECATED);
 
+        if (isset($this->legacyExtensionNames[$name])) {
+            $name = $this->legacyExtensionNames[$name];
+            @trigger_error(sprintf('Referencing the "%s" extension by its name (defined by getName()) is deprecated since 1.26 and will be removed in Twig 2.0. Use the Fully Qualified Extension Class Name instead.', $name), E_USER_DEPRECATED);
+        }
+
         if ($this->extensionInitialized) {
             throw new LogicException(sprintf('Unable to remove extension "%s" as extensions have already been initialized.', $name));
         }
 
-        unset($this->extensions[$name]);
+        unset($this->extensions[ltrim($name, '\\')]);
     }
 
     /**
@@ -853,7 +877,7 @@ public function setExtensions(array $extensions)
     /**
      * Returns all registered extensions.
      *
-     * @return array An array of extensions
+     * @return Twig_ExtensionInterface[] An array of extensions (keys are for internal usage only and should not be relied on)
      */
     public function getExtensions()
     {

lib/Twig/Extension.php

@@ -76,4 +76,14 @@ public function getGlobals()
     {
         return array();
     }
+
+    /**
+     * {@inheritdoc}
+     *
+     * @deprecated since 1.26 (to be removed in 2.0), not used anymore internally
+     */
+    public function getName()
+    {
+        return get_class($this);
+    }
 }

lib/Twig/Extension/Core.php

@@ -433,7 +433,7 @@ function twig_random(Twig_Environment $env, $values = null)
 function twig_date_format_filter(Twig_Environment $env, $date, $format = null, $timezone = null)
 {
     if (null === $format) {
-        $formats = $env->getExtension('core')->getDateFormat();
+        $formats = $env->getExtension('Twig_Extension_Core')->getDateFormat();
         $format = $date instanceof DateInterval ? $formats[1] : $formats[0];
     }
 
@@ -488,7 +488,7 @@ function twig_date_converter(Twig_Environment $env, $date = null, $timezone = nu
     // determine the timezone
     if (false !== $timezone) {
         if (null === $timezone) {
-            $timezone = $env->getExtension('core')->getTimezone();
+            $timezone = $env->getExtension('Twig_Extension_Core')->getTimezone();
         } elseif (!$timezone instanceof DateTimeZone) {
             $timezone = new DateTimeZone($timezone);
         }
@@ -509,14 +509,14 @@ function twig_date_converter(Twig_Environment $env, $date = null, $timezone = nu
     }
 
     if (null === $date || 'now' === $date) {
-        return new DateTime($date, false !== $timezone ? $timezone : $env->getExtension('core')->getTimezone());
+        return new DateTime($date, false !== $timezone ? $timezone : $env->getExtension('Twig_Extension_Core')->getTimezone());
     }
 
     $asString = (string) $date;
     if (ctype_digit($asString) || (!empty($asString) && '-' === $asString[0] && ctype_digit(substr($asString, 1)))) {
         $date = new DateTime('@'.$date);
     } else {
-        $date = new DateTime($date, $env->getExtension('core')->getTimezone());
+        $date = new DateTime($date, $env->getExtension('Twig_Extension_Core')->getTimezone());
     }
 
     if (false !== $timezone) {
@@ -589,7 +589,7 @@ function twig_round($value, $precision = 0, $method = 'common')
  */
 function twig_number_format_filter(Twig_Environment $env, $number, $decimal = null, $decimalPoint = null, $thousandSep = null)
 {
-    $defaults = $env->getExtension('core')->getNumberFormat();
+    $defaults = $env->getExtension('Twig_Extension_Core')->getNumberFormat();
     if (null === $decimal) {
         $decimal = $defaults[0];
     }
@@ -1115,7 +1115,7 @@ function twig_escape_filter(Twig_Environment $env, $string, $strategy = 'html',
             static $escapers;
 
             if (null === $escapers) {
-                $escapers = $env->getExtension('core')->getEscapers();
+                $escapers = $env->getExtension('Twig_Extension_Core')->getEscapers();
             }
 
             if (isset($escapers[$strategy])) {
@@ -1451,8 +1451,8 @@ function twig_include(Twig_Environment $env, $context, $template, $variables = a
         $variables = array_merge($context, $variables);
     }
 
-    if ($isSandboxed = $sandboxed && $env->hasExtension('sandbox')) {
-        $sandbox = $env->getExtension('sandbox');
+    if ($isSandboxed = $sandboxed && $env->hasExtension('Twig_Extension_Sandbox')) {
+        $sandbox = $env->getExtension('Twig_Extension_Sandbox');
         if (!$alreadySandboxed = $sandbox->isSandboxed()) {
             $sandbox->enableSandbox();
         }

lib/Twig/ExtensionInterface.php

@@ -82,6 +82,8 @@ public function getGlobals();
      * Returns the name of the extension.
      *
      * @return string The extension name
+     *
+     * @deprecated since 1.26 (to be removed in 2.0), not used anymore internally
      */
     public function getName();
 }