Added support for deprecating an alias

symfony · j92 · Oct 27, 2017 · Oct 27, 2017 · Oct 27, 2017 · Oct 27, 2017
commit 4e0383a4d15ac093f0d49f366c855b1de21c7b1d
diff --git a/src/Symfony/Component/DependencyInjection/Alias.php b/src/Symfony/Component/DependencyInjection/Alias.php
@@ -11,17 +11,24 @@
 
 namespace Symfony\Component\DependencyInjection;
 
+use Symfony\Component\DependencyInjection\Exception\InvalidArgumentException;
+
 class Alias
 {
     private $id;
     private $public;
     private $private;
+    private $deprecated;
+    private $deprecationTemplate;
+
+    private static $defaultDeprecationTemplate = 'The "%service_id%" service is deprecated. You should stop using it, as it will soon be removed.';
 
     public function __construct(string $id, bool $public = true)
     {
         $this->id = $id;
         $this->public = $public;
         $this->private = 2 > func_num_args();
+        $this->deprecated = false;
     }
 
     /**
@@ -78,6 +85,58 @@ public function isPrivate()
         return $this->private;
     }
 
+    /**
+     * Whether this alias is deprecated, that means it should not be called
+     * anymore.
+     *
+     * @param bool   $status Defaults to true
+     * @param string $template Optional template message to use if the alias is deprecated
+     *
+     * @return $this
+     *
+     * @throws InvalidArgumentException when the message template is invalid
+     */
+    public function setDeprecated($status = true, $template = null)
+    {
+        if (null !== $template) {
+            if (preg_match('#[\r\n]|\*/#', $template)) {
+                throw new InvalidArgumentException('Invalid characters found in deprecation template.');
+            }
+
+            if (false === strpos($template, '%service_id%')) {
+                throw new InvalidArgumentException('The deprecation template must contain the "%service_id%" placeholder.');
+            }
+
+            $this->deprecationTemplate = $template;
+        }
+
+        $this->deprecated = (bool) $status;
+
+        return $this;
+    }
+
+    /**
+     * Returns whether this alias is deprecated
+     *
+     * @return bool
+     */
+    public function isDeprecated()
+    {
+        return $this->deprecated;
+    }
+
+    /**
+     * Message to use if this alias is deprecated.
+     *
+     * @param string $id Service id relying on this alias
+     *
+     * @return string
+     */
+    public function getDeprecationMessage($id)
+    {
+        return str_replace('%service_id%', $id, $this->deprecationTemplate ?: self::$defaultDeprecationTemplate);
+    }
+
     /**
      * Returns the Id of this alias.
      *

diff --git a/src/Symfony/Component/DependencyInjection/Tests/AliasTest.php b/src/Symfony/Component/DependencyInjection/Tests/AliasTest.php
@@ -0,0 +1,108 @@
+<?php
+/**
+ * (c) BKV
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+declare(strict_types=1);
+
+namespace Symfony\Component\DependencyInjection\Tests;
+
+use PHPUnit\Framework\TestCase;
+use Symfony\Component\DependencyInjection\Alias;
+
+class AliasTest extends TestCase
+{
+    public function testConstructor()
+    {
+        $alias = new Alias('foo');
+
+        $this->assertEquals('foo', (string)$alias);
+        $this->assertTrue($alias->isPublic());
+    }
+
+    public function testCanConstructANonPublicAlias()
+    {
+        $alias = new Alias('foo', false);
+
+        $this->assertEquals('foo', (string)$alias);
+        $this->assertFalse($alias->isPublic());
+    }
+
+    public function testCanConstructAPrivateAlias()
+    {
+        $alias = new Alias('foo', false, false);
+
+        $this->assertEquals('foo', (string)$alias);
+        $this->assertFalse($alias->isPublic());
+        $this->assertFalse($alias->isPrivate());
+    }
+
+    public function testCanSetPublic()
+    {
+        $alias = new Alias('foo', false);
+        $alias->setPublic(true);
+
+        $this->assertTrue($alias->isPublic());
+    }
+
+    public function testCanDeprecateAnAlias()
+    {
+        $alias = new Alias('foo', false);
+        $alias->setDeprecated(true, 'The %service_id% service is deprecated.');
+
+        $this->assertTrue($alias->isDeprecated());
+    }
+
+    public function testItHasADefaultDeprecationMessage()
+    {
+        $alias = new Alias('foo', false);
+        $alias->setDeprecated();
+
+        $expectedMessage = 'The "foo" service is deprecated. You should stop using it, as it will soon be removed.';
+        $this->assertEquals($expectedMessage, $alias->getDeprecationMessage('foo'));
+    }
+
+    public function testReturnsCorrectDeprecationMessage()
+    {
+        $alias = new Alias('foo', false);
+        $alias->setDeprecated(true, 'The "%service_id%" is deprecated.');
+
+        $expectedMessage = 'The "foo" is deprecated.';
+        $this->assertEquals($expectedMessage, $alias->getDeprecationMessage('foo'));
+    }
+
+    public function testCanOverrideDeprecation()
+    {
+        $alias = new Alias('foo', false);
+        $alias->setDeprecated();
+
+        $initial = $alias->isDeprecated();
+        $alias->setDeprecated(false);
+        $final = $alias->isDeprecated();
+
+        $this->assertTrue($initial);
+        $this->assertFalse($final);
+    }
+
+    /**
+     * @dataProvider invalidDeprecationMessageProvider
+     * @expectedException \Symfony\Component\DependencyInjection\Exception\InvalidArgumentException
+     */
+    public function testCannotDeprecateWithAnInvalidTemplate(string $message)
+    {
+        $def = new Alias('foo');
+        $def->setDeprecated(true, $message);
+    }
+
+    public function invalidDeprecationMessageProvider()
+    {
+        return array(
+            "With \rs" => array("invalid \r message %service_id%"),
+            "With \ns" => array("invalid \n message %service_id%"),
+            'With */s' => array('invalid */ message %service_id%'),
+            'message not containing require %service_id% variable' => array('this is deprecated'),
+        );
+    }
+}