1 files changed, 145 insertions, 0 deletions
diff --git a/lib/public/AppFramework/Http/Attribute/Route.php b/lib/public/AppFramework/Http/Attribute/Route.php
new file mode 100644
index 00000000000..45e977d64f8
--- /dev/null
+++ b/lib/public/AppFramework/Http/Attribute/Route.php
@@ -0,0 +1,145 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2024 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\AppFramework\Http\Attribute;
+
+use Attribute;
+
+/**
+ * This attribute can be used to define routes on controller methods.
+ *
+ * It works in addition to the traditional routes.php method and has the same parameters
+ * (except for the `name` parameter which is not needed).
+ *
+ * @since 29.0.0
+ */
+#[Attribute(Attribute::TARGET_METHOD | Attribute::IS_REPEATABLE)]
+class Route {
+
+	/**
+	 * Corresponds to the `ocs` key in routes.php
+	 *
+	 * @see ApiRoute
+	 * @since 29.0.0
+	 */
+	public const TYPE_API = 'ocs';
+
+	/**
+	 * Corresponds to the `routes` key in routes.php
+	 *
+	 * @see FrontpageRoute
+	 * @since 29.0.0
+	 */
+	public const TYPE_FRONTPAGE = 'routes';
+
+	/**
+	 * @param string $type Either Route::TYPE_API or Route::TYPE_FRONTPAGE.
+	 * @psalm-param Route::TYPE_* $type
+	 * @param string $verb HTTP method of the route.
+	 * @psalm-param 'GET'|'HEAD'|'POST'|'PUT'|'DELETE'|'OPTIONS'|'PATCH' $verb
+	 * @param string $url The path of the route.
+	 * @param ?array<string, string> $requirements Array of regexes mapped to the path parameters.
+	 * @param ?array<string, mixed> $defaults Array of default values mapped to the path parameters.
+	 * @param ?string $root Custom root. For OCS all apps are allowed, but for index.php only some can use it.
+	 * @param ?string $postfix Postfix for the route name.
+	 * @since 29.0.0
+	 */
+	public function __construct(
+		protected string $type,
+		protected string $verb,
+		protected string $url,
+		protected ?array $requirements = null,
+		protected ?array $defaults = null,
+		protected ?string $root = null,
+		protected ?string $postfix = null,
+	) {
+	}
+
+	/**
+	 * @return array{
+	 *     verb: string,
+	 *     url: string,
+	 *     requirements?: array<string, string>,
+	 *     defaults?: array<string, mixed>,
+	 *     root?: string,
+	 *     postfix?: string,
+	 * }
+	 * @since 29.0.0
+	 */
+	public function toArray() {
+		$route = [
+			'verb' => $this->verb,
+			'url' => $this->url,
+		];
+
+		if ($this->requirements !== null) {
+			$route['requirements'] = $this->requirements;
+		}
+		if ($this->defaults !== null) {
+			$route['defaults'] = $this->defaults;
+		}
+		if ($this->root !== null) {
+			$route['root'] = $this->root;
+		}
+		if ($this->postfix !== null) {
+			$route['postfix'] = $this->postfix;
+		}
+
+		return $route;
+	}
+
+	/**
+	 * @since 29.0.0
+	 */
+	public function getType(): string {
+		return $this->type;
+	}
+
+	/**
+	 * @since 29.0.0
+	 */
+	public function getVerb(): string {
+		return $this->verb;
+	}
+
+	/**
+	 * @since 29.0.0
+	 */
+	public function getUrl(): string {
+		return $this->url;
+	}
+
+	/**
+	 * @since 29.0.0
+	 */
+	public function getRequirements(): ?array {
+		return $this->requirements;
+	}
+
+	/**
+	 * @since 29.0.0
+	 */
+	public function getDefaults(): ?array {
+		return $this->defaults;
+	}
+
+	/**
+	 * @since 29.0.0
+	 */
+	public function getRoot(): ?string {
+		return $this->root;
+	}
+
+	/**
+	 * @since 29.0.0
+	 */
+	public function getPostfix(): ?string {
+		return $this->postfix;
+	}
+}