Skip to content

Commit bc5a76d

Browse files
derrabusderrabus
committed
Merge branch '6.4' into 7.0
* 6.4: [Routing] Deprecate annotations in favor of attributes
2 parents f4a020f + 9cd2a7b commit bc5a76d

12 files changed

+202
-227
lines changed

‎CHANGELOG.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ CHANGELOG
1111

1212
* Add FQCN and FQCN::method aliases for routes loaded from attributes/annotations when applicable
1313
* Add native return type to `AnnotationClassLoader::setResolver()`
14+
* Deprecate Doctrine annotations support in favor of native attributes
15+
* Change the constructor signature of `AnnotationClassLoader` to `__construct(?string $env = null)`, passing an annotation reader as first argument is deprecated
1416

1517
6.2
1618
---

‎Loader/AnnotationClassLoader.php

Lines changed: 73 additions & 58 deletions
Original file line numberDiff line numberDiff line change
@@ -26,33 +26,14 @@
2626
* time, this method should define some PHP callable to be called for the route
2727
* (a controller in MVC speak).
2828
*
29-
* The @Route annotation can be set on the class (for global parameters),
29+
* The #[Route] attribute can be set on the class (for global parameters),
3030
* and on each method.
3131
*
32-
* The @Route annotation main value is the route path. The annotation also
32+
* The #[Route] attribute main value is the route path. The attribute also
3333
* recognizes several parameters: requirements, options, defaults, schemes,
3434
* methods, host, and name. The name parameter is mandatory.
3535
* Here is an example of how you should be able to use it:
36-
* /**
37-
* * @Route("/Blog")
38-
* * /
39-
* class Blog
40-
* {
41-
* /**
42-
* * @Route("/", name="blog_index")
43-
* * /
44-
* public function index()
45-
* {
46-
* }
47-
* /**
48-
* * @Route("/{id}", name="blog_post", requirements = {"id" = "\d+"})
49-
* * /
50-
* public function show()
51-
* {
52-
* }
53-
* }
5436
*
55-
* On PHP 8, the annotation class can be used as an attribute as well:
5637
* #[Route('/Blog')]
5738
* class Blog
5839
* {
@@ -71,7 +52,16 @@
7152
*/
7253
abstract class AnnotationClassLoader implements LoaderInterface
7354
{
55+
/**
56+
* @var Reader|null
57+
*
58+
* @deprecated in Symfony 6.4, this property will be removed in Symfony 7.
59+
*/
7460
protected $reader;
61+
62+
/**
63+
* @var string|null
64+
*/
7565
protected $env;
7666

7767
/**
@@ -84,10 +74,27 @@ abstract class AnnotationClassLoader implements LoaderInterface
8474
*/
8575
protected $defaultRouteIndex = 0;
8676

87-
public function __construct(Reader $reader = null, string $env = null)
77+
private bool $hasDeprecatedAnnotations = false;
78+
79+
/**
80+
* @param string|null $env
81+
*/
82+
public function __construct($env = null)
8883
{
89-
$this->reader = $reader;
90-
$this->env = $env;
84+
if ($env instanceof Reader || null === $env && \func_num_args() > 1 && null !== func_get_arg(1)) {
85+
trigger_deprecation('symfony/routing', '6.4', 'Passing an instance of "%s" as first and the environment as second argument to "%s" is deprecated. Pass the environment as first argument instead.', Reader::class, __METHOD__);
86+
87+
$this->reader = $env;
88+
$env = \func_num_args() > 1 ? func_get_arg(1) : null;
89+
}
90+
91+
if (\is_string($env) || null === $env) {
92+
$this->env = $env;
93+
} elseif ($env instanceof \Stringable || \is_scalar($env)) {
94+
$this->env = (string) $env;
95+
} else {
96+
throw new \TypeError(__METHOD__.sprintf(': Parameter $env was expected to be a string or null, "%s" given.', get_debug_type($env)));
97+
}
9198
}
9299

93100
/**
@@ -114,43 +121,48 @@ public function load(mixed $class, string $type = null): RouteCollection
114121
throw new \InvalidArgumentException(sprintf('Annotations from class "%s" cannot be read as it is abstract.', $class->getName()));
115122
}
116123

117-
$globals = $this->getGlobals($class);
118-
119-
$collection = new RouteCollection();
120-
$collection->addResource(new FileResource($class->getFileName()));
124+
$this->hasDeprecatedAnnotations = false;
121125

122-
if ($globals['env'] && $this->env !== $globals['env']) {
123-
return $collection;
124-
}
126+
try {
127+
$globals = $this->getGlobals($class);
128+
$collection = new RouteCollection();
129+
$collection->addResource(new FileResource($class->getFileName()));
130+
if ($globals['env'] && $this->env !== $globals['env']) {
131+
return $collection;
132+
}
133+
$fqcnAlias = false;
134+
foreach ($class->getMethods() as $method) {
135+
$this->defaultRouteIndex = 0;
136+
$routeNamesBefore = array_keys($collection->all());
137+
foreach ($this->getAnnotations($method) as $annot) {
138+
$this->addRoute($collection, $annot, $globals, $class, $method);
139+
if ('__invoke' === $method->name) {
140+
$fqcnAlias = true;
141+
}
142+
}
125143

126-
$fqcnAlias = false;
127-
foreach ($class->getMethods() as $method) {
128-
$this->defaultRouteIndex = 0;
129-
$routeNamesBefore = array_keys($collection->all());
130-
foreach ($this->getAnnotations($method) as $annot) {
131-
$this->addRoute($collection, $annot, $globals, $class, $method);
132-
if ('__invoke' === $method->name) {
144+
if (1 === $collection->count() - \count($routeNamesBefore)) {
145+
$newRouteName = current(array_diff(array_keys($collection->all()), $routeNamesBefore));
146+
$collection->addAlias(sprintf('%s::%s', $class->name, $method->name), $newRouteName);
147+
}
148+
}
149+
if (0 === $collection->count() && $class->hasMethod('__invoke')) {
150+
$globals = $this->resetGlobals();
151+
foreach ($this->getAnnotations($class) as $annot) {
152+
$this->addRoute($collection, $annot, $globals, $class, $class->getMethod('__invoke'));
133153
$fqcnAlias = true;
134154
}
135155
}
136-
137-
if (1 === $collection->count() - \count($routeNamesBefore)) {
138-
$newRouteName = current(array_diff(array_keys($collection->all()), $routeNamesBefore));
139-
$collection->addAlias(sprintf('%s::%s', $class->name, $method->name), $newRouteName);
156+
if ($fqcnAlias && 1 === $collection->count()) {
157+
$collection->addAlias($class->name, $invokeRouteName = key($collection->all()));
158+
$collection->addAlias(sprintf('%s::__invoke', $class->name), $invokeRouteName);
140159
}
141-
}
142160

143-
if (0 === $collection->count() && $class->hasMethod('__invoke')) {
144-
$globals = $this->resetGlobals();
145-
foreach ($this->getAnnotations($class) as $annot) {
146-
$this->addRoute($collection, $annot, $globals, $class, $class->getMethod('__invoke'));
147-
$fqcnAlias = true;
161+
if ($this->hasDeprecatedAnnotations) {
162+
trigger_deprecation('symfony/routing', '6.4', 'Class "%s" uses Doctrine Annotations to configure routes, which is deprecated. Use PHP attributes instead.', $class->getName());
148163
}
149-
}
150-
151-
if ($fqcnAlias && 1 === $collection->count()) {
152-
$collection->addAlias($class->name, $invokeRouteName = key($collection->all()));
153-
$collection->addAlias(sprintf('%s::__invoke', $class->name), $invokeRouteName);
164+
} finally {
165+
$this->hasDeprecatedAnnotations = false;
154166
}
155167

156168
return $collection;
@@ -272,6 +284,9 @@ protected function getDefaultRouteName(\ReflectionClass $class, \ReflectionMetho
272284
return $name;
273285
}
274286

287+
/**
288+
* @return array<string, mixed>
289+
*/
275290
protected function getGlobals(\ReflectionClass $class): array
276291
{
277292
$globals = $this->resetGlobals();
@@ -280,8 +295,8 @@ protected function getGlobals(\ReflectionClass $class): array
280295
if ($attribute = $class->getAttributes($this->routeAnnotationClass, \ReflectionAttribute::IS_INSTANCEOF)[0] ?? null) {
281296
$annot = $attribute->newInstance();
282297
}
283-
if (!$annot && $this->reader) {
284-
$annot = $this->reader->getClassAnnotation($class, $this->routeAnnotationClass);
298+
if (!$annot && $annot = $this->reader?->getClassAnnotation($class, $this->routeAnnotationClass)) {
299+
$this->hasDeprecatedAnnotations = true;
285300
}
286301

287302
if ($annot) {
@@ -365,11 +380,9 @@ protected function createRoute(string $path, array $defaults, array $requirement
365380
abstract protected function configureRoute(Route $route, \ReflectionClass $class, \ReflectionMethod $method, object $annot);
366381

367382
/**
368-
* @param \ReflectionClass|\ReflectionMethod $reflection
369-
*
370383
* @return iterable<int, RouteAnnotation>
371384
*/
372-
private function getAnnotations(object $reflection): iterable
385+
private function getAnnotations(\ReflectionClass|\ReflectionMethod $reflection): iterable
373386
{
374387
foreach ($reflection->getAttributes($this->routeAnnotationClass, \ReflectionAttribute::IS_INSTANCEOF) as $attribute) {
375388
yield $attribute->newInstance();
@@ -385,6 +398,8 @@ private function getAnnotations(object $reflection): iterable
385398

386399
foreach ($annotations as $annotation) {
387400
if ($annotation instanceof $this->routeAnnotationClass) {
401+
$this->hasDeprecatedAnnotations = true;
402+
388403
yield $annotation;
389404
}
390405
}

‎Tests/Fixtures/AnnotatedClasses/AbstractClass.php

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,13 @@
1111

1212
namespace Symfony\Component\Routing\Tests\Fixtures\AnnotatedClasses;
1313

14+
use Symfony\Component\Routing\Annotation\Route;
15+
1416
abstract class AbstractClass
1517
{
1618
abstract public function abstractRouteAction();
1719

20+
#[Route('/path/to/route/{arg1}')]
1821
public function routeAction($arg1, $arg2 = 'defaultValue2', $arg3 = 'defaultValue3')
1922
{
2023
}

‎Tests/Fixtures/OtherAnnotatedClasses/VariadicClass.php

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,11 @@
1111

1212
namespace Symfony\Component\Routing\Tests\Fixtures\OtherAnnotatedClasses;
1313

14+
use Symfony\Component\Routing\Annotation\Route;
15+
1416
class VariadicClass
1517
{
18+
#[Route('/path/to/{id}')]
1619
public function routeAction(...$params)
1720
{
1821
}

‎Tests/Fixtures/TraceableAnnotationClassLoader.php

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
<?php
2+
3+
/*
4+
* This file is part of the Symfony package.
5+
*
6+
* (c) Fabien Potencier <[email protected]>
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*/
11+
12+
namespace Symfony\Component\Routing\Tests\Fixtures;
13+
14+
use Symfony\Component\Routing\Loader\AnnotationClassLoader;
15+
use Symfony\Component\Routing\Route;
16+
use Symfony\Component\Routing\RouteCollection;
17+
18+
final class TraceableAnnotationClassLoader extends AnnotationClassLoader
19+
{
20+
/** @var list<string> */
21+
public array $foundClasses = [];
22+
23+
public function load(mixed $class, string $type = null): RouteCollection
24+
{
25+
if (!is_string($class)) {
26+
throw new \InvalidArgumentException(sprintf('Expected string, got "%s"', get_debug_type($class)));
27+
}
28+
29+
$this->foundClasses[] = $class;
30+
31+
return parent::load($class, $type);
32+
}
33+
34+
protected function configureRoute(Route $route, \ReflectionClass $class, \ReflectionMethod $method, object $annot): void
35+
{
36+
}
37+
}

‎Tests/Loader/AbstractAnnotationLoaderTestCase.php

Lines changed: 0 additions & 34 deletions
This file was deleted.

‎Tests/Loader/AnnotationClassLoaderTestCase.php

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -18,10 +18,7 @@
1818

1919
abstract class AnnotationClassLoaderTestCase extends TestCase
2020
{
21-
/**
22-
* @var AnnotationClassLoader
23-
*/
24-
protected $loader;
21+
protected AnnotationClassLoader $loader;
2522

2623
/**
2724
* @dataProvider provideTestSupportsChecksResource
@@ -31,7 +28,7 @@ public function testSupportsChecksResource($resource, $expectedSupports)
3128
$this->assertSame($expectedSupports, $this->loader->supports($resource), '->supports() returns true if the resource is loadable');
3229
}
3330

34-
public static function provideTestSupportsChecksResource()
31+
public static function provideTestSupportsChecksResource(): array
3532
{
3633
return [
3734
['class', true],

‎Tests/Loader/AnnotationClassLoaderWithAnnotationsTest.php

Lines changed: 5 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -12,19 +12,17 @@
1212
namespace Symfony\Component\Routing\Tests\Loader;
1313

1414
use Doctrine\Common\Annotations\AnnotationReader;
15-
use Symfony\Component\Routing\Loader\AnnotationClassLoader;
16-
use Symfony\Component\Routing\Route;
15+
use Symfony\Component\Routing\Tests\Fixtures\TraceableAnnotationClassLoader;
1716

17+
/**
18+
* @group legacy
19+
*/
1820
class AnnotationClassLoaderWithAnnotationsTest extends AnnotationClassLoaderTestCase
1921
{
2022
protected function setUp(string $env = null): void
2123
{
2224
$reader = new AnnotationReader();
23-
$this->loader = new class($reader, $env) extends AnnotationClassLoader {
24-
protected function configureRoute(Route $route, \ReflectionClass $class, \ReflectionMethod $method, object $annot): void
25-
{
26-
}
27-
};
25+
$this->loader = new TraceableAnnotationClassLoader($reader, $env);
2826
}
2927

3028
public function testDefaultRouteName()

‎Tests/Loader/AnnotationClassLoaderWithAttributesTest.php

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -11,18 +11,13 @@
1111

1212
namespace Symfony\Component\Routing\Tests\Loader;
1313

14-
use Symfony\Component\Routing\Loader\AnnotationClassLoader;
15-
use Symfony\Component\Routing\Route;
14+
use Symfony\Component\Routing\Tests\Fixtures\TraceableAnnotationClassLoader;
1615

1716
class AnnotationClassLoaderWithAttributesTest extends AnnotationClassLoaderTestCase
1817
{
1918
protected function setUp(string $env = null): void
2019
{
21-
$this->loader = new class(null, $env) extends AnnotationClassLoader {
22-
protected function configureRoute(Route $route, \ReflectionClass $class, \ReflectionMethod $method, object $annot): void
23-
{
24-
}
25-
};
20+
$this->loader = new TraceableAnnotationClassLoader($env);
2621
}
2722

2823
public function testDefaultRouteName()

0 commit comments

Comments
 (0)