[config] Add abbitily to deprecate a node #22382

sanpii · 2017-04-11T20:07:44Z

Q	A
Branch?	3.4
Bug fix?	no
New feature?	yes
BC breaks?	maybe
Deprecations?	no
Tests pass?	yes
Fixed tickets	n/a
License	MIT
Doc PR	symfony/symfony-docs#7794

For BC breaks, I don’t know if modifying the Xml and Yaml dumper output is considering as a BC break (it’s just a comment).

Nek- · 2017-04-11T22:31:22Z

You may add the possibility to specify a message ? Anyway that's awesome, thanks !

HeahDude · 2017-04-11T22:53:31Z

Hello @sanpii, thanks for proposing this. For the record, this was proposed before #21051.

sanpii · 2017-04-12T07:33:34Z

You may add the possibility to specify a message ?

It’s in a corner of my mind, but I don’t know how do this smartly.

sstok · 2017-04-12T08:35:36Z

FYI, there is typo in the title depreciate -> deprecate 😉
depreciate is to devalue something.

sanpii · 2017-04-12T08:39:10Z

@sstok fixed, thank you.

ro0NL · 2017-04-12T14:14:14Z

To clarify, my goal with #21051 was to not include/define deprecated nodes in the tree; and solely focus on bridging the old situation to a new situation (as a normalization step).

Im 👎 on this. You should checkout why mine was rejected :)

sanpii · 2017-04-12T19:30:02Z

You should checkout why mine was rejected :)

I see two points:

is quite easily implemented directly in the code

Of course, all new features is probably easy to implement… But, I think, trigger_error is a low level function and symfony is here to abstract its.

I don't see the need for end user projects to deprecate options

We are, at least, two persons who find this suffisamment helpful to take the time to make a PR.

ro0NL · 2017-04-13T14:38:35Z

I still think it's a good feature.. in case you thought different.

Maybe this approach is good enough, as it's kinda the same we do for services. Personally i like the normalization to happen, otherwise people still need to take care of old/new nodes at implementation level, e.g. in an extension.

nicolas-grekas · 2017-05-02T09:45:28Z

src/Symfony/Component/Config/Definition/ArrayNode.php

