From ad031188bca7578ce1ad706554be077a90af18a0 Mon Sep 17 00:00:00 2001
From: provokateurin <kate@provokateurin.de>
Date: Mon, 19 May 2025 09:07:08 +0200
Subject: [PATCH] feat(Http): Add RequestHeader attribute

Signed-off-by: provokateurin <kate@provokateurin.de>
---
 lib/composer/composer/autoload_classmap.php   |  1 +
 lib/composer/composer/autoload_static.php     |  1 +
 .../Http/Attribute/RequestHeader.php          | 50 +++++++++++++++++++
 3 files changed, 52 insertions(+)
 create mode 100644 lib/public/AppFramework/Http/Attribute/RequestHeader.php

diff --git a/lib/composer/composer/autoload_classmap.php b/lib/composer/composer/autoload_classmap.php
index c0c086e4038..1ccda5e6a90 100644
--- a/lib/composer/composer/autoload_classmap.php
+++ b/lib/composer/composer/autoload_classmap.php
@@ -85,6 +85,7 @@ return array(
     'OCP\\AppFramework\\Http\\Attribute\\OpenAPI' => $baseDir . '/lib/public/AppFramework/Http/Attribute/OpenAPI.php',
     'OCP\\AppFramework\\Http\\Attribute\\PasswordConfirmationRequired' => $baseDir . '/lib/public/AppFramework/Http/Attribute/PasswordConfirmationRequired.php',
     'OCP\\AppFramework\\Http\\Attribute\\PublicPage' => $baseDir . '/lib/public/AppFramework/Http/Attribute/PublicPage.php',
+    'OCP\\AppFramework\\Http\\Attribute\\RequestHeader' => $baseDir . '/lib/public/AppFramework/Http/Attribute/RequestHeader.php',
     'OCP\\AppFramework\\Http\\Attribute\\Route' => $baseDir . '/lib/public/AppFramework/Http/Attribute/Route.php',
     'OCP\\AppFramework\\Http\\Attribute\\StrictCookiesRequired' => $baseDir . '/lib/public/AppFramework/Http/Attribute/StrictCookiesRequired.php',
     'OCP\\AppFramework\\Http\\Attribute\\SubAdminRequired' => $baseDir . '/lib/public/AppFramework/Http/Attribute/SubAdminRequired.php',
diff --git a/lib/composer/composer/autoload_static.php b/lib/composer/composer/autoload_static.php
index f2f817877d2..9c983f74a83 100644
--- a/lib/composer/composer/autoload_static.php
+++ b/lib/composer/composer/autoload_static.php
@@ -126,6 +126,7 @@ class ComposerStaticInit749170dad3f5e7f9ca158f5a9f04f6a2
         'OCP\\AppFramework\\Http\\Attribute\\OpenAPI' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/Attribute/OpenAPI.php',
         'OCP\\AppFramework\\Http\\Attribute\\PasswordConfirmationRequired' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/Attribute/PasswordConfirmationRequired.php',
         'OCP\\AppFramework\\Http\\Attribute\\PublicPage' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/Attribute/PublicPage.php',
+        'OCP\\AppFramework\\Http\\Attribute\\RequestHeader' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/Attribute/RequestHeader.php',
         'OCP\\AppFramework\\Http\\Attribute\\Route' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/Attribute/Route.php',
         'OCP\\AppFramework\\Http\\Attribute\\StrictCookiesRequired' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/Attribute/StrictCookiesRequired.php',
         'OCP\\AppFramework\\Http\\Attribute\\SubAdminRequired' => __DIR__ . '/../../..' . '/lib/public/AppFramework/Http/Attribute/SubAdminRequired.php',
diff --git a/lib/public/AppFramework/Http/Attribute/RequestHeader.php b/lib/public/AppFramework/Http/Attribute/RequestHeader.php
new file mode 100644
index 00000000000..c9327eec4c0
--- /dev/null
+++ b/lib/public/AppFramework/Http/Attribute/RequestHeader.php
@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\AppFramework\Http\Attribute;
+
+use Attribute;
+
+/**
+ * This attribute allows documenting request headers and is primarily intended for OpenAPI documentation.
+ * It should be added whenever you use a request header in a controller method, in order to properly describe the header and its functionality.
+ * There are no checks that ensure the header is set, so you will still need to do this yourself in the controller method.
+ *
+ * @since 32.0.0
+ */
+#[Attribute(Attribute::TARGET_METHOD | Attribute::IS_REPEATABLE)]
+class RequestHeader {
+	/**
+	 * @param string $name The name of the request header
+	 * @param string $description The description of the request header
+	 */
+	public function __construct(
+		protected string $name,
+		protected string $description,
+	) {
+	}
+
+	/**
+	 * @return string The name of the request header.
+	 *
+	 * @since 32.0.0
+	 */
+	public function getName(): string {
+		return $this->name;
+	}
+
+	/**
+	 * @return string The description of the request header.
+	 *
+	 * @since 32.0.0
+	 */
+	public function getDescription(): string {
+		return $this->description;
+	}
+}