8000 [DependencyInjection] improve the deprecation features by handling pa… · symfony/symfony@810d6bf · GitHub
[go: up one dir, main page]
Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Appearance settings

Commit 810d6bf

Browse files
atailoulouteatailouloute
committed
[DependencyInjection] improve the deprecation features by handling package+version info
1 parent cde44fc commit 810d6bf

33 files changed

+308
-67
lines changed

‎src/Symfony/Component/DependencyInjection/Alias.php‎

Lines changed: 42 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -18,8 +18,7 @@ class Alias
1818
private $id;
1919
private $public;
2020
private $private;
21-
private $deprecated;
22-
private $deprecationTemplate;
21+
private $deprecation = [];
2322

2423
private static $defaultDeprecationTemplate = 'The "%alias_id%" service alias is deprecated. You should stop using it, as it will be removed in the future.';
2524

@@ -28,7 +27,6 @@ public function __construct(string $id, bool $public = true)
2827
$this->id = $id;
2928
$this->public = $public;
3029
$this->private = 2 > \func_num_args();
31-
$this->deprecated = false;
3230
}
3331

3432
/**
@@ -94,6 +92,8 @@ public function isPrivate()
9492
*/
9593
public function setDeprecated(bool $status = true, string $template = null)
9694
{
95+
trigger_deprecation('symfony/dependency-injection', '5.1', 'The "%s()" method is deprecated, use "deprecation()" instead.', __METHOD__);
96+
9797
if (null !== $template) {
9898
if (preg_match('#[\r\n]|\*/#', $template)) {
9999
throw new InvalidArgumentException('Invalid characters found in deprecation template.');
@@ -102,23 +102,58 @@ public function setDeprecated(bool $status = true, string $template = null)
102102
if (false === strpos($template, '%alias_id%')) {
103103
throw new InvalidArgumentException('The deprecation template must contain the "%alias_id%" placeholder.');
104104
}
105+
}
106+
107+
$this->deprecation = $status ? ['package' => '', 'version' => '', 'message' => $template ?: self::$defaultDeprecationTemplate] : [];
105108

106-
$this->deprecationTemplate = $template;
109+
return $this;
110+
}
111+
112+
/**
113+
* @param string $package The name of the composer package that is triggering the deprecation
114+
* @param string $version The version of the package that introduced the deprecation
115+
* @param string $message The deprecation message to use
116+
*
117+
* @return $this
118+
*/
119+
public function setDeprecation(string $package, string $version, string $message)
120+
{
121+
$message = $message ?: self::$defaultDeprecationTemplate;
122+
123+
if (preg_match('#[\r\n]|\*/#', $message)) {
124+
throw new InvalidArgumentException('Invalid characters found in deprecation template.');
125+
}
126+
127+
if (false === strpos($message, '%alias_id%')) {
128+
throw new InvalidArgumentException('The deprecation template must contain the "%alias_id%" placeholder.');
107129
}
108130

109-
$this->deprecated = $status;
131+
$this->deprecation = [
132+
'package' => $package,
133+
'version' => $version,
134+
'message' => $message,
135+
];
110136

111137
return $this;
112138
}
113139

114140
public function isDeprecated(): bool
115141
{
116-
return $this->deprecated;
142+
return (bool) $this->deprecation;
117143
}
118144

119145
public function getDeprecationMessage(string $id): string
120146
{
121-
return str_replace('%alias_id%', $id, $this->deprecationTemplate ?: self::$defaultDeprecationTemplate);
147+
return $this->getDeprecation($id)['message'];
148+
}
149+
150+
public function getDeprecation(string $id): array
151+
{
152+
return [
153+
'package' => $this->deprecation['package'] ?? '',
154+
'version' => $this->deprecation['version'] ?? '',
155+
'message' => str_replace('%alias_id%', $id, $this->deprecation['message'] ?? self::$defaultDeprecationTemplate),
156+
];
122157
}
123158

124159
/**

‎src/Symfony/Component/DependencyInjection/CHANGELOG.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,9 @@ CHANGELOG
77
* added support to autowire public typed properties in php 7.4
88
* added support for defining method calls, a configurator, and property setters in `InlineService 6284 Configurator`
99
* added possibility to define abstract service arguments
10+
* deprecated `Definition::setDeprecated()`, use `Definition::setDeprecation()` instead
11+
* deprecated `Alias::setDeprecated()`, use `Alias::setDeprecation()` instead
12+
* deprecated `DeprecateTrait::deprecate()`, use `DeprecateTrait::deprecation()` instead
1013

1114
5.0.0
1215
-----

‎src/Symfony/Component/DependencyInjection/Compiler/ResolveChildDefinitionsPass.php‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,7 @@ private function doResolveDefinition(ChildDefinition $definition): Definition
102102
$def->setMethodCalls($parentDef->getMethodCalls());
103103
$def->setProperties($parentDef->getProperties());
104104
if ($parentDef->isDeprecated()) {
105-
$def->setDeprecated(true, $parentDef->getDeprecationMessage('%service_id%'));
105+
$def->setDeprecation(...array_values($parentDef->getDeprecation('%service_id%')));
106106
}
107107
$def->setFactory($parentDef->getFactory());
108108
$def->setConfigurator($parentDef->getConfigurator());
@@ -137,7 +137,11 @@ private function doResolveDefinition(ChildDefinition $definition): Definition
137137
$def->setLazy($definition->isLazy());
138138
}
139139
if (isset($changes['deprecated'])) {
140-
$def->setDeprecated($definition->isDeprecated(), $definition->getDeprecationMessage('%service_id%'));
140+
if ($definition->isDeprecated()) {
141+
$def->setDeprecation(...array_values($definition->getDeprecation('%service_id%')));
142+
} else {
143+
$def->setDeprecated(false);
144+
}
141145
}
142146
if (isset($changes['autowired'])) {
143147
$def->setAutowired($definition->isAutowired());

‎src/Symfony/Component/DependencyInjection/Compiler/ResolveReferencesToAliasesPass.php‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,9 @@ private function getDefinitionId(string $id, ContainerBuilder $container): strin
6262
$alias = $container->getAlias($id);
6363

6464
if ($alias->isDeprecated()) {
65-
trigger_deprecation('', '', '%s. It is being referenced by the "%s" %s.', rtrim($alias->getDeprecationMessage($id), '. '), $this->currentId, $container->hasDefinition($this->currentId) ? 'service' : 'alias');
65+
$deprecation = $alias->getDeprecation($id);
66+
67+
trigger_deprecation($deprecation['package'], $deprecation['version'], '%s. It is being referenced by the "%s" %s.', rtrim($deprecation['message'], '. '), $this->currentId, $container->hasDefinition($this->currentId) ? 'service' : 'alias');
6668
}
6769

6870
$seen = [];

‎src/Symfony/Component/DependencyInjection/ContainerBuilder.php‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -568,7 +568,7 @@ private function doGet(string $id, int $invalidBehavior = ContainerInterface::EX
568568
$alias = $this->aliasDefinitions[$id];
569569

570570
if ($alias->isDeprecated()) {
571-
trigger_deprecation('', '', $alias->getDeprecationMessage($id));
571+
trigger_deprecation(...array_values($alias->getDeprecation($id)));
572572
}
573573

574574
return $this->doGet((string) $alias, $invalidBehavior, $inlineServices, $isConstructorArgument);
@@ -1037,7 +1037,7 @@ private function createService(Definition $definition, array &$inlineServices, b
10371037
}
10381038

10391039
if ($definition->isDeprecated()) {
1040-
trigger_deprecation('', '', $definition->getDeprecationMessage($id));
1040+
trigger_deprecation(...array_values($definition->getDeprecation($id)));
10411041
}
10421042

10431043
if ($tryProxy && $definition->isLazy() && !$tryProxy = !($proxy = $this->proxyInstantiator) || $proxy instanceof RealServiceInstantiator) {

‎src/Symfony/Component/DependencyInjection/Definition.php‎

Lines changed: 44 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -26,8 +26,7 @@ class Definition
2626
private $file;
2727
private $factory;
2828
private $shared = true;
29-
private $deprecated = false;
30-
private $deprecationTemplate;
29+
private $deprecation = [];
3130
private $properties = [];
3231
private $calls = [];
3332
private $instanceof = [];
@@ -713,6 +712,8 @@ public function isAbstract()
713712
*/
714713
public function setDeprecated(bool $status = true, string $template = null)
715714
{
715+
trigger_deprecation('symfony/dependency-injection', '5.1', 'The "%s()" method is deprecated, use "deprecation()" instead.', __METHOD__);
716+
716717
if (null !== $template) {
717718
if (preg_match('#[\r\n]|\*/#', $template)) {
718719
throw new InvalidArgumentException('Invalid characters found in deprecation template.');
@@ -721,13 +722,40 @@ public function setDeprecated(bool $status = true, string $template = null)
721722
if (false === strpos($template, '%service_id%')) {
722723
throw new InvalidArgumentException('The deprecation template must contain the "%service_id%" placeholder.');
723724
}
724-
725-
$this->deprecationTemplate = $template;
726725
}
727726

728727
$this->changes['deprecated'] = true;
729728

730-
$this->deprecated = $status;
729+
$this->deprecation = $status ? ['package' => '', 'version' => '', 'message' => $template ?: self::$defaultDeprecationTemplate] : [];
730+
731+
return $this;
732+
}
733+
734+
/**
735+
* @param string $package The name of the composer package that is triggering the deprecation
736+
* @param string $version The version of the package that introduced the deprecation
737+
* @param string|null $message The deprecation message to use, or null to use the default message
738+
*
739+
* @return $this
740+
*/
741+
public function setDeprecation(string $package, string $version, ?string $message = null)
742+
{
743+
$message = $message ?: self::$defaultDeprecationTemplate;
744+
745+
if (preg_match('#[\r\n]|\*/#', $message)) {
746+
throw new InvalidArgumentException('Invalid characters found in deprecation template.');
747+
}
748+
749+
if (false === strpos($message, '%service_id%')) {
750+
throw new InvalidArgumentException('The deprecation template must contain the "%service_id%" placeholder.');
751+
}
752+
753+
$this->changes['deprecated'] = true;
754+
$this->deprecation = [
755+
'package' => $package,
756+
'version' => $version,
757+
'message' => $message,
758+
];
731759

732760
return $this;
733761
}
@@ -740,7 +768,7 @@ public function setDeprecated(bool $status = true, string $template = null)
740768
*/
741769
public function isDeprecated()
742770
{
743-
return $this->deprecated;
771+
return (bool) $this->deprecation;
744772
}
745773

746774
/**
@@ -752,7 +780,16 @@ public function isDeprecated()
752780
*/
753781
public function getDeprecationMessage(string $id)
754782
{
755-
return str_replace('%service_id%', $id, $this->deprecationTemplate ?: self::$defaultDeprecationTemplate);
783+
return $this->getDeprecation($id)['message'];
784+
}
785+
786+
public function getDeprecation(string $id): array
787+
{
788+
return [
789+
'package' => $this->deprecation['package'] ?? '',
790+
'version' => $this->deprecation['version'] ?? '',
791+
'message' => str_replace('%service_id%', $id, $this->deprecation['message'] ?? self::$defaultDeprecationTemplate),
792+
];
756793
}
757794

758795
/**

‎src/Symfony/Component/DependencyInjection/Dumper/PhpDumper.php‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -760,7 +760,8 @@ private function addService(string $id, Definition $definition): array
760760
$return[] = '';
761761
}
762762

763-
$return[] = sprintf('@deprecated %s', $definition->getDeprecationMessage($id));
763+
$deprecation = $definition->getDeprecation($id);
764+
$return[] = sprintf('@deprecated %s', ($deprecation['package'] || $deprecation['version'] ? "Since {$deprecation['package']} {$deprecation['version']}: " : '').$deprecation['message']);
764765
}
765766

766767
$return = str_replace("\n * \n", "\n *\n", implode("\n * ", $return));
@@ -803,7 +804,8 @@ protected function {$methodName}($lazyInitialization)
803804
$this->inlinedDefinitions = $this->getDefinitionsFromArguments([$definition], null, $this->serviceCalls);
804805

805806
if ($definition->isDeprecated()) {
806-
$code .= sprintf(" trigger_deprecation('', '', %s);\n\n", $this->export($definition->getDeprecationMessage($id)));
807+
$deprecation = $definition->getDeprecation($id);
808+
$code .= sprintf(" trigger_deprecation(%s, %s, %s);\n\n", $this->export($deprecation['package']), $this->export($deprecation['version']), $this->export($deprecation['message']));
807809
}
808810

809811
if ($this->getProxyDumper()->isProxyCandidate($definition)) {
@@ -1302,7 +1304,10 @@ private function addDeprecatedAliases(): string
13021304
$id = (string) $definition;
13031305
$methodNameAlias = $this->generateMethodName($alias);
13041306
$idExported = $this->export($id);
1305-
$messageExported = $this->export($definition->getDeprecationMessage($alias));
1307+
$deprecation = $definition->getDeprecation($alias);
1308+
$packageExported = $this->export($deprecation['package']);
1309+
$versionExported = $this->export($deprecation['version']);
1310+
$messageExported = $this->export($deprecation['message']);
13061311
$code .= <<<EOF
13071312
13081313
/*{$this->docStar}
@@ -1312,7 +1317,7 @@ private function addDeprecatedAliases(): string
13121317
*/
13131318
protected function {$methodNameAlias}()
13141319
{
1315-
trigger_deprecation('', '', $messageExported);
1320+
trigger_deprecation($packageExported, $versionExported, $messageExported);
13161321
13171322
return \$this->get($idExported);
13181323
}

‎src/Symfony/Component/DependencyInjection/Dumper/XmlDumper.php‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -180,7 +180,11 @@ private function addService(Definition $definition, ?string $id, \DOMElement $pa
180180

181181
if ($definition->isDeprecated()) {
182182
$deprecated = $this->document->createElement('deprecated');
183-
$deprecated->appendChild($this->document->createTextNode($definition->getDeprecationMessage('%service_id%')));
183+
$deprecation = $definition->getDeprecation('%service_id%');
184+
185+
$deprecated->appendChild($this->document->createTextNode($definition->getDeprecation('%service_id%')['message']));
186+
$deprecated->setAttribute('package', $deprecation['package']);
187+
$deprecated->setAttribute('version', $deprecation['version']);
184188

185189
$service->appendChild($deprecated);
186190
}
@@ -225,8 +229,11 @@ private function addServiceAlias(string $alias, Alias $id, \DOMElement $parent)
225229
}
226230

227231
if ($id->isDeprecated()) {
232+
$deprecation = $id->getDeprecation('%alias_id%');
228233
$deprecated = $this->document->createElement('deprecated');
229-
$deprecated->appendChild($this->document->createTextNode($id->getDeprecationMessage('%alias_id%')));
234+
$deprecated->setAttribute('message', $deprecation['message']);
235+
$deprecated->setAttribute('package', $deprecation['package']);
236+
$deprecated->setAttribute('version', $deprecation['version']);
230237

231238
$service->appendChild($deprecated);
232239
}

‎src/Symfony/Component/DependencyInjection/Dumper/YamlDumper.php‎

Lines changed: 17 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -97,7 +97,12 @@ private function addService(string $id, Definition $definition): string
9797
}
9898

9999
if ($definition->isDeprecated()) {
100-
$code .= sprintf(" deprecated: %s\n", $this->dumper->dump($definition->getDeprecationMessage('%service_id%')));
100+
$code .= " deprecated:\n";
101+
foreach ($definition->getDeprecation('%service_id%') as $key => $value) {
102+
if ('' !== $value) {
103+
$code .= sprintf(" %s: %s\n", $key, $this->dumper->dump($value));
104+
}
105+
}
101106
}
102107

103108
if ($definition->isAutowired()) {
@@ -162,7 +167,17 @@ private function addService(string $id, Definition $definition): string
162167

163168
private function addServiceAlias(string $alias, Alias $id): string
164169
{
165-
$deprecated = $id->isDeprecated() ? sprintf(" deprecated: %s\n", $id->getDeprecationMessage('%alias_id%')) : '';
170+
$deprecated = '';
171+
172+
if ($id->isDeprecated()) {
173+
$deprecated = " deprecated:\n";
174+
175+
foreach ($id->getDeprecation('%alias_id%') as $key => $value) {
176+
if ('' !== $value) {
177+
$deprecated .= sprintf(" %s: %s\n", $key, $value);
178+
}
179+
}
180+
}
166181

167182
if ($id->isPrivate()) {
168183
return sprintf(" %s: '@%s'\n%s", $alias, $id, $deprecated);

‎src/Symfony/Component/DependencyInjection/Loader/Configurator/Traits/DeprecateTrait.php‎

Lines changed: 20 additions & 0 deletions
+
{
Original file line numberDiff line numberDiff line change
@@ -26,8 +26,28 @@ trait DeprecateTrait
2626
*/
2727
final public function deprecate(string $template = null): self
2828
{
29+
trigger_deprecation('symfony/dependency-injection', '5.1', 'The "%s()" method is deprecated, use "deprecation()" instead.', __METHOD__);
30+
2931
$this->definition->setDeprecated(true, $template);
3032

3133
return $this;
3234
}
35+
36+
/**
37+
* Mark this definition deprecated, that means it should not be called anymore.
38+
*
39+
* @param string $package The name of the composer package that is triggering the deprecation
40+
* @param string $version The version of the package that introduced the deprecation
41+
* @param string|null $message The deprecation message to use, or null to use the default message
42+
*
43+
* @return $this
44+
*
45+
* @throws InvalidArgumentException when the message template is invalid
46+
*/
47+
final public function deprecation(string $package, string $version, ?string $message = null): self
48
49+
$this->definition->setDeprecation($package, $version, $message);
50+
51+
return $this;
52+
}
3353
}

0 commit comments

Comments
 (0)
0