8000 feature #35778 [DI] Improve the deprecation features by handling pack… · symfony/symfony@c8f4d16 · GitHub
[go: up one dir, main page]
Skip to content

Commit c8f4d16

Browse files
nicolas-grekasnicolas-grekas
committed
feature #35778 [DI] Improve the deprecation features by handling package and version (atailouloute)
This PR was merged into the 5.1-dev branch. Discussion ---------- [DI] Improve the deprecation features by handling package and version | Q | A | ------------- | --- | Branch? | master | Bug fix? | no | New feature? | yes | Deprecations? | yes | Tickets | | License | MIT | Doc PR | TODO Improve the deprecation feature of the Dependency Injection component, by handling the `package` + `since_version` Before ```yaml services: LegacyService: deprecated: 'The %service_id% is deprecated, use NewService instead' ``` now: ```yaml services: LegacyService: deprecated: message: 'The %service_id% is deprecated, use NewService instead' package: 'my/package' since_version: '1.2' ``` TODO: - [x] update UPGRADE Commits ------- f10413c [DependencyInjection] improve the deprecation features by handling package+version info
2 parents 2130465 + f10413c commit c8f4d16

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

45 files changed

+467
-110
lines changed

‎UPGRADE-5.1.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,13 @@ Console
66

77
* `Command::setHidden()` is final since Symfony 5.1
88

9+
DependencyInjection
10+
-------------------
11+
12+
* The signature of method `Definition::setDeprecated()` has been updated to `Definition::setDeprecation(string $package, string $version, string $message)`.
13+
* The signature of method `Alias::setDeprecated()` has been updated to `Alias::setDeprecation(string $package, string $version, string $message)`.
14+
* The signature of method `DeprecateTrait::deprecate()` has been updated to `DeprecateTrait::deprecation(string $package, string $version, string $message)`.
15+
916
Dotenv
1017
------
1118

‎UPGRADE-6.0.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,13 @@ Console
66

77
* `Command::setHidden()` has a default value (`true`) for `$hidden` parameter
88

9+
DependencyInjection
10+
-------------------
11+
12+
* The signature of method `Definition::setDeprecated()` has been updated to `Definition::setDeprecation(string $package, string $version, string $message)`.
13+
* The signature of method `Alias::setDeprecated()` has been updated to `Alias::setDeprecation(string $package, string $version, string $message)`.
14+
* The signature of method `DeprecateTrait::deprecate()` has been updated to `DeprecateTrait::deprecation(string $package, string $version, string $message)`.
15+
916
Dotenv
1017
------
1118

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