@@ -234,6 +234,11 @@ protected function finalizeValue($value)
        }

        foreach ($this->children as $name => $child) {
+            if ($child->isDeprecated()) {
+                $msg = sprintf('The child node "%s" at path "%s" is deprecated.', $name, $this->getPath());


Typically, deprecation message should also mention the version since it's been deprecated, the outcome in the next major version, and the alternative if any. Would be great to allow + encourage doing so here also.

Yes, I’m agree with you. But I did’t find a good way to do this.

Maybe by passing an optionnal argument to isDeprecated() method?

I think that customizing the message would solve the thing (with mandatory place holders like %node_name% and %node_path%. A bit like what is done on deprecating services, which has a mandatory %service_id% placeholder (or something like that))

nicolas-grekas · 2017-07-06T07:34:55Z

I think we can go with this feature, the implementation is simple enough.
I propose this API:

public function setDeprecated($message)
public function isDeprecated()
public function getDeprecationMessage($node, $path)

with $message allowing %node% and %path placeholders.

Status: needs work

sanpii · 2017-07-07T19:24:54Z

PR updated according to @nicolas-grekas’ propositions.

ro0NL · 2017-07-07T20:55:11Z

src/Symfony/Component/Config/Definition/BaseNode.php

@@ -142,6 +143,16 @@ public function setRequired($boolean)
    }

    /**
+     * Set this node as deprecated.
+     *
+     * @param string $message Deprecated message


string|null

ro0NL · 2017-07-07T20:55:21Z

src/Symfony/Component/Config/Definition/BaseNode.php

+     */
+    public function isDeprecated()
+    {
+        return $this->deprecatedMessage != null;


ro0NL · 2017-07-07T20:55:29Z

src/Symfony/Component/Config/Definition/BaseNode.php

+     *
+     * @return bool
+     */
+    public function getDeprecationMessage($node, $path)


protected?

Not now, it’s used by Xml and Yaml dumper.

ro0NL · 2017-07-07T20:57:34Z

src/Symfony/Component/Config/Tests/Fixtures/Configuration/ExampleConfiguration.php

@@ -35,6 +35,8 @@ public function getConfigTreeBuilder()
                ->scalarNode('scalar_array_empty')->defaultValue(array())->end()
                ->scalarNode('scalar_array_defaults')->defaultValue(array('elem1', 'elem2'))->end()
                ->scalarNode('scalar_required')->isRequired()->end()
+                ->scalarNode('scalar_deprecated')->isDeprecated()->end()
+                ->scalarNode('scalar_deprecated_with_message')->isDeprecated('Deprecation custom message')->end()


you should test the placeholder replacements as well imo.

sanpii · 2017-07-08T16:05:55Z

@ro0NL Fixed, thank you for your review.

nicolas-grekas · 2017-07-11T14:16:29Z

src/Symfony/Component/Config/Definition/ArrayNode.php

@@ -234,6 +234,11 @@ protected function finalizeValue($value)
        }

        foreach ($this->children as $name => $child) {
+            if ($child->isDeprecated()) {
+                $msg = $child->getDeprecationMessage($name, $this->getPath());


let get rid of the $msg var and do things inline

nicolas-grekas · 2017-07-11T14:17:14Z

src/Symfony/Component/Config/Definition/BaseNode.php

+     */
+    public function isDeprecated()
+    {
+        return $this->deprecatedMessage !== null;


yoda style: null !== ...

nicolas-grekas · 2017-07-11T14:17:53Z

src/Symfony/Component/Config/Definition/BaseNode.php

@@ -29,6 +29,7 @@
    protected $finalValidationClosures = array();
    protected $allowOverwrite = true;
    protected $required = false;
+    protected $deprecatedMessage = null;


$deprecationMessage (same below)

nicolas-grekas · 2017-07-11T14:18:26Z

src/Symfony/Component/Config/CHANGELOG.md

@@ -9,6 +9,7 @@ CHANGELOG
 * made `ClassExistenceResource` work with interfaces and traits
 * added `ConfigCachePass` (originally in FrameworkBundle)
 * added `castToArray()` helper to turn any config value into an array
+ * added `isDeprecated()` method to indicate a deprecated node


let advertise setDeprecated instead?

nicolas-grekas · 2017-07-11T14:21:31Z

src/Symfony/Component/Config/Definition/Builder/NodeDefinition.php

+     *
+     * @return $this
+     */
+    public function isDeprecated($message = 'The child node "%node%" at path "%path%" is deprecated.')


should be named setDeprecated.
Not sure about the default value, there is always more to add than the default (not a string opinion, just noting.)

nicolas-grekas · 2017-07-11T14:22:22Z

src/Symfony/Component/Config/Definition/Builder/NodeDefinition.php

+     */
+    public function isDeprecated($message = 'The child node "%node%" at path "%path%" is deprecated.')
+    {
+        $this->deprecatedMessage = $message;


in Definition, we enforce that the placeholder is used, we should do the same here IMHO, for both placeholders

sanpii · 2017-07-11T15:34:40Z

@nicolas-grekas thank you.

…iff2.0 (Nyholm) This PR was squashed before being merged into the 3.4 branch (closes #23947). Discussion ---------- [Translation] Adding the ability do load <notes> in xliff2.0 | Q | A | ------------- | --- | Branch? | 3.4 | Bug fix? | ~~~~yes~~~ no (sorry) | New feature? | yes | BC breaks? | no | Deprecations? | no | Tests pass? | yes | Fixed tickets | | License | MIT | Doc PR | Since #23890 we can dump `<notes>`. We should also have the ability to load them back. Commits ------- b0cdb53 [Translation] Adding the ability do load <notes> in xliff2.0

fabpot · 2017-08-26T13:23:01Z

src/Symfony/Component/Config/Definition/BaseNode.php

@@ -142,6 +143,16 @@ public function setRequired($boolean)
    }

    /**
+     * Set this node as deprecated.


fabpot · 2017-08-26T13:23:27Z

src/Symfony/Component/Config/Definition/BaseNode.php

+     * @param string $node the configuration node name
+     * @param string $path the path of the node
+     *
+     * @return bool


@return string

fabpot · 2017-08-26T13:24:18Z

src/Symfony/Component/Config/Definition/BaseNode.php

@@ -142,6 +143,16 @@ public function setRequired($boolean)
    }

    /**
+     * Set this node as deprecated.
+     *


You should hint here that %node% and %path% have a special meaning in a deprecated message.

fabpot · 2017-08-26T13:25:12Z

src/Symfony/Component/Config/Definition/Builder/NodeDefinition.php

@@ -169,6 +170,20 @@ public function isRequired()
    }

    /**
+     * Sets the node as deprecated.
+     *


Same here for the special %node% and %path% vars.

fabpot · 2017-08-26T13:25:23Z

src/Symfony/Component/Config/Definition/Dumper/XmlReferenceDumper.php

+                        $comments[] = sprintf(
+                            'Deprecated (%s)',
+                            $child->getDeprecationMessage($child->getName(), $child->getPath())
+                        );


should be on one line.

fabpot · 2017-08-26T13:25:34Z

src/Symfony/Component/Config/Definition/Dumper/YamlReferenceDumper.php

+            $comments[] = sprintf(
+                'Deprecated (%s)',
+                $node->getDeprecationMessage($node->getName(), $node->getPath())
+            );


one line please

fabpot · 2017-08-26T13:26:28Z

Target branch should also be changed to 3.4 instead of master.

sanpii · 2017-08-26T13:49:26Z

@fabpot fixed and rebased on the 3.4 branch. Thank you.

fabpot · 2017-08-26T15:02:03Z

Thank you @sanpii.

…pot, sanpii) This PR was merged into the 4.0-dev branch. Discussion ---------- [config] Add abbitily to deprecate a node | Q | A | ------------- | --- | Branch? | 3.4 | Bug fix? | no | New feature? | yes | BC breaks? | maybe | Deprecations? | no | Tests pass? | yes | Fixed tickets | n/a | License | MIT | Doc PR | symfony/symfony-docs#7794 For BC breaks, I don’t know if modifying the Xml and Yaml dumper output is considering as a BC break (it’s just a comment). Commits ------- 31d2250 [config] Add abbitily to deprecate a node 3b6442f feature #23947 [Translation] Adding the ability do load <notes> in xliff2.0 (Nyholm) b0cdb53 [Translation] Adding the ability do load <notes> in xliff2.0

stof · 2017-08-28T10:38:48Z

@fabpot why was it merged into the 4.0-dev branch ?

nicolas-grekas · 2017-08-28T19:50:32Z

@sanpii are there existing deprecated options that could leverage this PR (on 3.4)? Would you have time to create a PR for it?

maidmaid · 2017-08-29T09:35:28Z

symfony/src/Symfony/Bundle/FrameworkBundle/DependencyInjection/Configuration.php

Lines 68 to 71 in 4173f13

    
           ->arrayNode('trusted_proxies') 
        
               ->beforeNormalization() 
        
                   ->ifTrue(function ($v) { 
        
                       @trigger_error('The "framework.trusted_proxies" configuration key has been deprecated in Symfony 3.3. Use the Request::setTrustedProxies() method in your front controller instead.', E_USER_DEPRECATED);

Maybe here for instance?

sanpii · 2017-08-29T10:27:44Z

@nicolas-grekas good idea, but the PR was merged on master, not on 3.4

Here the deprecated configuration I found:

https://github.com/symfony/symfony/blob/3.4/src/Symfony/Bundle/FrameworkBundle/DependencyInjection/FrameworkExtension.php#L1199
https://github.com/symfony/symfony/blob/3.4/src/Symfony/Bundle/FrameworkBundle/DependencyInjection/FrameworkExtension.php#L1455
https://github.com/symfony/symfony/blob/3.4/src/Symfony/Bundle/FrameworkBundle/FrameworkBundle.php#L67

…pot, sanpii) This PR was merged into the 3.4-dev branch. Discussion ---------- [config] Add abbitily to deprecate a node | Q | A | ------------- | --- | Branch? | 3.4 | Bug fix? | no | New feature? | yes | BC breaks? | maybe | Deprecations? | no | Tests pass? | yes | Fixed tickets | n/a | License | MIT | Doc PR | symfony/symfony-docs#7794 For BC breaks, I don’t know if modifying the Xml and Yaml dumper output is considering as a BC break (it’s just a comment). Commits ------- 31d2250 [config] Add abbitily to deprecate a node 3b6442f feature #23947 [Translation] Adding the ability do load <notes> in xliff2.0 (Nyholm) b0cdb53 [Translation] Adding the ability do load <notes> in xliff2.0

This PR was merged into the 3.4 branch. Discussion ---------- [config] Add ability to deprecate a node | Q | A | ------------- | --- | Branch? | 3.4 | Bug fix? | no | New feature? | yes | BC breaks? | no | Deprecations? | no | Tests pass? | yes | Fixed tickets | - | License | MIT | Doc PR | - This is #22382 on 3.4 Commits ------- a00a4ff [config] Add ability to deprecate a node

nicolas-grekas · 2017-08-29T16:09:43Z

Now merged in 3.4

* 3.4: (38 commits) Fix merge [Lock] Expose an expiringDate and isExpired method in Lock [VarDumper] fix DateCasterTest [config] Add ability to deprecate a node feature symfony#22382 [config] Add abbitily to deprecate a node (Nyholm, fabpot, sanpii) Fix segfault in period caster Create an interface for TranslationReader and moved TranslationLoader to Translation component Always require symfony/polyfill-apcu to provide APCuIterator everywhere [Lock] Fix some tests that require pcntl_sigwaitinfo() function bumped Symfony version to 3.3.9 updated VERSION for 3.3.8 updated CHANGELOG for 3.3.8 [DI] Fix tracking env var placeholders nested in object graphs bumped Symfony version to 3.3.8 updated VERSION for 3.3.7 updated CHANGELOG for 3.3.7 Add period caster [DI] improve psr4-based service discovery with namespace option [DI] Fix tracking env vars when merging configs (bis) removed obsolete comment ...

This PR was merged into the 3.4 branch. Discussion ---------- Fix ability to deprecate a config node | Q | A | ------------- | --- | Branch? | 3.4 | Bug fix? | not yet released | New feature? | no | BC breaks? | no | Deprecations? | no | Tests pass? | yes | Fixed tickets | #22382 | License | MIT | Doc PR | n/a Unlocks #24025 Commits ------- fc91869 Fix ability to deprecate a config node

This PR was merged into the 3.4 branch. Discussion ---------- Use new configuration depreciation method | Q | A | ------------- | --- | Branch? | 3.4 | Bug fix? | no | New feature? | no | BC breaks? | no | Deprecations? | no | Tests pass? | no | Fixed tickets | N/A | License | MIT | Doc PR | N/A In keeping with #22382 Commits ------- 4a62cc6 Do not trigger deprecation if node has not been explicitly filled 012e381 Use new configuration node depreciation method

…ereguiluz) This PR was submitted for the master branch but it was merged into the 3.4 branch instead (closes #7794). Discussion ---------- [config] Add a note about deprecated a node Documentation for symfony/symfony#22382 Commits ------- 1939371 Explained the possibility of defining custom deprecation messages d6a8624 [config] Add a note about deprecated a node

carsonbot added Status: Needs Review Config Feature labels Apr 11, 2017

sanpii mentioned this pull request Apr 11, 2017

[config] Add a note about deprecated a node symfony/symfony-docs#7794

Closed

sanpii changed the title ~~[config] Add abbitily to depreciate a node~~ [config] Add abbitily to deprecate a node Apr 12, 2017

nicolas-grekas added this to the 3.4 milestone Apr 13, 2017

nicolas-grekas reviewed May 2, 2017

View reviewed changes

carsonbot added Status: Needs Work and removed Status: Needs Review labels Jul 6, 2017

ro0NL reviewed Jul 7, 2017

View reviewed changes

ro0NL approved these changes Jul 8, 2017

View reviewed changes

nicolas-grekas reviewed Jul 11, 2017

View reviewed changes

dunglas mentioned this pull request Jul 12, 2017

Swagger subresource + OperationPathResolver refactor proposal api-platform/core#1245

Merged

7 tasks

nicolas-grekas approved these changes Aug 22, 2017

View reviewed changes

nicolas-grekas added Status: Reviewed and removed Status: Needs Work labels Aug 22, 2017

Nyholm and others added 2 commits August 26, 2017 06:08

[Translation] Adding the ability do load <notes> in xliff2.0

b0cdb53

fabpot requested changes Aug 26, 2017

View reviewed changes

[config] Add abbitily to deprecate a node

31d2250

fabpot approved these changes Aug 26, 2017

View reviewed changes

fabpot merged commit 31d2250 into symfony:master Aug 26, 2017

nicolas-grekas mentioned this pull request Aug 29, 2017

[config] Add ability to deprecate a node #24024

Merged

sanpii mentioned this pull request Aug 29, 2017

Use new configuration depreciation method #24025

Merged

chalasr mentioned this pull request Sep 3, 2017

Fix ability to deprecate a config node #24083

Merged

fabpot mentioned this pull request Oct 19, 2017

Release v4.0.0-BETA1 #24612

Merged

[config] Add abbitily to deprecate a node #22382

[config] Add abbitily to deprecate a node #22382

Conversation

sanpii commented Apr 11, 2017 • edited Loading

Nek- commented Apr 11, 2017

HeahDude commented Apr 11, 2017

sanpii commented Apr 12, 2017

sstok commented Apr 12, 2017

sanpii commented Apr 12, 2017

ro0NL commented Apr 12, 2017 • edited Loading

sanpii commented Apr 12, 2017

ro0NL commented Apr 13, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Taluu May 2, 2017 • edited Loading

Choose a reason for hiding this comment

nicolas-grekas commented Jul 6, 2017

sanpii commented Jul 7, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ro0NL Jul 7, 2017 • edited Loading

Choose a reason for hiding this comment

sanpii commented Jul 8, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sanpii commented Jul 11, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

fabpot commented Aug 26, 2017

sanpii commented Aug 26, 2017

fabpot commented Aug 26, 2017

stof commented Aug 28, 2017

nicolas-grekas commented Aug 28, 2017

maidmaid commented Aug 29, 2017 • edited Loading

sanpii commented Aug 29, 2017 • edited Loading

nicolas-grekas commented Aug 29, 2017

sanpii commented Apr 11, 2017 •

edited

Loading

ro0NL commented Apr 12, 2017 •

edited

Loading

Taluu May 2, 2017 •

edited

Loading

ro0NL Jul 7, 2017 •

edited

Loading

maidmaid commented Aug 29, 2017 •

edited

Loading

sanpii commented Aug 29, 2017 •

edited

Loading