From 7d62c024be645b6a41f9249ced95ab2af32d022e Mon Sep 17 00:00:00 2001
From: Rudolph Gottesheim <r.gottesheim@midnight-design.at>
Date: Wed, 27 May 2026 11:59:21 +0200
Subject: [PATCH] Allow @api annotation

Why: @api is a meaningful annotation for marking public API surface
(used by PHPStan, Psalm, IDEs), not a useless metadata tag like
@author/@version.

Remove it from both the phpcs ForbiddenAnnotations list and the
php-cs-fixer general_phpdoc_annotation_remove list, and add a valid
fixture so a future re-add would fail the test suite.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 Eventjet/ruleset.xml                    |  1 -
 php-cs-fixer-rules.php                  |  1 -
 tests/fixtures/valid/api-annotation.php | 10 ++++++++++
 3 files changed, 10 insertions(+), 2 deletions(-)
 create mode 100644 tests/fixtures/valid/api-annotation.php

diff --git a/Eventjet/ruleset.xml b/Eventjet/ruleset.xml
index af435fb..b0da5c1 100644
--- a/Eventjet/ruleset.xml
+++ b/Eventjet/ruleset.xml
@@ -137,7 +137,6 @@
                 name="forbiddenAnnotations"
                 type="array"
                 value="
-                    @api,
                     @author,
                     @category,
                     @copyright,
diff --git a/php-cs-fixer-rules.php b/php-cs-fixer-rules.php
index d6bb3f4..a754b91 100644
--- a/php-cs-fixer-rules.php
+++ b/php-cs-fixer-rules.php
@@ -25,7 +25,6 @@
     ],
     'general_phpdoc_annotation_remove' => [
         'annotations' => [
-            'api',
             'author',
             'category',
             'copyright',
diff --git a/tests/fixtures/valid/api-annotation.php b/tests/fixtures/valid/api-annotation.php
new file mode 100644
index 0000000..27402c3
--- /dev/null
+++ b/tests/fixtures/valid/api-annotation.php
@@ -0,0 +1,10 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * @api
+ */
+function foo(): void
+{
+}