From e3022fc5fc4d6c08896cab546e28099c3d4a14bf Mon Sep 17 00:00:00 2001 From: Alexandr Chernyaev Date: Fri, 3 Jan 2025 02:42:39 +0300 Subject: [PATCH] Replace @phpdoc annotations with PHP attributes --- composer.json | 4 +- src/Annotations/Param.php | 21 ---------- src/Annotations/Result.php | 21 ---------- src/Attributes/RpcMethod.php | 19 +++++++++ src/Commands/DocsCommand.php | 2 +- src/Docs.php | 74 ++++++++++++---------------------- src/Guide.php | 12 ------ tests/FixtureDocsProcedure.php | 20 ++++----- views/docs.blade.php | 37 ++++++++++------- 9 files changed, 76 insertions(+), 134 deletions(-) delete mode 100644 src/Annotations/Param.php delete mode 100644 src/Annotations/Result.php create mode 100644 src/Attributes/RpcMethod.php delete mode 100644 src/Guide.php diff --git a/composer.json b/composer.json index 72ff050..f5f0880 100644 --- 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 deleted file mode 100644 index 5c8dd31..0000000 --- a/src/Annotations/Param.php +++ /dev/null @@ -1,21 +0,0 @@ - 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 index 7a3680d..85e13c0 100644 --- 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,7 +112,7 @@ private function highlight(array $value): Stringable $code = highlight_string('replaceFirst('<?php ', '') + ->replaceFirst('<?php ', '') ->replace('    ', '  '); $keys = $this->arrayKeysMulti($value); @@ -149,7 +120,14 @@ private function highlight(array $value): Stringable foreach ($keys as $item) { $docs = $docs->replace( '"'.$item.'"', - '"'.$item.'"' + '"'.$item.'"' + ); + } + + foreach ($keys as $item) { + $docs = $docs->replace( + '"'.$item.'"', + '"'.$item.'"' ); } diff --git a/src/Guide.php b/src/Guide.php deleted file mode 100644 index 8928a75..0000000 --- a/src/Guide.php +++ /dev/null @@ -1,12 +0,0 @@ - '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 index ef17aca..94e10ba 100644 --- 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; } @@ -33,10 +33,15 @@
- Starter template + + + + {{ $title }} - { JSON-RPC } Documentation + { JSON-RPC } @@ -45,7 +50,7 @@ @foreach($procedures as $procedure) -
+

{{ $procedure['name'] }} @@ -54,23 +59,25 @@

{{ $procedure['description'] ?? '' }}

-

-
-

Request:

- {!! $procedure['request'] ?? '' !!} -
-

Response:

- {!! $procedure['response'] ?? '' !!} +
+
+
+

Request:

+ {!! $procedure['request'] ?? '' !!} +
+ +
+

Response:

+ {!! $procedure['response'] ?? '' !!} +
+
+
- - @if (!$loop->last) -
- @endif @endforeach