Controller reference (Close #47) (#109)

kubk · web-flow · commit c72a5ea23a30 · 2023-08-12T10:10:00.000+03:00
* Controller reference (Close #47)
diff --git a/src/Ast/Converter.php b/src/Ast/Converter.php
@@ -5,6 +5,7 @@
 namespace Riverwaysoft\PhpConverter\Ast;
 
 use PhpParser\NodeTraverser;
+use PhpParser\NodeVisitor\ParentConnectingVisitor;
 use PhpParser\Parser;
 use PhpParser\ParserFactory;
 
@@ -28,6 +29,7 @@ public function convert(iterable $listings): ConverterResult
         $converterResult = new ConverterResult();
 
         $traverser = new NodeTraverser();
+        $traverser->addVisitor(new ParentConnectingVisitor());
         foreach ($this->visitors as $visitor) {
             $traverser->addVisitor($visitor);
         }
@@ -38,7 +40,7 @@ public function convert(iterable $listings): ConverterResult
         }
 
         foreach ($this->visitors as $visitor) {
-            $converterResult->merge($visitor->popResult());
+            $converterResult->merge($visitor->getResult());
         }
 
         return $converterResult;
diff --git a/src/Ast/ConverterVisitor.php b/src/Ast/ConverterVisitor.php
@@ -8,6 +8,5 @@
 
 abstract class ConverterVisitor extends NodeVisitorAbstract
 {
-    /** @phpstan-impure */
-    abstract public function popResult(): ConverterResult;
+    abstract public function getResult(): ConverterResult;
 }
diff --git a/src/Ast/DtoVisitor.php b/src/Ast/DtoVisitor.php
@@ -218,10 +218,8 @@ public function resolveExpressionType(Class_|Enum_ $node): ExpressionType
             : ExpressionType::class();
     }
 
-    public function popResult(): ConverterResult
+    public function getResult(): ConverterResult
     {
-        $result = $this->converterResult;
-        $this->converterResult = new ConverterResult();
-        return $result;
+        return $this->converterResult;
     }
 }
diff --git a/src/Bridge/ApiPlatform/ApiPlatformDtoResourceVisitor.php b/src/Bridge/ApiPlatform/ApiPlatformDtoResourceVisitor.php
@@ -399,10 +399,8 @@ private function getAttributeArgumentByName(Attribute $attribute, string $name):
         return null;
     }
 
-    public function popResult(): ConverterResult
+    public function getResult(): ConverterResult
     {
-        $result = $this->converterResult;
-        $this->converterResult = new ConverterResult();
-        return $result;
+        return $this->converterResult;
     }
 }
diff --git a/src/Bridge/Symfony/SymfonyControllerVisitor.php b/src/Bridge/Symfony/SymfonyControllerVisitor.php
@@ -202,13 +202,22 @@ private function createApiEndpoint(ClassMethod $node): void
                 $routeParams,
             ),
             queryParams: $queryParams,
+            codeReference: $this->generateCodeReference($node),
         ));
     }
 
-    public function popResult(): ConverterResult
+    private function generateCodeReference(ClassMethod $node): string|null
     {
-        $result = $this->converterResult;
-        $this->converterResult = new ConverterResult();
-        return $result;
+        $parent = $node->getAttribute('parent');
+        if (!($parent instanceof Node\Stmt\Class_)) {
+            return null;
+        }
+
+        return sprintf("%s::%s", $parent->name->name, $node->name->name);
+    }
+
+    public function getResult(): ConverterResult
+    {
+        return $this->converterResult;
     }
 }
diff --git a/src/Dto/ApiClient/ApiEndpoint.php b/src/Dto/ApiClient/ApiEndpoint.php
@@ -21,6 +21,7 @@ public function __construct(
         public array $routeParams = [],
         /** @var ApiEndpointParam[] */
         public array $queryParams = [],
+        public string|null $codeReference = null,
     ) {
         if (str_contains($this->route, '.')) {
             throw new Exception(sprintf("Invalid character . in route %s", $this->route));
@@ -36,6 +37,7 @@ public function jsonSerialize(): mixed
             'input' => $this->input,
             'output' => $this->output,
             'queryParams' => $this->queryParams,
+            'codeReference' => $this->codeReference,
         ];
     }
 }
diff --git a/src/OutputGenerator/TypeScript/AxiosEndpointGenerator.php b/src/OutputGenerator/TypeScript/AxiosEndpointGenerator.php
@@ -20,7 +20,12 @@ public function __construct(
 
     public function generate(ApiEndpoint $apiEndpoint, DtoList $dtoList): string
     {
-        $string = "\nexport const %s = (%s): %s => {\n%s\n}\n";
+        $string = "\n%sexport const %s = (%s): %s => {\n%s\n}\n";
+
+        $codeReference = '';
+        if ($apiEndpoint->codeReference) {
+            $codeReference = sprintf("/** @see %s */\n", $apiEndpoint->codeReference);
+        }
 
         $fullRoute = $apiEndpoint->route . '/' . $apiEndpoint->method->getType();
         $name = $this->normalizeEndpointName($fullRoute);
@@ -70,7 +75,7 @@ public function generate(ApiEndpoint $apiEndpoint, DtoList $dtoList): string
     .%s<%s>(`%s`%s)
     .then((response) => response.data);', $apiEndpoint->method->getType(), $outputType, $route, $formParamsAsString);
 
-        return sprintf($string, $name, $params, $returnType, $body);
+        return sprintf($string, $codeReference, $name, $params, $returnType, $body);
     }
 
     private function normalizeEndpointName(string $str): string
diff --git a/tests/__snapshots__/ConverterTest__testFilterClassesByPhpAnnotation__1.json b/tests/__snapshots__/ConverterTest__testFilterClassesByPhpAnnotation__1.json
@@ -12,7 +12,8 @@
                     "generics": []
                 }
             },
