Added support for deprecating aliases #24707

j92 · 2017-10-27T14:48:03Z

Q	A
Branch?	master
Bug fix?	no
New feature?	yes
BC breaks?	no
Deprecations?	no
Tests pass?	yes
Fixed tickets	#24507
License	MIT
Doc PR	symfony/symfony-docs#...

This pr adds support for deprecating aliases. I applied the same logic as for services, so we can deprecate an alias like this:

<service id="alias_for_foobar" alias="foobar">
      <deprecated />
</service>

Or we can deprecate an alias providing a deprecation template:

<service id="alias_for_foobar" alias="foobar">
     <deprecated>The "%service_id%" service is deprecated.</deprecated>
</service>

I submitted a WIP pull request to get early feedback. Please let me know if I am on the right track, so I can finish the work in the various file loaders and dumpers. Docs and changelog will be updated after the feedback.

Thanks!

greg0ire

Thanks for implementing this, great job so far!

greg0ire · 2017-10-27T17:18:49Z

src/Symfony/Component/DependencyInjection/Alias.php

+    private $deprecated;
+    private $deprecationTemplate;
+
+    private static $defaultDeprecationTemplate = 'The "%service_id%" service is deprecated. You should stop using it, as it will soon be removed.';


Maybe "service alias" instead of just "service"?

greg0ire · 2017-10-27T17:25:07Z

src/Symfony/Component/DependencyInjection/Tests/AliasTest.php

+            "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'),


nicolas-grekas · 2017-10-28T14:40:15Z

