feat: migration path for with_annotation to with_attribute (#2430)

## Description Deprecates `with_annotation` in favor of `with_attribute` introduced in 5.x #2368 ## What type of PR is this? (check all applicable) - [ ] Bug Fix - [ ] Feature - [ ] Refactor - [x] Deprecation - [ ] Breaking Change - [x] Documentation Update - [ ] CI ## Checklist - [x] I have made corresponding changes to the documentation (`docs/`) - [x] I have made corresponding changes to the changelog (`CHANGELOG.md`)
nelmio · Jan 19, 2025 · 3aaa734 · 3aaa734
1 parent f320ae4
commit 3aaa734
Show file tree

Hide file tree

Showing 11 changed files with 75 additions and 15 deletions.
diff --git a/.doctor-rst.yaml b/.doctor-rst.yaml
@@ -53,16 +53,16 @@ rules:
 
     #   master
     versionadded_directive_major_version:
-        major_version: 7
+        major_version: 4
 
     versionadded_directive_min_version:
-        min_version: '7.0'
+        min_version: '4.0'
 
     deprecated_directive_major_version:
-        major_version: 6
+        major_version: 4
 
     deprecated_directive_min_version:
-        min_version: '6.0'
+        min_version: '4.0'
 
 # do not report as violation
 whitelist:

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,16 @@
 # CHANGELOG
 
+## 4.36.0
+* Configuration option `with_annotation` has been deprecated in favor of `with_attribute`
+```diff
+nelmio_api_doc:
+    areas:
+        path_patterns:
+            - ^/api/foo
+-       with_annotation: true
++       with_attribute: true
+```
+
 ## 4.35.0
 * Added support for the symfony/type-info component
 ```yaml

diff --git a/docs/areas.rst b/docs/areas.rst
@@ -77,7 +77,7 @@ the routes that should be documented:
             default:
                 path_patterns: [ ^/api ]
             internal:
-                with_annotation: true
+                with_attribute: true
 
 Then add the attribute/annotation before your controller or action::
 

diff --git a/docs/configuration_reference.rst b/docs/configuration_reference.rst
@@ -54,7 +54,7 @@ The bundle configuration is stored under the ``nelmio_api_doc`` key in your appl
                     # Example:
                     # - ^api_v1
             # whether to filter by attributes
-            with_annotation:       false
+            with_attribute: false
             # if set disables default routes without attributes
             disable_default_routes: false
             # The base documentation used for the area
@@ -94,6 +94,10 @@ Whether to use `symfony/type-info`_ for determining types.
 
     If you are using Symfony 7.2 or higher, you should set this option to ``true``. As this greatly improves type detection.
 
+.. versionadded:: 4.35
+
+    Support for `symfony/type-info`_ was added in 4.35.
+
 use_validation_groups
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -193,7 +197,7 @@ Filter the routes that are documented.
                     name_patterns:
                         # Example:
                         # - ^api_v1
-                with_annotation:       false
+                with_attribute: false
                 disable_default_routes: false
                 documentation:
                     # Example:
@@ -238,6 +242,18 @@ with_annotation
 
 Whether to only document routes with the ``#[Areas]`` annotation/attribute.
 
+.. deprecated:: 4.36
+
+    ``with_annotation`` was deprecated in 4.36. Use ``with_attribute`` instead.
+
+with_attribute
+...............
+
+**type**: ``boolean``
+**default**: ``false``
+
+Whether to only document routes with the ``#[Areas]`` annotation/attribute.
+
 disable_default_routes
 ......................
 

diff --git a/docs/faq.rst b/docs/faq.rst
@@ -279,7 +279,7 @@ Q: I have a property that is not recognized. How can I specify the type?
             type_info: true
             # ...
 
-.. versionadded:: 7.2
+.. versionadded:: 4.35
 
     The `TypeInfo component`_ was introduced as a stable feature in Symfony 7.2.
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -534,7 +534,7 @@ General PHP objects
             type_info: true
             # ...
 
-.. versionadded:: 7.2
+.. versionadded:: 4.35
 
     The `TypeInfo component`_ was introduced as a stable feature in Symfony 7.2.
 

diff --git a/src/DependencyInjection/Configuration.php b/src/DependencyInjection/Configuration.php
@@ -91,6 +91,7 @@ public function getConfigTreeBuilder(): TreeBuilder
                                 'path_patterns' => [],
                                 'host_patterns' => [],
                                 'with_annotation' => false,
+                                'with_attribute' => false,
                                 'documentation' => [],
                                 'name_patterns' => [],
                                 'disable_default_routes' => false,
@@ -134,6 +135,11 @@ public function getConfigTreeBuilder(): TreeBuilder
                             ->booleanNode('with_annotation')
                                 ->defaultFalse()
                                 ->info('whether to filter by annotation')
+                                ->setDeprecated('nelmio/api-doc-bundle', '4.36.0', 'The "%node%" option is deprecated. Use "with_attribute" instead.')
+                            ->end()
+                            ->booleanNode('with_attribute')
+                                ->defaultFalse()
+                                ->info('whether to filter by attribute')
                             ->end()
                             ->booleanNode('disable_default_routes')
                                 ->defaultFalse()

diff --git a/src/DependencyInjection/NelmioApiDocExtension.php b/src/DependencyInjection/NelmioApiDocExtension.php
@@ -133,7 +133,7 @@ public function load(array $configs, ContainerBuilder $container): void
             if (0 === count($areaConfig['path_patterns'])
                 && 0 === count($areaConfig['host_patterns'])
                 && 0 === count($areaConfig['name_patterns'])
-                && false === $areaConfig['with_annotation']
+                && (false === $areaConfig['with_annotation'] && false === $areaConfig['with_attribute'])
                 && false === $areaConfig['disable_default_routes']
             ) {
                 $container->setDefinition(sprintf('nelmio_api_doc.routes.%s', $area), $routesDefinition)

diff --git a/src/Routing/FilteredRouteCollectionBuilder.php b/src/Routing/FilteredRouteCollectionBuilder.php
@@ -49,12 +49,14 @@ public function __construct(
                 'host_patterns' => [],
                 'name_patterns' => [],
                 'with_annotation' => false,
+                'with_attribute' => false,
                 'disable_default_routes' => false,
             ])
             ->setAllowedTypes('path_patterns', 'string[]')
             ->setAllowedTypes('host_patterns', 'string[]')
             ->setAllowedTypes('name_patterns', 'string[]')
             ->setAllowedTypes('with_annotation', 'boolean')
+            ->setAllowedTypes('with_attribute', 'boolean')
             ->setAllowedTypes('disable_default_routes', 'boolean')
         ;
 
@@ -123,7 +125,7 @@ private function matchName(string $name): bool
 
     private function matchAnnotation(Route $route): bool
     {
-        if (false === $this->options['with_annotation']) {
+        if (false === $this->options['with_annotation'] && false === $this->options['with_attribute']) {
             return true;
         }
 

diff --git a/tests/DependencyInjection/ConfigurationTest.php b/tests/DependencyInjection/ConfigurationTest.php
@@ -38,6 +38,7 @@ public function testDefaultArea(): void
                     'host_patterns' => [],
                     'name_patterns' => [],
                     'with_annotation' => false,
+                    'with_attribute' => false,
                     'disable_default_routes' => false,
                     'documentation' => [],
                 ],
@@ -53,6 +54,7 @@ public function testAreas(): void
                 'path_patterns' => ['/foo'],
                 'host_patterns' => [],
                 'with_annotation' => false,
+                'with_attribute' => false,
                 'documentation' => [],
                 'name_patterns' => [],
                 'disable_default_routes' => false,
@@ -61,6 +63,7 @@ public function testAreas(): void
                 'path_patterns' => ['/internal'],
                 'host_patterns' => ['^swagger\.'],
                 'with_annotation' => false,
+                'with_attribute' => false,
                 'documentation' => [],
                 'name_patterns' => [],
                 'disable_default_routes' => false,
@@ -69,6 +72,7 @@ public function testAreas(): void
                 'path_patterns' => ['/internal'],
                 'host_patterns' => [],
                 'with_annotation' => false,
+                'with_attribute' => false,
                 'documentation' => [],
                 'name_patterns' => [],
                 'disable_default_routes' => false,

diff --git a/tests/Routing/FilteredRouteCollectionBuilderTest.php b/tests/Routing/FilteredRouteCollectionBuilderTest.php
@@ -124,6 +124,7 @@ public static function getInvalidOptions(): \Generator
         yield [['path_patterns' => [new \stdClass()]]];
         yield [['path_patterns' => ['^/foo$', 1]]];
         yield [['with_annotation' => ['an array']]];
+        yield [['with_attribute' => ['an array']]];
         yield [['path_patterns' => 'a string']];
         yield [['path_patterns' => 11]];
         yield [['name_patterns' => 22]];
@@ -230,30 +231,50 @@ public function testMatchingRoutesWithAnnotation(string $name, Route $route, arr
     public static function getMatchingRoutesWithAnnotation(): \Generator
     {
         yield from [
-            'with annotation only' => [
+            'with annotation only, deprecated' => [
                 'r10',
                 new Route('/api/areas/new', ['_controller' => 'ApiController::newAreaAction']),
                 ['with_annotation' => true],
             ],
-            'with annotation and path patterns' => [
+            'with annotation only' => [
+                'r10',
+                new Route('/api/areas/new', ['_controller' => 'ApiController::newAreaAction']),
+                ['with_attribute' => true],
+            ],
+            'with annotation and path patterns, deprecated' => [
                 'r10',
                 new Route('/api/areas/new', ['_controller' => 'ApiController::newAreaAction']),
                 ['path_patterns' => ['^/api'], 'with_annotation' => true],
             ],
+            'with annotation and path patterns' => [
+                'r10',
+                new Route('/api/areas/new', ['_controller' => 'ApiController::newAreaAction']),
+                ['path_patterns' => ['^/api'], 'with_attribute' => true],
+            ],
         ];
 
         if (\PHP_VERSION_ID < 80000) {
             yield from [
-                'with attribute only' => [
+                'with attribute only, deprecated' => [
                     'r10',
                     new Route('/api/areas_attributes/new', ['_controller' => 'ApiController::newAreaActionAttributes']),
                     ['with_annotation' => true],
                 ],
-                'with attribute and path patterns' => [
+                'with attribute only' => [
+                    'r10',
+                    new Route('/api/areas_attributes/new', ['_controller' => 'ApiController::newAreaActionAttributes']),
+                    ['with_attribute' => true],
+                ],
+                'with attribute and path patterns, deprecated' => [
                     'r10',
                     new Route('/api/areas_attributes/new', ['_controller' => 'ApiController::newAreaActionAttributes']),
                     ['path_patterns' => ['^/api'], 'with_annotation' => true],
                 ],
+                'with attribute and path patterns' => [
+                    'r10',
+                    new Route('/api/areas_attributes/new', ['_controller' => 'ApiController::newAreaActionAttributes']),
+                    ['path_patterns' => ['^/api'], 'with_attribute' => true],
+                ],
             ];
         }
     }