FEATURE: Add Flow\Route Attribute/Annotation

Neos.Flow/Classes/Annotations/Route.php

@@ -0,0 +1,51 @@
+<?php
+declare(strict_types=1);
+
+namespace Neos\Flow\Annotations;
+
+/*
+ * This file is part of the Neos.Flow package.
+ *
+ * (c) Contributors of the Neos Project - www.neos.io
+ *
+ * This package is Open Source Software. For the full copyright and license
+ * information, please view the LICENSE file which was distributed with this
+ * source code.
+ */
+
+use Doctrine\Common\Annotations\Annotation\NamedArgumentConstructor;
+
+/**
+ * Adds a route configuration to a method
+ *
+ * This is a convenient way to add routes in project code
+ * but should not be used in libraries/packages that shall be
+ * configured for different use cases.
+ *
+ * @Annotation
+ * @NamedArgumentConstructor
+ * @Target({"METHOD"})
+ */
+#[\Attribute(\Attribute::TARGET_METHOD | \Attribute::IS_REPEATABLE)]
+final class Route
+{
+    /**
+     * @param string $uriPattern The uri-pattern for the route without leading '/'. Must not contain `{@action}` or `{@controller}`.
+     * @param string|null $name (default null) The name ouf the route as it shows up in the route:list command
+     * @param array $httpMethods (default []) List of http verbs like 'GET', 'POST', 'PUT', 'DELETE', if not specified 'any' is used
+     * @param array $defaults (default []) Values to set for this route. Dan define arguments but also specify the `@format` if required.
+     */
+    public function __construct(
+        public readonly string $uriPattern,
+        public readonly ?string $name = null,
+        public readonly array $httpMethods = [],
+        public readonly array $defaults = [],
+    ) {
+        if (str_contains($uriPattern, '{@controller}') || str_contains($uriPattern, '{@action}')) {
+            throw new \DomainException(sprintf('It is not allowed to override {@controller} or {@action} in route annotations "%s"', $uriPattern), 1711129634);
+        }
+        if (in_array(array_keys($defaults), ['@package', '@subpackage', '@controller', '@action'])) {
+            throw new \DomainException(sprintf('It is not allowed to override @package, @controller, @subpackage and @action in route annotation defaults "%s"', $uriPattern), 1711129638);
+        }
+    }
+}

Neos.Flow/Classes/Configuration/Loader/RoutesLoader.php