This PR needs to be rebase on master and target 4.1, it's too late to merge in into 3.4.
Note also that there is a big missing part (it's a non-trivial topic): the dumper container also needs to trigger the deprecation notice.

j92 · 2017-10-28T15:17:18Z

@nicolas-grekas Thanks for the feedback. I will add the missing part, do some more testing and target 4.1.

j92 · 2017-11-03T15:32:42Z

I am currently figuring out how to handle the trigger of the deprecation notice in the dumped container. Especially with deprecated private aliases, which are removed from the container in the RemovePrivateAliasesPass compiler pass. So after compiling, I have no reference to these aliases anymore.

For public aliases I had the idea to deprecate the actual definition in the ReplaceAliasByActualDefinitionPass compiler pass, but I'm also not sure if thats the correct way to go.

@greg0ire Maybe you have an idea that will push me in the right direction here?

greg0ire · 2017-11-03T16:02:09Z

Especially with deprecated private aliases, which are removed from the container in the RemovePrivateAliasesPass compiler pass. So after compiling, I have no reference to these aliases anymore.

Not sure if this is an issue. IMO, the deprecations should be triggered when compiling the container, because that is when they are used. You don't want deprecations to be triggered for every unrelated http requests.

For public aliases I had the idea to deprecate the actual definition in the ReplaceAliasByActualDefinitionPass compiler pass, but I'm also not sure if thats the correct way to go.

If you do that, people will not be able to get rid of the deprecation by referencing the actual service definition, will they?

j92 · 2017-11-17T08:10:47Z

@greg0ire Sorry for the late reply, I didn't have a lot of time to work on this issue.

Are you sure that the deprecations should be triggered when compiling the container? As far as I can see and understand it, the notices are added in the dumper classes like the PhpDumper and the XmlDumper. Then the dumped container is loaded and the real errors are triggered in the ContainerBuilder. So every time the container is loaded, the deprecation error is triggered, which makes it possible to show it in the Symfony Profile for example.

greg0ire · 2017-11-17T09:24:33Z

That's my point. Wouldn't that make a lot of deprecations, irrelevant to the current page? Not sure what's best.

j92 · 2017-11-17T09:56:04Z

That makes a lot of deprecations indeed, but that's also how it's done for services at the moment. Deprecating a service, triggers a notice on every request. So my guess is that we want the same behaviour for service aliases right?

greg0ire · 2017-11-17T09:56:55Z

Correct. Go with it then.

j92 · 2017-11-17T10:09:41Z

Okay, I will then.

To come back to my original question, I am wondering about the comment of @nicolas-grekas :

Note also that there is a big missing part (it's a non-trivial topic): the dumper container also needs to trigger the deprecation notice.

Is it enough to implement the deprecation notices in the several dumpers like the PhpDumper and the XmlDumper, so that when they are loaded, the ContainerBuilder triggers the deprecation notice? Or I am missing other places which should trigger the deprecation notice as well?

kiler129 · 2018-01-25T08:45:20Z

Ok, I think there is a time to take a dust from this issue ;) First of all I don’t believe it’s enough to implement them in dumpers, this will lead to poor DX.

I spent some time with the code and I have few ideas. Two steps are necessary regardless of the solution choosen:

Rebase onto master
Modify ReplaceAliasByActualDefinition to ignore not just public aliases but also deprecated ones

Then we get into interesting part - how to trigger deprecation on runtime?

[A] Change aliases array to contain deprecation flag
- We change aliastName => (string)target to aliasName => [target, (bool)isDeprecated]
- We change internal yet public $this->aliases (correct me if I’m wrong?).
- This requires modification of all calls to $this->aliases[$id] to use $this->aliases[$id][0]
- Generally I will say it's no-no solution due to a real BC break
[B] Save two maps side by side
- First map stays as it is in $this->aliases
- Second map has structure exactly like $this->aliases but it’s checked after normal map and triggers deprecation notice as needed
- This requires additional element and changes in base container class. Instead of having something like this (example from get()):
```
if (isset($this->aliases[$id])) {
    $id = $this->aliases[$id];
}
```
  we will end up with:
```
if (isset($this->aliases[$id])) {
    $id = $this->aliases[$id];
} elseif (isset($this->aliasesDeprecated[$id])) {
    $id = $this-> aliasesDeprecated[$id];
    @trigger_error(...);
}
```
- This solution has almost no BC break. The only small thing I see is we no longer guarantee that $this->aliases contains all not inlined aliases, but personally I'm not concerned
- I don't like this solution since it introduces additional overhead to every lookup when service is not an alias nor a deprecated alias
- This solution doesn't let us give a good DX by suggesting a replacement
[C] Save deprecation map
- Map in $this->aliases stays as is
- We add list under $this-> aliasesDeprecated containing an array with alias name as the key and target alias as value (which gives us option to provide suggestion of new service/alias name)
- Again we have to change lookups in base container. The lookup will look like so:
```
if (isset($this->aliases[$id])) {
    $id = $this->aliases[$id];
    if (isset($this->aliasesDeprecated[$id])) {
        @trigger_error(...);
    }
}
```
- This solution has almost zero BC break
- I slightly dislike it. It's better than [B] since we get overhead only on call to aliases, but the overhead is added to all aliased - deprecated or not...
[D] Generate alias methods
- Modify PhpDumper::addMethodMap() to include methods for deprecated aliases (this of course has to be done after targets)
- Skip deprecated aliases in PhpDumper::addAlises()
- Modify (scary) PhpDumper::addService() to generate method like so:
```
protected function get[AliasName]AliasTo[TargetName]() {
    @trigger_error(...);

    return get[TargetName]();
}
```
- This will be hard to implement (at least form my point of view)
- This will introduce performance loss only on deprecated aliases, nothing else

WDYT @nicolas-grekas? @fabpot?

nicolas-grekas · 2018-01-25T09:34:32Z

@kiler129 thanks for the heads up. I think we should go for D (no need for a special name for the method, the existing "generateMethodName" logic is good enough), but of course only for public aliases that cannot be inlined. Thus, the current state of the PR looks good to me. It just needs to handle two more cases:

non-inlined public deprecated aliases should generate a method like suggested here (D). That'd mean they'd be listed in the "methodMaps" property, and not in "aliases" anymore of course.
we need a new logic at compilation time that would trigger a deprecation whenever a deprecated symbol is referenced (either an alias or a service, doesn't matter).

As a general design note, I don't think it matter that the symbol being deprecated is an alias or a service: that's an implementation detail of the service graph. What matters is that a symbol that is being planned for removal triggers a warning when referenced/used. This may mean that we don't need to put the word "alias" in the messages, and use "service" all the time. WDYT?

@j92 does that make sense for you? Ok to continue?

kiler129 · 2018-01-25T09:58:06Z

I think we're on the right track.

For inlined aliases (so in practice all private ones, right?) we will get a deprecation notice during build and it will stay in compilation log which is easily accessible now
Non-inlined ones will become pseudo-services carrying method triggering deprecation and listed in map and will not be present in aliases array
For the reference logic across compilation process, if I understood your intention correctly @nicolas-grekas, you want to trigger deprecation everywhere deprecated symbol is used. I quickly searched DIC component code and found possible targets:
- Compiler\AnalyzeServiceReferencesPass::getDefinitionId
- Compiler\AutoAliasServicePass
- Compiler\DecoratorServicePass
- Compiler\ResolveReferencesToAliasesPass::getDefinitionId

After thinking for a while I believe the idea of treating services and aliases equally is right - it's an implementation detail after all. Other messages in DIC component (except obvious places like hasAlias()) also doesn't handle aliases in any special way in terms of messages.

@j92 Are you willing to rebase onto master and implement additional logic discussed?

nicolas-grekas · 2018-01-25T10:43:06Z

ResolveReferencesToAliasesPass looks like the good place to me for now

j92 · 2018-01-26T08:28:32Z

@kiler129 Thanks for dusting of this issue;) Yes, I am willing to rebase this branch and will start to implement the additional logic asap.

kiler129 · 2018-03-13T17:09:01Z

@j92: Any news? Sorry for poking you, but I just periodically visit PRs which are relevant to what I do ;)