-            "queryParams": []
+            "queryParams": [],
+            "codeReference": "SomeController::getUserMethodsArray"
         }
     ]
 }
diff --git a/tests/__snapshots__/ConverterTest__testFilterClassesByPhpAttribute__1.json b/tests/__snapshots__/ConverterTest__testFilterClassesByPhpAttribute__1.json
@@ -12,7 +12,8 @@
                     "generics": []
                 }
             },
-            "queryParams": []
+            "queryParams": [],
+            "codeReference": "SomeController::getUserMethodsArray"
         },
         {
             "route": "\/api\/users",
@@ -31,7 +32,8 @@
                 "context": [],
                 "generics": []
             },
-            "queryParams": []
+            "queryParams": [],
+            "codeReference": "SomeController::createUser"
         },
         {
             "route": "\/api\/users\/{id}",
@@ -50,7 +52,8 @@
                 "context": [],
                 "generics": []
             },
-            "queryParams": []
+            "queryParams": [],
+            "codeReference": "SomeController::getUser"
         },
         {
             "route": "\/api\/users_methods_string",
@@ -62,7 +65,8 @@
                 "context": [],
                 "generics": []
             },
-            "queryParams": []
+            "queryParams": [],
+            "codeReference": "SomeController::getUserMethodsString"
         },
         {
             "route": "\/api\/users_reversed_order",
@@ -76,7 +80,8 @@
                     "generics": []
                 }
             },
-            "queryParams": []
+            "queryParams": [],
+            "codeReference": "SomeController::getUserMethodsArrayReversedOrder"
         }
     ]
 }
diff --git a/tests/__snapshots__/TypeScriptGeneratorTest__testTypesWithApiClientAndOverrideReturn__1.ts b/tests/__snapshots__/TypeScriptGeneratorTest__testTypesWithApiClientAndOverrideReturn__1.ts
@@ -14,30 +14,35 @@ export type UserShortOutput = {
   id: string;
 };
 
+/** @see UserController::annotationsReturn */
 export const apiAnnotationsReturnGet = (): Promise<UserOutput> => {
   return axios
     .get<UserOutput>(`/api/annotations-return`)
     .then((response) => response.data);
 }
 
+/** @see UserController::annotationsReturnTakePrecedenceOverDtoEndpoint */
 export const apiAnnotationsReturnPrecedenceGet = (): Promise<UserShortOutput> => {
   return axios
     .get<UserShortOutput>(`/api/annotations-return-precedence`)
     .then((response) => response.data);
 }
 
+/** @see UserController::nestedGenericsSimpleType */
 export const apiNestedGenericsSimpleTypeGet = (): Promise<JsonResponse<string[]>> => {
   return axios
     .get<JsonResponse<string[]>>(`/api/nested-generics-simple-type`)
     .then((response) => response.data);
 }
 
+/** @see UserController::nestedGenericAnnotationReturn */
 export const apiRouteWithNestedGenericsAnnotationsReturnGet = (): Promise<JsonResponse<UserOutput>> => {
   return axios
     .get<JsonResponse<UserOutput>>(`/api/route-with-nested-generics-annotations-return`)
     .then((response) => response.data);
 }
 
