Replace @PHPDoc annotations with PHP attributes

sajya · Jan 2, 2025 · e3022fc · e3022fc
1 parent 8b0ecfe
commit e3022fc
Show file tree

Hide file tree

Showing 9 changed files with 76 additions and 134 deletions.
diff --git a/composer.json b/composer.json
@@ -16,9 +16,7 @@
     ],
     "require": {
         "ext-json": "*",
-        "doctrine/annotations": "^2.0",
-        "laravel/framework": "^10.0|^11.0",
-        "phpdocumentor/reflection-docblock": "^5.3"
+        "laravel/framework": "^10.0|^11.0"
     },
     "require-dev": {
         "laravel/pint": "^1.4",

diff --git a/src/Annotations/Param.php b/src/Annotations/Param.php
diff --git a/src/Annotations/Result.php b/src/Annotations/Result.php
diff --git a/src/Attributes/RpcMethod.php b/src/Attributes/RpcMethod.php
@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Sajya\Server\Attributes;
+
+use Attribute;
+
+#[Attribute(Attribute::TARGET_METHOD)]
+class RpcMethod
+{
+    public function __construct(
+        public string|null $description = null,
+        public array|null  $params = null,
+        public array|null  $result = null
+    )
+    {
+    }
+}
diff --git a/src/Commands/DocsCommand.php b/src/Commands/DocsCommand.php
@@ -50,7 +50,7 @@ public function handle(): int
 
         $html = view('sajya::docs', [
             'title'      => config('app.name'),
-            'uri'        => config('app.url').$route->uri(),
+            'uri'        => route($routeName),
             'procedures' => $docs->getAnnotations(),
         ]);
 

diff --git a/src/Docs.php b/src/Docs.php
@@ -4,17 +4,14 @@
 
 namespace Sajya\Server;
 
-use Doctrine\Common\Annotations\AnnotationReader;
-use Illuminate\Config\Repository;
 use Illuminate\Routing\Route;
 use Illuminate\Support\Collection;
 use Illuminate\Support\Str;
 use Illuminate\Support\Stringable;
-use phpDocumentor\Reflection\DocBlockFactory;
 use ReflectionClass;
 use ReflectionMethod;
 use Sajya\Server\Annotations\Param;
-use Sajya\Server\Annotations\Result;
+use Sajya\Server\Attributes\RpcMethod;
 
 class Docs
 {
@@ -51,29 +48,29 @@ public function getAnnotations(): Collection
 
                 return collect($reflectionClass->getMethods(ReflectionMethod::IS_PUBLIC))
                     ->map(function (ReflectionMethod $method) use ($name) {
+
+                        $attributes = $this->getMethodAnnotations($method);
+
                         $request = [
                             'jsonrpc' => '2.0',
                             'id'      => 1,
                             'method'  => $name.$this->delimiter.$method->getName(),
-                            'params'  => $this->getMethodAnnotations($method, Param::class),
+                            'params'  => $attributes?->params,
                         ];
 
                         $response = [
                             'jsonrpc' => '2.0',
                             'id'      => 1,
-                            'result'  => $this->getMethodAnnotations($method, Result::class),
+                            'result'  => $attributes?->result,
                         ];
 
-                        $factory = DocBlockFactory::createInstance();
-                        $comment = $method->getDocComment();
-                        $docblock = $factory->create($comment === false ? ' ' : $comment);
-                        $description = $docblock->getSummary();
-
                         return [
                             'name'        => $name,
-                            'description' => $description,
                             'delimiter'   => $this->delimiter,
                             'method'      => $method->getName(),
+                            'description' => $attributes?->description,
+                            'params'      => $attributes?->params,
+                            'result'      => $attributes?->result,
                             'request'     => $this->highlight($request),
                             'response'    => $this->highlight($response),
                         ];
@@ -82,44 +79,18 @@ public function getAnnotations(): Collection
             ->flatten(1);
     }
 
-    /**
-     * @param ReflectionMethod $method
-     * @param string           $class
-     *
-     * @return array
-     */
-    private function getMethodAnnotations(ReflectionMethod $method, string $class): array
+    private function getMethodAnnotations(ReflectionMethod $method): ?RpcMethod
     {
-        $repository = new Repository();
-
-        $values = $this
-            ->getAnnotationsFrom($method, $class)
-            ->mapWithKeys(fn (object $param) => [$param->name => $param->value]);
+        $attributes = $method->getAttributes(RpcMethod::class);
 
-        foreach ($values as $key => $param) {
-            $key = Str::of($key);
+        foreach ($attributes as $attribute) {
+            /** @var RpcMethod $instance */
+            $instance = $attribute->newInstance();
 
-            if ($key->endsWith('.')) {
-                $repository->push((string) $key->replaceLast('.', ''), $param);
-            } else {
-                $repository->set((string) $key, $param);
-            }
+            return $instance;
         }
 
-        return $repository->all();
-    }
-
-    /**
-     * @param ReflectionMethod $method
-     * @param string           $class
-     *
-     * @return Collection
-     */
-    private function getAnnotationsFrom(ReflectionMethod $method, string $class): Collection
-    {
-        $annotations = (new AnnotationReader())->getMethodAnnotations($method);
-
-        return collect($annotations)->filter(fn ($annotation) => is_a($annotation, $class));
+        return null;
     }
 
     /**
@@ -132,7 +103,7 @@ private function getAnnotationsFrom(ReflectionMethod $method, string $class): Co
     private function highlight(array $value): Stringable
     {
         ini_set('highlight.comment', '#008000');
-        ini_set('highlight.default', '#000000');
+        ini_set('highlight.default', '#C3E88D');
         ini_set('highlight.html', '#808080');
         ini_set('highlight.keyword', '#998;');
         ini_set('highlight.string', '#d14');
@@ -141,15 +112,22 @@ private function highlight(array $value): Stringable
         $code = highlight_string('<?php '.$json, true);
 
         $docs = Str::of($code)
-            ->replaceFirst('&lt;?php&nbsp;', '')
+            ->replaceFirst('<span style="color: #C3E88D">&lt;?php </span>', '')
             ->replace('&nbsp;&nbsp;&nbsp;&nbsp;', '&nbsp;&nbsp;');
 
         $keys = $this->arrayKeysMulti($value);
 
         foreach ($keys as $item) {
             $docs = $docs->replace(
                 '<span style="color: #d14">"'.$item.'"</span>',
-                '<span style="color: #333">"'.$item.'"</span>'
+                '<span style="color: #C3E88D">"'.$item.'"</span>'
+            );
+        }
+
+        foreach ($keys as $item) {
+            $docs = $docs->replace(
+                '<span style="color: #d14">"'.$item.'"</span>',
+                '<span style="color: red">"'.$item.'"</span>'
             );
         }
 

diff --git a/src/Guide.php b/src/Guide.php
diff --git a/tests/FixtureDocsProcedure.php b/tests/FixtureDocsProcedure.php
@@ -4,8 +4,7 @@
 
 namespace Sajya\Server\Tests;
 
-use Sajya\Server\Annotations\Param;
-use Sajya\Server\Annotations\Result;
+use Sajya\Server\Attributes\RpcMethod;
 use Sajya\Server\Procedure;
 
 class FixtureDocsProcedure extends Procedure
@@ -18,17 +17,12 @@ class FixtureDocsProcedure extends Procedure
      */
     public static string $name = 'docs';
 
-    /**
-     * Execute the procedure.
-     *
-     * @Param(name="key", value="required")
-     * @Param(name="array.", value="max:5")
-     *
-     * @Result(name="key", value="string")
-     * @Result(name="array.", value="max:4")
-     *
-     * @return string
-     */
+    #[
+        RpcMethod(
+            description: 'Execute the procedure.',
+            params: ['key' => 'required', 'array' => 'max:5'],
+            result: ['key' => 'string', 'array' => 'max:4'])
+    ]
     public function ping(): string
     {
         return 'pong';

diff --git a/views/docs.blade.php b/views/docs.blade.php
@@ -21,7 +21,7 @@
 
         code {
             display: block;
-            background: #f8f8f8;
+            background: rgb(37 42 55);
             padding: 0.5em;
         }
     </style>
@@ -33,10 +33,15 @@
 <div class="col-lg-11 mx-auto pt-3 pt-md-5">
     <header class="row d-flex align-items-center pb-md-3 mb-4 mb-md-5 border-bottom">
         <span class="col d-flex align-items-center text-dark text-decoration-none me-auto user-select-none">
-            <img alt="Starter template" src="https://sajya.github.io/assets/img/logo.svg" width="45" class="me-2">
+            <svg fill="currentColor" width="48px" height="48px" class="me-2" xmlns="http://www.w3.org/2000/svg"
+                 viewBox="231 232 276.5 275.49">
+                <path
+                    d="M504.07 328.344H391.678C388.889 328.344 387.237 325.261 388.779 322.949L444.938 237.395C446.443 235.083 444.791 232 442.038 232H347.485C346.31 232 345.209 232.587 344.585 233.578L231.57 405.75C230.065 408.063 231.717 411.145 234.469 411.145H278.589V411.256H328.765H346.751C349.504 411.256 351.192 414.339 349.651 416.651L293.565 502.095C292.06 504.407 293.712 507.49 296.465 507.49H391.018C392.192 507.49 393.293 506.903 393.917 505.912L506.933 333.74C508.438 331.427 506.786 328.344 504.033 328.344H504.07ZM481.276 347.613L386.503 492.038C385.842 493.029 384.778 493.616 383.603 493.616H322.269C319.479 493.616 317.827 490.533 319.369 488.221L368.848 412.834C369.508 411.843 370.573 411.256 371.747 411.256H401.222C403.828 415.99 408.82 419.257 414.619 419.257C423.098 419.257 429.925 412.393 429.925 403.952C429.925 395.51 423.061 388.647 414.619 388.647C408.526 388.647 403.277 392.244 400.818 397.419H378.978H292.501V397.309H260.2C257.41 397.309 255.758 394.226 257.3 391.913L352.073 247.489C352.734 246.498 353.798 245.91 354.973 245.91H416.307C419.097 245.91 420.749 248.993 419.207 251.306L369.655 326.803C368.994 327.794 367.93 328.381 366.755 328.381H337.942C335.446 323.353 330.27 319.866 324.287 319.866C315.808 319.866 308.981 326.729 308.981 335.171C308.981 343.613 315.845 350.476 324.287 350.476C330.197 350.476 335.226 347.099 337.795 342.218H478.376C481.166 342.218 482.818 345.301 481.276 347.613Z">
+                </path>
+            </svg>
             <span class="fs-3">
                {{ $title }}
-                <span class="text-muted ps-md-2 fs-6 d-block d-md-inline">{ JSON-RPC } Documentation</span>
+                <span class="text-muted ps-md-2 fs-6 d-block d-md-inline">{ JSON-RPC }</span>
             </span>
         </span>
 
@@ -45,7 +50,7 @@
 
     @foreach($procedures as $procedure)
 
-        <div class="row g-2 g-md-5">
+        <div class="row g-2 g-md-5 mb-3 mb-md-0">
             <div class="col-12 col-md-3 pe-md-0">
                 <h4 class="user-select-all mb-3">
                     {{ $procedure['name'] }}
@@ -54,23 +59,25 @@
                 <p>
                     {{ $procedure['description'] ?? '' }}
                 </p>
-
             </div>
 
-            <div class="col">
-                <p class="user-select-none fw-light text-muted mb-1">Request:</p>
-                {!! $procedure['request'] ?? '' !!}
-            </div>
 
             <div class="col">
-                <p class="user-select-none fw-light text-muted mb-1">Response:</p>
-                {!! $procedure['response'] ?? '' !!}
+                <div class="p-4 {{ $loop->last ? 'rounded-bottom': '' }} {{ $loop->first ? 'rounded-top' : '' }}" style="background: rgb(37 42 55)">
+                <div class="row">
+                    <div class="col">
+                        <p class="user-select-none fw-light text-white opacity-50 mb-1 small">Request:</p>
+                        {!! $procedure['request'] ?? '' !!}
+                    </div>
+
+                    <div class="col">
+                        <p class="user-select-none fw-light text-white opacity-50 mb-1 small">Response:</p>
+                        {!! $procedure['response'] ?? '' !!}
+                    </div>
+                </div>
+                </div>
             </div>
         </div>
-
-        @if (!$loop->last)
-            <hr class="col-3 col-md-2 mb-5">
-        @endif
     @endforeach