vendor/symfony/routing/Loader/AttributeClassLoader.php line 86

  1. <?php
  3. /*
  4.  * This file is part of the Symfony package.
  5.  *
  6.  * (c) Fabien Potencier <fabien@symfony.com>
  7.  *
  8.  * For the full copyright and license information, please view the LICENSE
  9.  * file that was distributed with this source code.
  10.  */
  12. namespace Symfony\Component\Routing\Loader;
  14. use Doctrine\Common\Annotations\Reader;
  15. use Symfony\Component\Config\Loader\LoaderInterface;
  16. use Symfony\Component\Config\Loader\LoaderResolverInterface;
  17. use Symfony\Component\Config\Resource\FileResource;
  18. use Symfony\Component\Routing\Attribute\Route as RouteAnnotation;
  19. use Symfony\Component\Routing\Route;
  20. use Symfony\Component\Routing\RouteCollection;
  22. /**
  23.  * AttributeClassLoader loads routing information from a PHP class and its methods.
  24.  *
  25.  * You need to define an implementation for the configureRoute() method. Most of the
  26.  * time, this method should define some PHP callable to be called for the route
  27.  * (a controller in MVC speak).
  28.  *
  29.  * The #[Route] attribute can be set on the class (for global parameters),
  30.  * and on each method.
  31.  *
  32.  * The #[Route] attribute main value is the route path. The attribute also
  33.  * recognizes several parameters: requirements, options, defaults, schemes,
  34.  * methods, host, and name. The name parameter is mandatory.
  35.  * Here is an example of how you should be able to use it:
  36.  *
  37.  *     #[Route('/Blog')]
  38.  *     class Blog
  39.  *     {
  40.  *         #[Route('/', name: 'blog_index')]
  41.  *         public function index()
  42.  *         {
  43.  *         }
  44.  *         #[Route('/{id}', name: 'blog_post', requirements: ["id" => '\d+'])]
  45.  *         public function show()
  46.  *         {
  47.  *         }
  48.  *     }
  49.  *
  50.  * @author Fabien Potencier <fabien@symfony.com>
  51.  * @author Alexander M. Turek <me@derrabus.de>
  52.  * @author Alexandre Daubois <alex.daubois@gmail.com>
  53.  */
  54. abstract class AttributeClassLoader implements LoaderInterface
  55. {
  56.     /**
  57.      * @var Reader|null
  58.      *
  59.      * @deprecated in Symfony 6.4, this property will be removed in Symfony 7.
  60.      */
  61.     protected $reader;
  63.     /**
  64.      * @var string|null
  65.      */
  66.     protected $env;
  68.     /**
  69.      * @var string
  70.      */
  71.     protected $routeAnnotationClass = RouteAnnotation::class;
  73.     /**
  74.      * @var int
  75.      */
  76.     protected $defaultRouteIndex = 0;
  78.     private bool $hasDeprecatedAnnotations = false;
  80.     /**
  81.      * @param string|null $env
  82.      */
  83.     public function __construct($env = null)
  84.     {
  85.         if ($env instanceof Reader || null === $env && \func_num_args() > 1 && null !== func_get_arg(1)) {
  86.             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__);
  88.             $this->reader = $env;
  89.             $env = \func_num_args() > 1 ? func_get_arg(1) : null;
  90.         }
  92.         if (\is_string($env) || null === $env) {
  93.             $this->env = $env;
  94.         } elseif ($env instanceof \Stringable || \is_scalar($env)) {
  95.             $this->env = (string) $env;
  96.         } else {
  97.             throw new \TypeError(__METHOD__.sprintf(': Parameter $env was expected to be a string or null, "%s" given.', get_debug_type($env)));
  98.         }
  99.     }
  101.     /**
  102.      * Sets the annotation class to read route properties from.
  103.      *
  104.      * @return void
  105.      */
  106.     public function setRouteAnnotationClass(string $class)
  107.     {
  108.         $this->routeAnnotationClass = $class;
  109.     }
  111.     /**
  112.      * @throws \InvalidArgumentException When route can't be parsed
  113.      */
  114.     public function load(mixed $class, ?string $type = null): RouteCollection
  115.     {
  116.         if (!class_exists($class)) {
  117.             throw new \InvalidArgumentException(sprintf('Class "%s" does not exist.', $class));
  118.         }
  120.         $class = new \ReflectionClass($class);
  121.         if ($class->isAbstract()) {
  122.             throw new \InvalidArgumentException(sprintf('Attributes from class "%s" cannot be read as it is abstract.', $class->getName()));
  123.         }
  125.         $this->hasDeprecatedAnnotations = false;
  127.         try {
  128.             $globals = $this->getGlobals($class);
  129.             $collection = new RouteCollection();
  130.             $collection->addResource(new FileResource($class->getFileName()));
  131.             if ($globals['env'] && $this->env !== $globals['env']) {
  132.                 return $collection;
  133.             }
  134.             $fqcnAlias = false;
  135.             foreach ($class->getMethods() as $method) {
  136.                 $this->defaultRouteIndex = 0;
  137.                 $routeNamesBefore = array_keys($collection->all());
  138.                 foreach ($this->getAnnotations($method) as $annot) {
  139.                     $this->addRoute($collection, $annot, $globals, $class, $method);
  140.                     if ('__invoke' === $method->name) {
  141.                         $fqcnAlias = true;
  142.                     }
  143.                 }
  145.                 if (1 === $collection->count() - \count($routeNamesBefore)) {
  146.                     $newRouteName = current(array_diff(array_keys($collection->all()), $routeNamesBefore));
  147.                     if ($newRouteName !== $aliasName = sprintf('%s::%s', $class->name, $method->name)) {
  148.                         $collection->addAlias($aliasName, $newRouteName);
  149.                     }
  150.                 }
  151.             }
  152.             if (0 === $collection->count() && $class->hasMethod('__invoke')) {
  153.                 $globals = $this->resetGlobals();
  154.                 foreach ($this->getAnnotations($class) as $annot) {
  155.                     $this->addRoute($collection, $annot, $globals, $class, $class->getMethod('__invoke'));
  156.                     $fqcnAlias = true;
  157.                 }
  158.             }
  159.             if ($fqcnAlias && 1 === $collection->count()) {
  160.                 $invokeRouteName = key($collection->all());
  161.                 if ($invokeRouteName !== $class->name) {
  162.                     $collection->addAlias($class->name, $invokeRouteName);
  163.                 }
  165.                 if ($invokeRouteName !== $aliasName = sprintf('%s::__invoke', $class->name)) {
  166.                     $collection->addAlias($aliasName, $invokeRouteName);
  167.                 }
  168.             }
  170.             if ($this->hasDeprecatedAnnotations) {
  171.                 trigger_deprecation('symfony/routing', '6.4', 'Class "%s" uses Doctrine Annotations to configure routes, which is deprecated. Use PHP attributes instead.', $class->getName());
  172.             }
  173.         } finally {
  174.             $this->hasDeprecatedAnnotations = false;
  175.         }
  177.         return $collection;
  178.     }
  180.     /**
  181.      * @param RouteAnnotation $annot or an object that exposes a similar interface
  182.      *
  183.      * @return void
  184.      */
  185.     protected function addRoute(RouteCollection $collection, object $annot, array $globals, \ReflectionClass $class, \ReflectionMethod $method)
  186.     {
  187.         if ($annot->getEnv() && $annot->getEnv() !== $this->env) {
  188.             return;
  189.         }
  191.         $name = $annot->getName() ?? $this->getDefaultRouteName($class, $method);
  192.         $name = $globals['name'].$name;
  194.         $requirements = $annot->getRequirements();
  196.         foreach ($requirements as $placeholder => $requirement) {
  197.             if (\is_int($placeholder)) {
  198.                 throw new \InvalidArgumentException(sprintf('A placeholder name must be a string (%d given). Did you forget to specify the placeholder key for the requirement "%s" of route "%s" in "%s::%s()"?', $placeholder, $requirement, $name, $class->getName(), $method->getName()));
  199.             }
  200.         }
  202.         $defaults = array_replace($globals['defaults'], $annot->getDefaults());
  203.         $requirements = array_replace($globals['requirements'], $requirements);
  204.         $options = array_replace($globals['options'], $annot->getOptions());
  205.         $schemes = array_unique(array_merge($globals['schemes'], $annot->getSchemes()));
  206.         $methods = array_unique(array_merge($globals['methods'], $annot->getMethods()));
  208.         $host = $annot->getHost() ?? $globals['host'];
  209.         $condition = $annot->getCondition() ?? $globals['condition'];
  210.         $priority = $annot->getPriority() ?? $globals['priority'];
  212.         $path = $annot->getLocalizedPaths() ?: $annot->getPath();
  213.         $prefix = $globals['localized_paths'] ?: $globals['path'];
  214.         $paths = [];
  216.         if (\is_array($path)) {
  217.             if (!\is_array($prefix)) {
  218.                 foreach ($path as $locale => $localePath) {
  219.                     $paths[$locale] = $prefix.$localePath;
  220.                 }
  221.             } elseif ($missing = array_diff_key($prefix, $path)) {
  222.                 throw new \LogicException(sprintf('Route to "%s" is missing paths for locale(s) "%s".', $class->name.'::'.$method->name, implode('", "', array_keys($missing))));
  223.             } else {
  224.                 foreach ($path as $locale => $localePath) {
  225.                     if (!isset($prefix[$locale])) {
  226.                         throw new \LogicException(sprintf('Route to "%s" with locale "%s" is missing a corresponding prefix in class "%s".', $method->name, $locale, $class->name));
  227.                     }
  229.                     $paths[$locale] = $prefix[$locale].$localePath;
  230.                 }
  231.             }
  232.         } elseif (\is_array($prefix)) {
  233.             foreach ($prefix as $locale => $localePrefix) {
  234.                 $paths[$locale] = $localePrefix.$path;
  235.             }
  236.         } else {
  237.             $paths[] = $prefix.$path;
  238.         }
  240.         foreach ($method->getParameters() as $param) {
  241.             if (isset($defaults[$param->name]) || !$param->isDefaultValueAvailable()) {
  242.                 continue;
  243.             }
  244.             foreach ($paths as $locale => $path) {
  245.                 if (preg_match(sprintf('/\{%s(?:<.*?>)?\}/', preg_quote($param->name)), $path)) {
  246.                     if (\is_scalar($defaultValue = $param->getDefaultValue()) || null === $defaultValue) {
  247.                         $defaults[$param->name] = $defaultValue;
  248.                     } elseif ($defaultValue instanceof \BackedEnum) {
  249.                         $defaults[$param->name] = $defaultValue->value;
  250.                     }
  251.                     break;
  252.                 }
  253.             }
  254.         }
  256.         foreach ($paths as $locale => $path) {
  257.             $route = $this->createRoute($path, $defaults, $requirements, $options, $host, $schemes, $methods, $condition);
  258.             $this->configureRoute($route, $class, $method, $annot);
  259.             if (0 !== $locale) {
  260.                 $route->setDefault('_locale', $locale);
  261.                 $route->setRequirement('_locale', preg_quote($locale));
  262.                 $route->setDefault('_canonical_route', $name);
  263.                 $collection->add($name.'.'.$locale, $route, $priority);
  264.             } else {
  265.                 $collection->add($name, $route, $priority);
  266.             }
  267.         }
  268.     }
  270.     public function supports(mixed $resource, ?string $type = null): bool
  271.     {
  272.         if ('annotation' === $type) {
  273.             trigger_deprecation('symfony/routing', '6.4', 'The "annotation" route type is deprecated, use the "attribute" route type instead.');
  274.         }
  276.         return \is_string($resource) && preg_match('/^(?:\\\\?[a-zA-Z_\x7f-\xff][a-zA-Z0-9_\x7f-\xff]*)+$/', $resource) && (!$type || \in_array($type, ['annotation', 'attribute'], true));
  277.     }
  279.     public function setResolver(LoaderResolverInterface $resolver): void
  280.     {
  281.     }
  283.     public function getResolver(): LoaderResolverInterface
  284.     {
  285.     }
  287.     /**
  288.      * Gets the default route name for a class method.
  289.      *
  290.      * @return string
  291.      */
  292.     protected function getDefaultRouteName(\ReflectionClass $class, \ReflectionMethod $method)
  293.     {
  294.         $name = str_replace('\\', '_', $class->name).'_'.$method->name;
  295.         $name = \function_exists('mb_strtolower') && preg_match('//u', $name) ? mb_strtolower($name, 'UTF-8') : strtolower($name);
  296.         if ($this->defaultRouteIndex > 0) {
  297.             $name .= '_'.$this->defaultRouteIndex;
  298.         }
  299.         ++$this->defaultRouteIndex;
  301.         return $name;
  302.     }
  304.     /**
  305.      * @return array<string, mixed>
  306.      */
  307.     protected function getGlobals(\ReflectionClass $class)
  308.     {
  309.         $globals = $this->resetGlobals();
  311.         $annot = null;
  312.         if ($attribute = $class->getAttributes($this->routeAnnotationClass, \ReflectionAttribute::IS_INSTANCEOF)[0] ?? null) {
  313.             $annot = $attribute->newInstance();
  314.         }
  315.         if (!$annot && $annot = $this->reader?->getClassAnnotation($class, $this->routeAnnotationClass)) {
  316.             $this->hasDeprecatedAnnotations = true;
  317.         }
  319.         if ($annot) {
  320.             if (null !== $annot->getName()) {
  321.                 $globals['name'] = $annot->getName();
  322.             }
  324.             if (null !== $annot->getPath()) {
  325.                 $globals['path'] = $annot->getPath();
  326.             }
  328.             $globals['localized_paths'] = $annot->getLocalizedPaths();
  330.             if (null !== $annot->getRequirements()) {
  331.                 $globals['requirements'] = $annot->getRequirements();
  332.             }
  334.             if (null !== $annot->getOptions()) {
  335.                 $globals['options'] = $annot->getOptions();
  336.             }
  338.             if (null !== $annot->getDefaults()) {
  339.                 $globals['defaults'] = $annot->getDefaults();
  340.             }
  342.             if (null !== $annot->getSchemes()) {
  343.                 $globals['schemes'] = $annot->getSchemes();
  344.             }
  346.             if (null !== $annot->getMethods()) {
  347.                 $globals['methods'] = $annot->getMethods();
  348.             }
  350.             if (null !== $annot->getHost()) {
  351.                 $globals['host'] = $annot->getHost();
  352.             }
  354.             if (null !== $annot->getCondition()) {
  355.                 $globals['condition'] = $annot->getCondition();
  356.             }
  358.             $globals['priority'] = $annot->getPriority() ?? 0;
  359.             $globals['env'] = $annot->getEnv();
  361.             foreach ($globals['requirements'] as $placeholder => $requirement) {
  362.                 if (\is_int($placeholder)) {
  363.                     throw new \InvalidArgumentException(sprintf('A placeholder name must be a string (%d given). Did you forget to specify the placeholder key for the requirement "%s" in "%s"?', $placeholder, $requirement, $class->getName()));
  364.                 }
  365.             }
  366.         }
  368.         return $globals;
  369.     }
  371.     private function resetGlobals(): array
  372.     {
  373.         return [
  374.             'path' => null,
  375.             'localized_paths' => [],
  376.             'requirements' => [],
  377.             'options' => [],
  378.             'defaults' => [],
  379.             'schemes' => [],
  380.             'methods' => [],
  381.             'host' => '',
  382.             'condition' => '',
  383.             'name' => '',
  384.             'priority' => 0,
  385.             'env' => null,
  386.         ];
  387.     }
  389.     /**
  390.      * @return Route
  391.      */
  392.     protected function createRoute(string $path, array $defaults, array $requirements, array $options, ?string $host, array $schemes, array $methods, ?string $condition)
  393.     {
  394.         return new Route($path, $defaults, $requirements, $options, $host, $schemes, $methods, $condition);
  395.     }
  397.     /**
  398.      * @return void
  399.      */
  400.     abstract protected function configureRoute(Route $route, \ReflectionClass $class, \ReflectionMethod $method, object $annot);
  402.     /**
  403.      * @return iterable<int, RouteAnnotation>
  404.      */
  405.     private function getAnnotations(\ReflectionClass|\ReflectionMethod $reflection): iterable
  406.     {
  407.         foreach ($reflection->getAttributes($this->routeAnnotationClass, \ReflectionAttribute::IS_INSTANCEOF) as $attribute) {
  408.             yield $attribute->newInstance();
  409.         }
  411.         if (!$this->reader) {
  412.             return;
  413.         }
  415.         $annotations = $reflection instanceof \ReflectionClass
  416.             ? $this->reader->getClassAnnotations($reflection)
  417.             : $this->reader->getMethodAnnotations($reflection);
  419.         foreach ($annotations as $annotation) {
  420.             if ($annotation instanceof $this->routeAnnotationClass) {
  421.                 $this->hasDeprecatedAnnotations = true;
  423.                 yield $annotation;
  424.             }
  425.         }
  426.     }
  427. }
  429. if (!class_exists(AnnotationClassLoader::class, false)) {
  430.     class_alias(AttributeClassLoader::class, AnnotationClassLoader::class);
  431. }