+/** @see UserController::nestedGenericAnnotationUnionReturn */
 export const apiRouteWithNestedGenericsUnionAnnotationsReturnGet = (): Promise<JsonResponse<UserOutput[]>> => {
   return axios
     .get<JsonResponse<UserOutput[]>>(`/api/route-with-nested-generics-union-annotations-return`)
diff --git a/tests/__snapshots__/TypeScriptGeneratorTest__testTypesWithApiClient__1.ts b/tests/__snapshots__/TypeScriptGeneratorTest__testTypesWithApiClient__1.ts
@@ -20,48 +20,56 @@ export type UserOutput = {
   hasDefaultValue: string;
 };
 
+/** @see UserController::routeWithAnnotationsReturn */
 export const apiRouteWithAnnotationsReturnGet = (): Promise<UserOutput> => {
   return axios
     .get<UserOutput>(`/api/route-with-annotations-return`)
     .then((response) => response.data);
 }
 
+/** @see UserController::routeWithName */
 export const apiRouteWithNameGet = (): Promise<null> => {
   return axios
     .get<null>(`/api/route-with-name`)
     .then((response) => response.data);
 }
 
+/** @see UserController::routeWithPath */
 export const apiRouteWithPathGet = (): Promise<null> => {
   return axios
     .get<null>(`/api/route-with-path`)
     .then((response) => response.data);
 }
 
+/** @see UserController::getUsers */
 export const apiUsersGet = (): Promise<UserOutput[]> => {
   return axios
     .get<UserOutput[]>(`/api/users`)
     .then((response) => response.data);
 }
 
+/** @see UserController::getUser */
 export const apiUsersPost = (input: CreateUserInput): Promise<UserOutput> => {
   return axios
     .post<UserOutput>(`/api/users`, input)
     .then((response) => response.data);
 }
 
+/** @see UserController::getUsersWithFilters */
 export const apiUsersWithFiltersGet = (query: FilterQuery): Promise<UserOutput[]> => {
   return axios
     .get<UserOutput[]>(`/api/users-with-filters`, { params: query })
     .then((response) => response.data);
 }
 
+/** @see UserController::getUser */
 export const apiUsersUserGet = (user: string): Promise<UserOutput> => {
   return axios
     .get<UserOutput>(`/api/users/${user}`)
     .then((response) => response.data);
 }
 
+/** @see UserController::getUser */
 export const apiUsersUpdateItUserToUpdatePut = (userToUpdate: string, input: UpdateUserInput): Promise<UserOutput> => {
   return axios
     .put<UserOutput>(`/api/users_update-it/${userToUpdate}`, input)

Original file line number	Diff line number	Diff line change
`@@ -5,6 +5,7 @@`
`5`	`5`	`namespace Riverwaysoft\PhpConverter\Ast;`
`6`	`6`
`7`	`7`	`use PhpParser\NodeTraverser;`
	`8`	`+use PhpParser\NodeVisitor\ParentConnectingVisitor;`
`8`	`9`	`use PhpParser\Parser;`
`9`	`10`	`use PhpParser\ParserFactory;`
`10`	`11`
`@@ -28,6 +29,7 @@ public function convert(iterable $listings): ConverterResult`
`28`	`29`	`$converterResult = new ConverterResult();`
`29`	`30`
`30`	`31`	`$traverser = new NodeTraverser();`
	`32`	`+ $traverser->addVisitor(new ParentConnectingVisitor());`
`31`	`33`	`foreach ($this->visitors as $visitor) {`
`32`	`34`	`$traverser->addVisitor($visitor);`
`33`	`35`	`}`
`@@ -38,7 +40,7 @@ public function convert(iterable $listings): ConverterResult`
`38`	`40`	`}`
`39`	`41`
`40`	`42`	`foreach ($this->visitors as $visitor) {`
`41`		`- $converterResult->merge($visitor->popResult());`
	`43`	`+ $converterResult->merge($visitor->getResult());`
`42`	`44`	`}`
`43`	`45`
`44`	`46`	`return $converterResult;`
Original file line number	Diff line number	Diff line change
`@@ -8,6 +8,5 @@`
`8`	`8`
`9`	`9`	`abstract class ConverterVisitor extends NodeVisitorAbstract`
`10`	`10`	`{`
`11`		`- /** @phpstan-impure */`
`12`		`- abstract public function popResult(): ConverterResult;`
	`11`	`+ abstract public function getResult(): ConverterResult;`
`13`	`12`	`}`
Original file line number	Diff line number	Diff line change
`@@ -218,10 +218,8 @@ public function resolveExpressionType(Class_\|Enum_ $node): ExpressionType`
`218`	`218`	`: ExpressionType::class();`
`219`	`219`	`}`
`220`	`220`
`221`		`- public function popResult(): ConverterResult`
	`221`	`+ public function getResult(): ConverterResult`
`222`	`222`	`{`
`223`		`- $result = $this->converterResult;`
`224`		`- $this->converterResult = new ConverterResult();`
`225`		`- return $result;`
	`223`	`+ return $this->converterResult;`
`226`	`224`	`}`
`227`	`225`	`}`
Original file line number	Diff line number	Diff line change
`@@ -399,10 +399,8 @@ private function getAttributeArgumentByName(Attribute $attribute, string $name):`
`399`	`399`	`return null;`
`400`	`400`	`}`
`401`	`401`
`402`		`- public function popResult(): ConverterResult`
	`402`	`+ public function getResult(): ConverterResult`
`403`	`403`	`{`
`404`		`- $result = $this->converterResult;`
`405`		`- $this->converterResult = new ConverterResult();`
`406`		`- return $result;`
	`404`	`+ return $this->converterResult;`
`407`	`405`	`}`
`408`	`406`	`}`
Original file line number	Diff line number	Diff line change
`@@ -12,7 +12,8 @@`
`12`	`12`	`"generics": []`
`13`	`13`	`}`
`14`	`14`	`},`
`15`		`- "queryParams": []`
	`15`	`+ "queryParams": [],`
	`16`	`+ "codeReference": "SomeController::getUserMethodsArray"`
`16`	`17`	`}`
`17`	`18`	`]`
`18`	`19`	`}`