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

Commit f00b925

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

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 `InlineServiceConfigurator`
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%s', $deprecation['version'] ? ('Since ' . ($deprecation['package'] ? $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['versi 10000 on']);
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