Lines changed: 48 additions & 14 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
/**
@@ -85,40 +83,76 @@ public function isPrivate()
8583
* Whether this alias is deprecated, that means it should not be referenced
8684
* anymore.
8785
*
88-
* @param bool $status Whether this alias is deprecated, defaults to true
89-
* @param string $template Optional template message to use if the alias is deprecated
86+
* @param string $package The name of the composer package that is triggering the deprecation
87+
* @param string $version The version of the package that introduced the deprecation
88+
* @param string $message The deprecation message to use
9089
*
9190
* @return $this
9291
*
9392
* @throws InvalidArgumentException when the message template is invalid
9493
*/
95-
public function setDeprecated(bool $status = true, string $template = null)
94+
public function setDeprecated(/* string $package, string $version, string $message */)
9695
{
97-
if (null !== $template) {
98-
if (preg_match('#[\r\n]|\*/#', $template)) {
96+
$args = \func_get_args();
97+
98+
if (\func_num_args() < 3) {
99+
trigger_deprecation('symfony/dependency-injection', '5.1', 'The signature of method "%s()" requires 3 arguments: "string $package, string $version, string $message", not defining them is deprecated.', __METHOD__);
100+
101+
$status = $args[0] ?? true;
102+
103+
if (!$status) {
104+
trigger_deprecation('symfony/dependency-injection', '5.1', 'Passing a null message to un-deprecate a node is deprecated.');
105+
}
106+
107+
$message = (string) ($args[1] ?? null);
108+
$package = $version = '';
109+
} else {
110+
$status = true;
111+
$package = (string) $args[0];
112+
$version = (string) $args[1];
113+
$message = (string) $args[2];
114+
}
115+
116+
if ('' !== $message) {
117+
if (preg_match('#[\r\n]|\*/#', $message)) {
99118
throw new InvalidArgumentException('Invalid characters found in deprecation template.');
100119
}
101120

102-
if (false === strpos($template, '%alias_id%')) {
121+
if (false === strpos($message, '%alias_id%')) {
103122
throw new InvalidArgumentException('The deprecation template must contain the "%alias_id%" placeholder.');
104123
}
105-
106-
$this->deprecationTemplate = $template;
107124
}
108125

109-
$this->deprecated = $status;
126+
$this->deprecation = $status ? ['package' => $package, 'version' => $version, 'message' => $message ?: self::$defaultDeprecationTemplate] : [];
110127

111128
return $this;
112129
}
113130

114131
public function isDeprecated(): bool
115132
{
116-
return $this->deprecated;
133+
return (bool) $this->deprecation;
117134
}
118135

136+
/**
137+
* @deprecated since Symfony 5.1, use "getDeprecation()" instead.
138+
*/
119139
public function getDeprecationMessage(string $id): string
120140
{
121-
return str_replace('%alias_id%', $id, $this->deprecationTemplate ?: self::$defaultDeprecationTemplate);
141+
trigger_deprecation('symfony/dependency-injection', '5.1', 'The "%s()" method is deprecated, use "getDeprecation()" instead.', __METHOD__);
142+
143+
return $this->getDeprecation($id)['message'];
144+
}
145+
146+
/**
147+
* @param string $id Service id relying on this definition
148+
*/
149+
public function getDeprecation(string $id): array
150+
{
151+
return [
152+
'package' => $this->deprecation['package'],
153+
'version' => $this->deprecation['version'],
154+
'message' => str_replace('%alias_id%', $id, $this->deprecation['message']),
155+
];
122156
}
123157

124158
/**

‎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+
* updated the signature of method `Definition::setDeprecated()` to `Definition::setDeprecation(string $package, string $version, string $message)`
11+
* updated the signature of method `Alias::setDeprecated()` to `Alias::setDeprecation(string $package, string $version, string $message)`
12+
* updated the signature of method `DeprecateTrait::deprecate()` to `DeprecateTrait::deprecation(string $package, string $version, string $message)`
1013

1114
5.0.0
1215
-----

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

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,8 @@ 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+
$deprecation = $parentDef->getDeprecation('%service_id%');
106+
$def->setDeprecated($deprecation['package'], $deprecation['version'], $deprecation['message']);
106107
}
107108
$def->setFactory($parentDef->getFactory());
108109
$def->setConfigurator($parentDef->getConfigurator());
@@ -137,7 +138,12 @@ private function doResolveDefinition(ChildDefinition $definition): Definition
137138
$def->setLazy($definition->isLazy());
138139
}
139140
if (isset($changes['deprecated'])) {
140-
$def->setDeprecated($definition->isDeprecated(), $definition->getDeprecationMessage('%service_id%'));
141+
if ($definition->isDeprecated()) {
142+
$deprecation = $definition->getDeprecation('%service_id%');
143+
$def->setDeprecated($deprecation['package'], $deprecation['version'], $deprecation['message']);
144+
} else {
145+
$def->setDeprecated(false);
146+
}
141147
}
142148
if (isset($changes['autowired'])) {
143149
$def->setAutowired($definition->isAutowired());

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

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -62,7 +62,8 @@ 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+
trigger_deprecation($deprecation['package'], $deprecation['version'], rtrim($deprecation['message'], '. ').'. It is being referenced by the "%s" '.($container->hasDefinition($this->currentId) ? 'service.' : 'alias.'), rtrim($deprecation['message'], '. '), $this->currentId);
6667
}
6768

6869
$seen = [];

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

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -568,7 +568,8 @@ 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+
$deprecation = $alias->getDeprecation($id);
572+
trigger_deprecation($deprecation['package'], $deprecation['version'], $deprecation['message']);
572573
}
573574

574575
return $this->doGet((string) $alias, $invalidBehavior, $inlineServices, $isConstructorArgument);
@@ -1037,7 +1038,8 @@ private function createService(Definition $definition, array &$inlineServices, b
10371038
}
10381039

10391040
if ($definition->isDeprecated()) {
1040-
trigger_deprecation('', '', $definition->getDeprecationMessage($id));
1041+
$deprecation = $definition->getDeprecation($id);
1042+
trigger_deprecation($deprecation['package'], $deprecation['version'], $deprecation['message']);
10411043
}
10421044

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

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

Lines changed: 47 additions & 13 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 = [];
@@ -705,29 +704,48 @@ public function isAbstract()
705704
* Whether this definition is deprecated, that means it should not be called
706705
* anymore.
707706
*
708-
* @param string $template Template message to use if the definition is deprecated
707+
* @param string $package The name of the composer package that is triggering the deprecation
708+
* @param string $version The version of the package that introduced the deprecation
709+
* @param string $message The deprecation message to use
709710
*
710711
* @return $this
711712
*
712713
* @throws InvalidArgumentException when the message template is invalid
713714
*/
714-
public function setDeprecated(bool $status = true, string $template = null)
715+
public function setDeprecated(/* string $package, string $version, string $message */)
715716
{
716-
if (null !== $template) {
717-
if (preg_match('#[\r\n]|\*/#', $template)) {
717+
$args = \func_get_args();
718+
719+
if (\func_num_args() < 3) {
720+
trigger_deprecation('symfony/dependency-injection', '5.1', 'The signature of method "%s()" requires 3 arguments: "string $package, string $version, string $message", not defining them is deprecated.', __METHOD__);
721+
722+
$status = $args[0] ?? true;
723+
724+
if (!$status) {
725+
trigger_deprecation('symfony/dependency-injection', '5.1', 'Passing a null message to un-deprecate a node is deprecated.');
726+
}
727+
728+
$message = (string) ($args[1] ?? null);
729+
$package = $version = '';
730+
} else {
731+
$status = true;
732+
$package = (string) $args[0];
733+
$version = (string) $args[1];
734+
$message = (string) $args[2];
735+
}
736+
737+
if ('' !== $message) {
738+
if (preg_match('#[\r\n]|\*/#', $message)) {
718739
throw new InvalidArgumentException('Invalid characters found in deprecation template.');
719740
}
720741

721-
if (false === strpos($template, '%service_id%')) {
742+
if (false === strpos($message, '%service_id%')) {
722743
throw new InvalidArgumentException('The deprecation template must contain the "%service_id%" placeholder.');
723744
}
724-
725-
$this->deprecationTemplate = $template;
726745
}
727746

728747
$this->changes['deprecated'] = true;
729-
730-
$this->deprecated = $status;
748+
$this->deprecation = $status ? ['package' => $package, 'version' => $version, 'message' => $message ?: self::$defaultDeprecationTemplate] : [];
731749

732750
return $this;
733751
}
@@ -740,19 +758,35 @@ public function setDeprecated(bool $status = true, string $template = null)
740758
*/
741759
public function isDeprecated()
742760
{
743-
return $this->deprecated;
761+
return (bool) $this->deprecation;
744762
}
745763

746764
/**
747765
* Message to use if this definition is deprecated.
748766
*
767+
* @deprecated since Symfony 5.1, use "getDeprecation()" instead.
768+
*
749769
* @param string $id Service id relying on this definition
750770
*
751771
* @return string
752772
*/
753773
public function getDeprecationMessage(string $id)
754774
{
755-
return str_replace('%service_id%', $id, $this->deprecationTemplate ?: self::$defaultDeprecationTemplate);
775+
trigger_deprecation('symfony/dependency-injection', '5.1', 'The "%s()" method is deprecated, use "getDeprecation()" instead.', __METHOD__);
776+
777+
return $this->getDeprecation($id)['message'];
778+
}
779+
780+
/**
781+
* @param string $id Service id relying on this definition
782+
*/
783+
public function getDeprecation(string $id): array
784+
{
785+
return [
786+
'package' => $this->deprecation['package'],
787+
'version' => $this->deprecation['version'],
788+
'message' => str_replace('%service_id%', $id, $this->deprecation['message']),
789+
];
756790
}
757791

758792
/**

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

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

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

792793
$return = str_replace("\n * \n", "\n *\n", implode("\n * ", $return));
@@ -835,7 +836,8 @@ protected function {$methodName}($lazyInitialization)
835836
$this->inlinedDefinitions = $this->getDefinitionsFromArguments([$definition], null, $this->serviceCalls);
836837

837838
if ($definition->isDeprecated()) {
838-
$code .= sprintf(" trigger_deprecation('', '', %s);\n\n", $this->export($definition->getDeprecationMessage($id)));
839+
$deprecation = $definition->getDeprecation($id);
840+
$code .= sprintf(" trigger_deprecation(%s, %s, %s);\n\n", $this->export($deprecation['package']), $this->export($deprecation['version']), $this->export($ 10000 deprecation['message']));
839841
} else {
840842
foreach ($this->inlinedDefinitions as $def) {
841843
foreach ($this->getClasses($def) as $class) {
@@ -1341,7 +1343,10 @@ private function addDeprecatedAliases(): string
13411343
$id = (string) $definition;
13421344
$methodNameAlias = $this->generateMethodName($alias);
13431345
$idExported = $this->export($id);
1344-
$messageExported = $this->export($definition->getDeprecationMessage($alias));
1346+
$deprecation = $definition->getDeprecation($alias);
1347+
$packageExported = $this->export($deprecation['package']);
1348+
$versionExported = $this->export($deprecation['version']);
1349+
$messageExported = $this->export($deprecation['message']);
13451350
$code .= <<<EOF
13461351
13471352
/*{$this->docStar}
@@ -1351,7 +1356,7 @@ private function addDeprecatedAliases(): string
13511356
*/
13521357
protected function {$methodNameAlias}()
13531358
{
1354-
trigger_deprecation('', '', $messageExported);
1359+
trigger_deprecation($packageExported, $versionExported, $messageExported);
13551360
13561361
return \$this->get($idExported);
13571362
}

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

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

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

185188
$service->appendChild($deprecated);
186189
}
@@ -225,8 +228,11 @@ private function addServiceAlias(string $alias, Alias $id, \DOMElement $parent)
225228
}
226229

227230
if ($id->isDeprecated()) {
231+
$deprecation = $id->getDeprecation('%alias_id%');
228232
$deprecated = $this->document->createElement('deprecated');
229-
$deprecated->appendChild($this->document->createTextNode($id->getDeprecationMessage('%alias_id%')));
233+
$deprecated->setAttribute('message', $deprecation['message']);
234+
$deprecated->setAttribute('package', $deprecation['package']);
235+
$deprecated->setAttribute('version', $deprecation['version']);
230236

231237
$service->appendChild($deprecated);
232238
}

0 commit comments

Comments
 (0)
0