@@ -84,20 +84,28 @@ public function load(array $packages, ApplicationContext $context): array
     protected function includeSubRoutesFromSettings(array $routeDefinitions, array $routeSettings): array
     {
         $sortedRouteSettings = (new PositionalArraySorter($routeSettings))->toArray();
-        foreach ($sortedRouteSettings as $packageKey => $routeFromSettings) {
+        foreach ($sortedRouteSettings as $configurationKey => $routeFromSettings) {
             if ($routeFromSettings === false) {
                 continue;
             }
-            $subRoutesName = $packageKey . 'SubRoutes';
-            $subRoutesConfiguration = ['package' => $packageKey];
+            if (isset($routeFromSettings['providerFactory'])) {
+                $routeDefinitions[] = [
+                    'name' => $configurationKey,
+                    'providerFactory' => $routeFromSettings['providerFactory'],
+                    'providerOptions' => $routeFromSettings['providerOptions'] ?? [],
+                ];
+                continue;
+            }
+            $subRoutesName = $configurationKey . 'SubRoutes';
+            $subRoutesConfiguration = ['package' => $configurationKey];
             if (isset($routeFromSettings['variables'])) {
                 $subRoutesConfiguration['variables'] = $routeFromSettings['variables'];
             }
             if (isset($routeFromSettings['suffix'])) {
                 $subRoutesConfiguration['suffix'] = $routeFromSettings['suffix'];
             }
             $routeDefinitions[] = [
-                'name' => $packageKey,
+                'name' => $configurationKey,
                 'uriPattern' => '<' . $subRoutesName . '>',
                 'subRoutes' => [
                     $subRoutesName => $subRoutesConfiguration
@@ -128,6 +136,10 @@ protected function mergeRoutesWithSubRoutes(array $packages, ApplicationContext
             }
             $mergedSubRoutesConfiguration = [$routeConfiguration];
             foreach ($routeConfiguration['subRoutes'] as $subRouteKey => $subRouteOptions) {
+                if (isset($subRouteOptions['providerFactory'])) {
+                    $mergedRoutesConfiguration[] = $subRouteOptions;
+                    continue;
+                }
                 if (!isset($subRouteOptions['package'])) {
                     throw new ParseErrorException(sprintf('Missing package configuration for SubRoute in Route "%s".', ($routeConfiguration['name'] ?? 'unnamed Route')), 1318414040);
                 }

Neos.Flow/Classes/Mvc/Routing/AttributeRoutesProvider.php

@@ -0,0 +1,133 @@
+<?php
+
+/*
+ * This file is part of the Neos.Flow package.
+ *
+ * (c) Contributors of the Neos Project - www.neos.io
+ *
+ * This package is Open Source Software. For the full copyright and license
+ * information, please view the LICENSE file which was distributed with this
+ * source code.
+ */
+
+declare(strict_types=1);
+
+namespace Neos\Flow\Mvc\Routing;
+
+use Neos\Flow\Mvc\Exception\InvalidActionNameException;
+use Neos\Flow\Mvc\Routing\Exception\InvalidControllerException;
+use Neos\Flow\ObjectManagement\ObjectManagerInterface;
+use Neos\Flow\Reflection\ReflectionService;
+use Neos\Flow\Annotations as Flow;
+use Neos\Utility\Arrays;
+
+/**
+ * Allows to annotate controller methods with route configurations
+ *
+ * Implementation:
+ *
+ * Flows routing configuration is declared via \@package, \@subpackage, \@controller and \@action
+ * The first three options will resolve to a fully qualified class name {@see \Neos\Flow\Mvc\ActionRequest::getControllerObjectName()}
+ * which is instantiated in the dispatcher {@see \Neos\Flow\Mvc\Dispatcher::dispatch()}
+ *
+ * The latter \@action option will be treated internally by each controller.
+ * By convention and implementation of the default ActionController inside processRequest
+ * {@see \Neos\Flow\Mvc\Controller\ActionController::callActionMethod()} will be used to concatenate the "Action" suffix
+ * to the action name and invoke it internally with prepared method arguments.
+ * The \@action is just another routing value while the dispatcher does not really know about "actions" from the "outside".
+ *
+ * Creating routes by annotation must make a few assumptions to work.
+ * As not every FQ class name is representable via the routing configuration (e.g. the class has to end with "Controller"),
+ * only classes can be annotated that reside in a correct location and have the correct suffix.
+ * Otherwise, an exception will be thrown as the class is not discoverable by the dispatcher.
+ *
+ * The routing annotation is placed at methods.
+ * It is validated that the annotated method ends with "Action" and a routing value with the suffix trimmed will be generated.
+ * Using the annotations on any controller makes the assumption that the controller will delegate the request to the dedicate
+ * action by depending "Action".
+ * This thesis is true for the ActionController.
+ *
+ * As discussed in https://discuss.neos.io/t/rfc-future-of-routing-mvc-in-flow/6535 we want to refactor the routing values
+ * to include the fully qualified controller name, so it can be easier generated without strong restrictions.
+ * Additionally, the action mapping should include its full name and be guaranteed to called.
+ * Either by invoking the action in the dispatcher or by documenting this feature as part of a implementation of a ControllerInterface
+ */
+final class AttributeRoutesProvider implements RoutesProviderInterface
+{
+    /**
+     * @param array<string> $classNames
+     */
+    public function __construct(
+        public readonly ReflectionService $reflectionService,
+        public readonly ObjectManagerInterface $objectManager,
+        public readonly array $classNames,
+    ) {
+    }
+
+    public function getRoutes(): Routes
+    {
+        $routes = [];
+        $annotatedClasses = $this->reflectionService->getClassesContainingMethodsAnnotatedWith(Flow\Route::class);
+
+        foreach ($annotatedClasses as $className) {
+            $includeClassName = false;
+            foreach ($this->classNames as $classNamePattern) {
+                if (fnmatch($classNamePattern, $className, FNM_NOESCAPE)) {
+                    $includeClassName = true;
+                    break;
+                }
+            }
+            if (!$includeClassName) {
+                continue;
+            }
+            $controllerObjectName = $this->objectManager->getCaseSensitiveObjectName($className);
+            $controllerPackageKey = $this->objectManager->getPackageKeyByObjectName($controllerObjectName);
+            $controllerPackageNamespace = str_replace('.', '\\', $controllerPackageKey);
+            if (!str_ends_with($className, 'Controller')) {
+                throw new InvalidControllerException('Only for controller classes');
+            }
+
+            $localClassName = substr($className, strlen($controllerPackageNamespace) + 1);
+
+            if (str_starts_with($localClassName, 'Controller\\')) {
+                $controllerName = substr($localClassName, 11);
+                $subPackage = null;
+            } elseif (str_contains($localClassName, '\\Controller\\')) {
+                list($subPackage, $controllerName) = explode('\\Controller\\', $localClassName);
+            } else {
+                throw new InvalidControllerException('Unknown controller pattern');
+            }
+
+            $annotatedMethods = $this->reflectionService->getMethodsAnnotatedWith($className, Flow\Route::class);
+            foreach ($annotatedMethods as $methodName) {
+                if (!str_ends_with($methodName, 'Action')) {
+                    throw new InvalidActionNameException('Only for action methods');
+                }
+                $annotations = $this->reflectionService->getMethodAnnotations($className, $methodName, Flow\Route::class);
+                foreach ($annotations as $annotation) {
+                    if ($annotation instanceof Flow\Route) {
+                        $controller = substr($controllerName, 0, -10);
+                        $action = substr($methodName, 0, -6);
+                        $configuration = [
+                            'name' => $controllerPackageKey . ' :: ' . $controller . ' :: ' . ($annotation->name ?: $action),
+                            'uriPattern' => $annotation->uriPattern,
+                            'httpMethods' => $annotation->httpMethods,
+                            'defaults' => Arrays::arrayMergeRecursiveOverrule(
+                                [
+                                    '@package' => $controllerPackageKey,
+                                    '@subpackage' => $subPackage,
+                                    '@controller' => $controller,
+                                    '@action' => $action,
+                                    '@format' => 'html'
+                                ],
+                                $annotation->defaults ?? []
+                            )
+                        ];
+                        $routes[] = Route::fromConfiguration($configuration);
+                    }
+                }
+            }
+        }
+        return Routes::create(...$routes);
+    }
+}

Neos.Flow/Classes/Mvc/Routing/AttributeRoutesProviderFactory.php

@@ -0,0 +1,39 @@
+<?php
+
+/*
+ * This file is part of the Neos.Flow package.
+ *
+ * (c) Contributors of the Neos Project - www.neos.io
+ *
+ * This package is Open Source Software. For the full copyright and license
+ * information, please view the LICENSE file which was distributed with this
+ * source code.
+ */
+
+declare(strict_types=1);
+
+namespace Neos\Flow\Mvc\Routing;
+
+use Neos\Flow\ObjectManagement\ObjectManagerInterface;
+use Neos\Flow\Reflection\ReflectionService;
+
+class AttributeRoutesProviderFactory implements RoutesProviderFactoryInterface
+{
+    public function __construct(
+        public readonly ReflectionService $reflectionService,
+        public readonly ObjectManagerInterface $objectManager,
+    ) {
+    }
+
+    /**
+     * @param array<string, mixed> $options
+     */
+    public function createRoutesProvider(array $options): RoutesProviderInterface
+    {
+        return new AttributeRoutesProvider(
+            $this->reflectionService,
+            $this->objectManager,
+            $options['classNames'] ?? [],
+        );
+    }
+}

Neos.Flow/Classes/Mvc/Routing/ConfigurationRoutesProvider.php

@@ -6,22 +6,36 @@
 
 use Neos\Flow\Annotations as Flow;
 use Neos\Flow\Configuration\ConfigurationManager;
+use Neos\Flow\ObjectManagement\ObjectManagerInterface;
 
 /**
  * @Flow\Scope("singleton")
  */
 final class ConfigurationRoutesProvider implements RoutesProviderInterface
 {
-    private ConfigurationManager $configurationManager;
-
     public function __construct(
-        ConfigurationManager $configurationManager
+        private ConfigurationManager $configurationManager,
+        private ObjectManagerInterface $objectManager,
     ) {
-        $this->configurationManager = $configurationManager;
     }
 
     public function getRoutes(): Routes
     {
-        return Routes::fromConfiguration($this->configurationManager->getConfiguration(ConfigurationManager::CONFIGURATION_TYPE_ROUTES));
+        $routes = [];
+        foreach ($this->configurationManager->getConfiguration(ConfigurationManager::CONFIGURATION_TYPE_ROUTES) as $routeConfiguration) {
+            if (isset($routeConfiguration['providerFactory'])) {
+                $providerFactory = $this->objectManager->get($routeConfiguration['providerFactory']);
+                if (!$providerFactory instanceof RoutesProviderFactoryInterface) {
+                    throw new \InvalidArgumentException(sprintf('The configured route providerFactory "%s" does not implement the "%s"', $routeConfiguration['providerFactory'], RoutesProviderFactoryInterface::class), 1710784630);
+                }
+                $provider = $providerFactory->createRoutesProvider($routeConfiguration['providerOptions'] ?? []);
+                foreach ($provider->getRoutes() as $route) {
+                    $routes[] = $route;
+                }
+            } else {
+                $routes[] = Route::fromConfiguration($routeConfiguration);
+            }
+        }
+        return Routes::create(...$routes);
     }
 }

Neos.Flow/Classes/Mvc/Routing/RoutesProviderFactoryInterface.php

@@ -0,0 +1,23 @@
+<?php
+
+/*
+ * This file is part of the Neos.Flow package.
+ *
+ * (c) Contributors of the Neos Project - www.neos.io
+ *
+ * This package is Open Source Software. For the full copyright and license
+ * information, please view the LICENSE file which was distributed with this
+ * source code.
+ */
+
+declare(strict_types=1);
+
+namespace Neos\Flow\Mvc\Routing;
+
+interface RoutesProviderFactoryInterface
+{
+    /**
+     * @param array<string, mixed> $options
+     */
+    public function createRoutesProvider(array $options): RoutesProviderInterface;
+}

Neos.Flow/Classes/Mvc/Routing/RoutesProviderInterface.php

@@ -1,5 +1,15 @@
 <?php
 
+/*
+ * This file is part of the Neos.Flow package.
+ *
+ * (c) Contributors of the Neos Project - www.neos.io
+ *
+ * This package is Open Source Software. For the full copyright and license
+ * information, please view the LICENSE file which was distributed with this
+ * source code.
+ */
+
 declare(strict_types=1);
 
 namespace Neos\Flow\Mvc\Routing;

Neos.Flow/Classes/Package.php

@@ -11,6 +11,7 @@
  * source code.
  */
 
+use Neos\Flow\Annotations\Route;
 use Neos\Flow\Cache\AnnotationsCacheFlusher;
 use Neos\Flow\Configuration\Loader\AppendLoader;
 use Neos\Flow\Configuration\Source\YamlSource;
@@ -158,6 +159,7 @@ public function boot(Core\Bootstrap $bootstrap)
 
         $dispatcher->connect(Proxy\Compiler::class, 'compiledClasses', function (array $classNames) use ($bootstrap) {
             $annotationsCacheFlusher = $bootstrap->getObjectManager()->get(AnnotationsCacheFlusher::class);
+            $annotationsCacheFlusher->registerAnnotation(Route::class, ['Flow_Mvc_Routing_Route', 'Flow_Mvc_Routing_Resolve']);
             $annotationsCacheFlusher->flushConfigurationCachesByCompiledClass($classNames);
         });
     }

Neos.Flow/Classes/Reflection/ReflectionService.php

@@ -1273,7 +1273,7 @@ protected function reflectClassMethod(string $className, MethodReflection $metho
             if (!isset($this->classesByMethodAnnotations[$annotationClassName][$className])) {
                 $this->classesByMethodAnnotations[$annotationClassName][$className] = [];
             }
-            $this->classesByMethodAnnotations[$annotationClassName][$className][] = $methodName;
+            $this->classesByMethodAnnotations[$annotationClassName][$className][$methodName] = $methodName;
         }
 
         $returnType = $method->getDeclaredReturnType();