8 files changed, 218 insertions, 0 deletions
diff --git a/lib/public/AppFramework/Attribute/ASince.php b/lib/public/AppFramework/Attribute/ASince.php
new file mode 100644
index 00000000000..1e0c45348cf
--- /dev/null
+++ b/lib/public/AppFramework/Attribute/ASince.php
@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\AppFramework\Attribute;
+
+use Attribute;
+
+/**
+ * Abstract base attribute to declare an API's stability.
+ *
+ * @since 32.0.0
+ */
+#[Consumable(since: '32.0.0')]
+abstract class ASince {
+	/**
+	 * @param string $since For shipped apps and server code such as core/ and lib/,
+	 *                      this should be the server version. For other apps it
+	 *                      should be the semantic app version.
+	 */
+	public function __construct(
+		protected string $since,
+	) {
+	}
+
+	public function getSince(): string {
+		return $this->since;
+	}
+}
diff --git a/lib/public/AppFramework/Attribute/Catchable.php b/lib/public/AppFramework/Attribute/Catchable.php
new file mode 100644
index 00000000000..d45401550f6
--- /dev/null
+++ b/lib/public/AppFramework/Attribute/Catchable.php
@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\AppFramework\Attribute;
+
+use Attribute;
+
+/**
+ * Attribute to declare that the exception is "catchable" by apps.
+ *
+ * @since 32.0.0
+ */
+#[Attribute(Attribute::TARGET_ALL | Attribute::IS_REPEATABLE)]
+#[Consumable(since: '32.0.0')]
+#[Implementable(since: '32.0.0')]
+class Catchable extends ASince {
+}
diff --git a/lib/public/AppFramework/Attribute/Consumable.php b/lib/public/AppFramework/Attribute/Consumable.php
new file mode 100644
index 00000000000..2175bb0af88
--- /dev/null
+++ b/lib/public/AppFramework/Attribute/Consumable.php
@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\AppFramework\Attribute;
+
+use Attribute;
+
+/**
+ * Attribute to declare that the API stability is limited to "consuming" the
+ * class, interface, enum, etc. Apps are not allowed to implement or replace them.
+ *
+ * For events use @see \OCP\AppFramework\Attribute\Listenable
+ * For exceptions use @see \OCP\AppFramework\Attribute\Catchable
+ *
+ * @since 32.0.0
+ */
+#[Attribute(Attribute::TARGET_ALL | Attribute::IS_REPEATABLE)]
+#[Consumable(since: '32.0.0')]
+#[Implementable(since: '32.0.0')]
+class Consumable extends ASince {
+}
diff --git a/lib/public/AppFramework/Attribute/Dispatchable.php b/lib/public/AppFramework/Attribute/Dispatchable.php
new file mode 100644
index 00000000000..ff703d4749e
--- /dev/null
+++ b/lib/public/AppFramework/Attribute/Dispatchable.php
@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\AppFramework\Attribute;
+
+use Attribute;
+
+/**
+ * Attribute to declare that the event is "dispatchable" by apps.
+ *
+ * @since 32.0.0
+ */
+#[Attribute(Attribute::TARGET_ALL | Attribute::IS_REPEATABLE)]
+#[Consumable(since: '32.0.0')]
+#[Implementable(since: '32.0.0')]
+class Dispatchable extends ASince {
+}
diff --git a/lib/public/AppFramework/Attribute/ExceptionalImplementable.php b/lib/public/AppFramework/Attribute/ExceptionalImplementable.php
new file mode 100644
index 00000000000..23e9f830d9b
--- /dev/null
+++ b/lib/public/AppFramework/Attribute/ExceptionalImplementable.php
@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\AppFramework\Attribute;
+
+use Attribute;
+
+/**
+ * Attribute to declare that the API marked as Consumable/Listenable/Catchable
+ * has an exception and is Implementable/Dispatchable/Throwable by a dedicated
+ * app. Changes to such an API have to be communicated to the affected app maintainers.
+ *
+ * @since 32.0.0
+ */
+#[Attribute(Attribute::TARGET_ALL | Attribute::IS_REPEATABLE)]
+#[Consumable(since: '32.0.0')]
+#[Implementable(since: '32.0.0')]
+class ExceptionalImplementable {
+	public function __construct(
+		protected string $app,
+		protected ?string $class = null,
+	) {
+	}
+
+	public function getApp(): string {
+		return $this->app;
+	}
+
+	public function getClass(): ?string {
+		return $this->class;
+	}
+}
diff --git a/lib/public/AppFramework/Attribute/Implementable.php b/lib/public/AppFramework/Attribute/Implementable.php
new file mode 100644
index 00000000000..40ce0e0cf06
--- /dev/null
+++ b/lib/public/AppFramework/Attribute/Implementable.php
@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\AppFramework\Attribute;
+
+use Attribute;
+
+/**
+ * Attribute to declare that the API stability is limited to "implementing" the
+ * class, interface, enum, etc.
+ *
+ * For events use @see \OCP\AppFramework\Attribute\Dispatchable
+ * For exceptions use @see \OCP\AppFramework\Attribute\Throwable
+ *
+ * @since 32.0.0
+ */
+#[Attribute(Attribute::TARGET_ALL | Attribute::IS_REPEATABLE)]
+#[Consumable(since: '32.0.0')]
+#[Implementable(since: '32.0.0')]
+class Implementable extends ASince {
+}
diff --git a/lib/public/AppFramework/Attribute/Listenable.php b/lib/public/AppFramework/Attribute/Listenable.php
new file mode 100644
index 00000000000..98c2ca78690
--- /dev/null
+++ b/lib/public/AppFramework/Attribute/Listenable.php
@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\AppFramework\Attribute;
+
+use Attribute;
+
+/**
+ * Attribute to declare that the event is "listenable" by apps.
+ *
+ * @since 32.0.0
+ */
+#[Attribute(Attribute::TARGET_ALL | Attribute::IS_REPEATABLE)]
+#[Consumable(since: '32.0.0')]
+#[Implementable(since: '32.0.0')]
+class Listenable extends ASince {
+}
diff --git a/lib/public/AppFramework/Attribute/Throwable.php b/lib/public/AppFramework/Attribute/Throwable.php
new file mode 100644
index 00000000000..2c763c76b4c
--- /dev/null
+++ b/lib/public/AppFramework/Attribute/Throwable.php
@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * SPDX-FileCopyrightText: 2025 Nextcloud GmbH and Nextcloud contributors
+ * SPDX-License-Identifier: AGPL-3.0-or-later
+ */
+
+namespace OCP\AppFramework\Attribute;
+
+use Attribute;
+
+/**
+ * Attribute to declare that the exception is "throwable" by apps.
+ *
+ * @since 32.0.0
+ */
+#[Attribute(Attribute::TARGET_ALL | Attribute::IS_REPEATABLE)]
+#[Consumable(since: '32.0.0')]
+#[Implementable(since: '32.0.0')]
+class Throwable extends ASince {
+}