From a9e7687ee01b76c7219d7ba0bde994668e149f51 Mon Sep 17 00:00:00 2001
From: dmitrybukhonov <d.buhonov@yandex.ru>
Date: Tue, 28 Oct 2025 21:07:11 +0400
Subject: [PATCH] Add Route attribute to document HTTP endpoints

---
 src/Route.php                            | 35 ++++++++++++++++++++++++
 tests/.gitkeep                           |  0
 tests/Fig/Attributes/Tests/RouteTest.php | 31 +++++++++++++++++++++
 3 files changed, 66 insertions(+)
 create mode 100644 src/Route.php
 delete mode 100644 tests/.gitkeep
 create mode 100644 tests/Fig/Attributes/Tests/RouteTest.php

diff --git a/src/Route.php b/src/Route.php
new file mode 100644
index 0000000..fa4732e
--- /dev/null
+++ b/src/Route.php
@@ -0,0 +1,35 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Fig\Attributes;
+
+use Attribute;
+
+/**
+ * Indicates the HTTP endpoint(s) associated with the class, method, or action.
+ *
+ * ## Target audience.
+ *
+ * Implementors: Static analysis tools, API documentation generators
+ * Users: Developers defining controller actions or classes handling HTTP requests
+ */
+#[Attribute(Attribute::TARGET_CLASS)]
+final class Route
+{
+    /** @var string[] HTTP methods like GET, POST, PUT, DELETE */
+    public array $methods;
+
+    /** @var string Path relative to the application root */
+    public string $path;
+
+    /**
+     * @param string|string[] $methods HTTP method(s)
+     * @param string $path Endpoint path
+     */
+    public function __construct(string|array $methods, string $path)
+    {
+        $this->methods = is_array($methods) ? $methods : [$methods];
+        $this->path = $path;
+    }
+}
diff --git a/tests/.gitkeep b/tests/.gitkeep
deleted file mode 100644
index e69de29..0000000
diff --git a/tests/Fig/Attributes/Tests/RouteTest.php b/tests/Fig/Attributes/Tests/RouteTest.php
new file mode 100644
index 0000000..d043f50
--- /dev/null
+++ b/tests/Fig/Attributes/Tests/RouteTest.php
@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Fig\Attributes\Tests;
+
+use Fig\Attributes\Route;
+use PHPUnit\Framework\TestCase;
+
+final class RouteTest extends TestCase
+{
+    /**
+     * @covers \Fig\Attributes\Route
+     */
+    public function testSingleMethod(): void
+    {
+        $attribute = new Route('GET', '/users');
+        $this->assertSame(['GET'], $attribute->methods);
+        $this->assertSame('/users', $attribute->path);
+    }
+
+    /**
+     * @covers \Fig\Attributes\Route
+     */
+    public function testMultipleMethods(): void
+    {
+        $attribute = new Route(['GET', 'POST'], '/users');
+        $this->assertSame(['GET', 'POST'], $attribute->methods);
+        $this->assertSame('/users', $attribute->path);
+    }
+}