fabpot · 2018-04-04T12:27:22Z

@nicolas-grekas Can you review this one again?

j92 · 2018-04-04T13:02:54Z

@greg0ire @kiler129 Sorry for not finishing this PR in time. I got stuck a while ago and was not progressing at all. Unfortunately the next few weeks I won't have free time, so:

Is there someone who can takeover the work?

weaverryan · 2018-04-18T19:08:25Z

It's ok @j92 :). Let's just finish this PR when you have time. I'm here because we just had a use-case for this in DoctrineBundle. But, no need to rush - we're after the 4.1 feature freeze. But, yes, let's definitely try to get this in there for 4.2!

artursvonda · 2018-08-02T11:44:28Z

src/Symfony/Component/DependencyInjection/Loader/YamlFileLoader.php

@@ -346,8 +346,13 @@ private function parseDefinition($id, $service, $file, array $defaults)
            }

            foreach ($service as $key => $value) {
-                if (!in_array($key, array('alias', 'public'))) {
+                if (!in_array($key, array('alias', 'public', 'deprecated'))) {
                    throw new InvalidArgumentException(sprintf('The configuration key "%s" is unsupported for the service "%s" which is defined as an alias in "%s". Allowed configuration keys for service aliases are "alias" and "public".', $key, $id, $file));


Should the message be updated, too? Now it includes hardcoded keys for service aliases are "alias" and "public".

fabpot · 2018-10-10T12:04:23Z

@nicolas-grekas I think we need your input here :)

nicolas-grekas · 2019-01-24T17:02:18Z

Continued in #29968, thank you @j92!

This PR was merged into the 4.3-dev branch. Discussion ---------- [DI] Added support for deprecating aliases | Q | A | ------------- | --- | Branch? | master | Bug fix? | no | New feature? | yes | BC breaks? | no | Deprecations? |no | Tests pass? | yes | Fixed tickets | #24507 | License | MIT | Doc PR | TBD This PR is a continuity of #24707 Commits ------- 6c571ad Added support for deprecating aliases (runtime+dumper) 0eb071b Added support for deprecating an alias

carsonbot added Status: Needs Review Bug Feature labels Oct 27, 2017

j92 mentioned this pull request Oct 27, 2017

Ability to deprecate aliases #24507

Closed

carsonbot added Status: Needs Work and removed Status: Needs Review labels Oct 27, 2017

greg0ire suggested changes Oct 27, 2017

View reviewed changes

j92 force-pushed the deprecate-aliases branch 2 times, most recently from c709de5 to ced5f49 Compare October 28, 2017 14:28

nicolas-grekas added this to the 4.1 milestone Oct 28, 2017

garak mentioned this pull request Jan 22, 2018

Add aliases to be able to extend VichImageType dustin10/VichUploaderBundle#818

Merged

j92 changed the base branch from 3.4 to master January 26, 2018 09:06

j92 added 4 commits January 26, 2018 10:10

Added support for deprecating an alias

4e0383a

Added support for deprecating an alias in the container builder

dc3fb87

Added deprecation of aliases to the xml file loader

2d6181d

Removed string typehint

d2781fa

j92 added 4 commits January 26, 2018 10:14

Applied coding standard review

70721a5

Fixed a type and made the deprecation template clearer

34ce7bf

Added deprecation of aliases to the yaml file loader

16a8676

Added deprecating aliases to the various container files

3bffe61

j92 force-pushed the deprecate-aliases branch from ced5f49 to 3bffe61 Compare January 26, 2018 09:15

greg0ire mentioned this pull request Mar 7, 2018

Provide autowiring for AuditReader sonata-project/EntityAuditBundle#311

Closed

nicolas-grekas modified the milestones: 4.1, next Apr 20, 2018

artursvonda reviewed Aug 2, 2018

View reviewed changes

nicolas-grekas self-assigned this Oct 10, 2018

renanbr mentioned this pull request Jan 23, 2019

[DI] Added support for deprecating aliases #29968

Merged

nicolas-grekas closed this Jan 24, 2019

nicolas-grekas modified the milestones: next, 4.3 Apr 30, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Added support for deprecating aliases #24707

Added support for deprecating aliases #24707

j92 commented Oct 27, 2017 •

edited

Loading

greg0ire left a comment

greg0ire Oct 27, 2017

greg0ire Oct 27, 2017

nicolas-grekas commented Oct 28, 2017

j92 commented Oct 28, 2017

j92 commented Nov 3, 2017

greg0ire commented Nov 3, 2017

j92 commented Nov 17, 2017

greg0ire commented Nov 17, 2017

j92 commented Nov 17, 2017

greg0ire commented Nov 17, 2017

j92 commented Nov 17, 2017

kiler129 commented Jan 25, 2018 •

edited

Loading

nicolas-grekas commented Jan 25, 2018 •

edited

Loading

kiler129 commented Jan 25, 2018 •

edited

Loading

nicolas-grekas commented Jan 25, 2018

j92 commented Jan 26, 2018

kiler129 commented Mar 13, 2018

fabpot commented Apr 4, 2018

j92 commented Apr 4, 2018 •

edited

Loading

weaverryan commented Apr 18, 2018

artursvonda Aug 2, 2018

fabpot commented Oct 10, 2018

nicolas-grekas commented Jan 24, 2019

Added support for deprecating aliases #24707

Added support for deprecating aliases #24707

Conversation

j92 commented Oct 27, 2017 • edited Loading

greg0ire left a comment

Choose a reason for hiding this comment

greg0ire Oct 27, 2017

Choose a reason for hiding this comment

greg0ire Oct 27, 2017

Choose a reason for hiding this comment

nicolas-grekas commented Oct 28, 2017

j92 commented Oct 28, 2017

j92 commented Nov 3, 2017

greg0ire commented Nov 3, 2017

j92 commented Nov 17, 2017

greg0ire commented Nov 17, 2017

j92 commented Nov 17, 2017

greg0ire commented Nov 17, 2017

j92 commented Nov 17, 2017

kiler129 commented Jan 25, 2018 • edited Loading

nicolas-grekas commented Jan 25, 2018 • edited Loading

kiler129 commented Jan 25, 2018 • edited Loading

nicolas-grekas commented Jan 25, 2018

j92 commented Jan 26, 2018

kiler129 commented Mar 13, 2018

fabpot commented Apr 4, 2018

j92 commented Apr 4, 2018 • edited Loading

weaverryan commented Apr 18, 2018

artursvonda Aug 2, 2018

Choose a reason for hiding this comment

fabpot commented Oct 10, 2018

nicolas-grekas commented Jan 24, 2019

j92 commented Oct 27, 2017 •

edited

Loading

kiler129 commented Jan 25, 2018 •

edited

Loading

nicolas-grekas commented Jan 25, 2018 •

edited

Loading

kiler129 commented Jan 25, 2018 •

edited

Loading

j92 commented Apr 4, 2018 •

edited

Loading