Merge branch 'controller-namespace-issue-for-modules-in-urlprefixes' of github.com:php-openapi/yii2-openapi into 102-fractalaction-not-generated-for-root-path

Author: SOHELAHMED7

README.md

@@ -610,8 +610,8 @@ then the value for `comments` can be
 
 ### `x-route`
 
-To customize route (controller ID/action ID) for a path, use custom key `x-route` with value `<controller ID>/<action ID>`. It can be used for non-crud paths. It must be used under HTTP method key but not
-directly under the `paths` key of OpenAPI spec. Example:
+To customize [route](https://www.yiiframework.com/doc/guide/2.0/en/runtime-routing) (controller ID/action ID) for a path, use custom key `x-route` with value `[<module ID>/<child module ID>/...]<controller ID>/<action ID>`. It can be used for non-crud paths. It must be used under HTTP method key but not
+directly under the `paths` key of OpenAPI spec. Providing `<controller ID>` and `<action ID>` is required. Example:
 
 ```yaml
 paths:
@@ -681,7 +681,17 @@ Generated URL rules config for above is (in `urls.rest.php` or pertinent file):
     'POST a1/b1' => 'abc/xyz',
     'a1/b1' => 'abc/options',
 ```
-`x-route` does not support [Yii Modules](https://www.yiiframework.com/doc/guide/2.0/en/structure-modules).
+
+`x-route` must not start with slash `/`. For example `x-route: /user/posts` is incorrect. It must start with [module ID](https://www.yiiframework.com/doc/guide/2.0/en/structure-modules) or [controller ID](https://www.yiiframework.com/doc/guide/2.0/en/structure-controllers#controller-ids)
+
+#### Route, path and namespace
+
+Route, path and namespace for controller/action will be resolved in following manner (from highest priority to lowest):
+
+- [`x-route`](#x-route)
+- [`urlPrefixes`](https://github.com/php-openapi/yii2-openapi/blob/649743cf0a78743f550edcbd4e93fdffc55c76fd/src/lib/Config.php#L51)
+- [`controllerNamespace`](https://github.com/php-openapi/yii2-openapi/blob/649743cf0a78743f550edcbd4e93fdffc55c76fd/src/lib/Config.php#L77) of this lib
+- [`controllerNamespace`](https://github.com/yiisoft/yii2/blob/16f50626e1aa81200f109c1a455a5c9b18acfdda/framework/base/Application.php#L93) of Yii app
 
 ### `x-description-is-comment`
 

src/lib/Config.php

@@ -183,7 +183,7 @@ public function getOpenApi():OpenApi
         return $this->openApi;
     }
 
-    public function getPathFromNamespace(string $namespace):string
+    public static function getPathFromNamespace(string $namespace): string
     {
         return Yii::getAlias('@' . str_replace('\\', '/', ltrim($namespace, '\\')));
     }

src/lib/generators/ControllersGenerator.php

@@ -18,7 +18,6 @@
 use Laminas\Code\Generator\ValueGenerator;
 use Yii;
 use yii\gii\CodeFile;
-use yii\helpers\ArrayHelper;
 use yii\helpers\Inflector;
 
 class ControllersGenerator
@@ -38,7 +37,13 @@ class ControllersGenerator
     public function __construct(Config $config, array $actions = [])
     {
         $this->config = $config;
-        $this->controllers = ArrayHelper::index($actions, null, 'controllerId');
+        foreach ($actions as $action) {
+            $r = $action->getRoute();
+            $r = explode('/', $r);
+            array_pop($r);
+            array_pop($r);
+            $this->controllers[implode('/', $r) . '/' . $action->controllerId][] = $action;
+        }
         $this->files = new CodeFiles([]);
     }
 
@@ -51,22 +56,25 @@ public function generate():CodeFiles
             return new CodeFiles([]);
         }
         $namespace = $this->config->controllerNamespace ?? Yii::$app->controllerNamespace;
-        $path = $this->config->getPathFromNamespace($namespace);
+        $path = Config::getPathFromNamespace($namespace);
         $templateName = $this->config->useJsonApi ? 'controller_jsonapi.php' : 'controller.php';
 
-        foreach ($this->controllers as $controller => $actions) {
+        foreach ($this->controllers as $controllerWithPrefix => $actions) {
             $controllerNamespace = $namespace;
             $controllerPath = $path;
             /**
              * @var RestAction|FractalAction $action
              **/
             $action = $actions[0];
-            if ($action->prefix && !empty($action->prefixSettings)) {
+            if (!empty($action->prefixSettings)) {
                 $controllerNamespace = trim($action->prefixSettings['namespace'], '\\');
                 $controllerPath = $action->prefixSettings['path']
-                    ?? $this->config->getPathFromNamespace($controllerNamespace);
+                    ?? Config::getPathFromNamespace($controllerNamespace);
             }
-            $className = Inflector::id2camel($controller) . 'Controller';
+
+            $routeParts = explode('/', $controllerWithPrefix);
+
+            $className = Inflector::id2camel(end($routeParts)) . 'Controller';
             $this->files->add(new CodeFile(
                 Yii::getAlias($controllerPath . "/base/$className.php"),
                 $this->config->render(
@@ -86,6 +94,18 @@ public function generate():CodeFiles
                     $classFileGenerator->generate()
                 ));
             }
+
+            // generate Module.php file for modules
+            foreach ($action->modulesList as $moduleId => $moduleDetail) {
+                // only generate Module.php file if they do not exist, do not override
+                if (!file_exists(Yii::getAlias($moduleDetail['path'] . "/Module.php"))) {
+                    $moduleFileGenerator = $this->makeModuleFile('Module', $moduleDetail['namespace'], $moduleId, $action);
+                    $this->files->add(new CodeFile(
+                        Yii::getAlias($moduleDetail['path'] . "/Module.php"),
+                        $moduleFileGenerator->generate()
+                    ));
+                }
+            }
         }
         return $this->files;
     }
@@ -156,4 +176,37 @@ protected function makeCustomController(
         $classFileGenerator->setClasses([$reflection]);
         return $classFileGenerator;
     }
+
+    /**
+     * @param RestAction|FractalAction $action
+     */
+    public function makeModuleFile(string $class, string $namespace, $moduleId, $action): FileGenerator
+    {
+        $file = new FileGenerator;
+        $reflection = new ClassGenerator(
+            $class,
+            $namespace,
+            null,
+            'yii\base\Module'
+        );
+
+        $moduleIds = array_keys($action->modulesList);
+        $position = array_search($moduleId, $moduleIds);
+        $childModuleId = $childModuleCode = null;
+        if (array_key_exists($position + 1, $moduleIds)) { # if `true`, child module exists
+            $childModuleId = $moduleIds[$position + 1];
+            $childModuleNamespace = $action->modulesList[$childModuleId]['namespace'];
+            $childModuleCode = <<<PHP
+\$this->modules = [
+    '{$childModuleId}' => [
+        'class' => \\{$childModuleNamespace}\Module::class,
+    ],
+];
+PHP;
+        }
+
+        $reflection->addMethod('init', [], AbstractMemberGenerator::FLAG_PUBLIC, 'parent::init();' . PHP_EOL . $childModuleCode);
+        $file->setClasses([$reflection]);
+        return $file;
+    }
 }

src/lib/generators/JsonActionGenerator.php

@@ -74,12 +74,19 @@ protected function prepareAction(
             }
         }
 
+        $actionId = $routeData->isNonCrudAction() ? trim("{$actionType}-{$routeData->action}", '-')
+            : "$actionType{$routeData->action}";
+        if (!empty($customRoute)) {
+            $parts = explode('/', $customRoute);
+            $controllerId = $parts[count($parts) - 2];
+            $actionId = $parts[count($parts) - 1];
+        }
+
         return Yii::createObject(FractalAction::class, [
             [
                 'singularResourceKey' => $this->config->singularResourceKeys,
                 'type' => $routeData->type,
-                'id' => $routeData->isNonCrudAction() ? trim("{$actionType}-{$routeData->action}", '-')
-                    : "$actionType{$routeData->action}",
+                'id' => $actionId,
                 'controllerId' => $controllerId,
                 'urlPath' => $routeData->path,
                 'requestMethod' => strtoupper($method),
@@ -96,6 +103,8 @@ protected function prepareAction(
                 'expectedRelations' => $expectedRelations,
                 'prefix' => $routeData->getPrefix(),
                 'prefixSettings' => $routeData->getPrefixSettings(),
+                'xRoute' => $customRoute,
+                'modulesList' => $routeData->listModules()
             ],
         ]);
     }

src/lib/generators/ModelsGenerator.php

@@ -46,8 +46,8 @@ public function generate():CodeFiles
         if (!$this->config->generateModels) {
             return $this->files;
         }
-        $modelPath = $this->config->getPathFromNamespace($this->config->modelNamespace);
-        $fakerPath = $this->config->getPathFromNamespace($this->config->fakerNamespace);
+        $modelPath = Config::getPathFromNamespace($this->config->modelNamespace);
+        $fakerPath = Config::getPathFromNamespace($this->config->fakerNamespace);
         if ($this->config->generateModelFaker) {
             $this->files->add(new CodeFile(
                 Yii::getAlias("$fakerPath/BaseModelFaker.php"),

src/lib/generators/RestActionGenerator.php

@@ -71,8 +71,8 @@ protected function resolvePath(string $path, PathItem $pathItem):array
     {
         $actions = [];
 
-        $routeData = Yii::createObject(RouteData::class, [$pathItem, $path, $this->config->urlPrefixes]);
         foreach ($pathItem->getOperations() as $method => $operation) {
+            $routeData = Yii::createObject(RouteData::class, [$path, $pathItem, $method, $operation, $this->config->urlPrefixes]);
             $customRoute = null;
             if (isset($operation->{CustomSpecAttr::ROUTE})) { # https://github.com/cebe/yii2-openapi/issues/144
                 $customRoute = $operation->{CustomSpecAttr::ROUTE};
@@ -119,7 +119,10 @@ protected function prepareAction(
             $this->knownModelClasses[$routeData->path] = $modelClass;
         }
 
-        if ($routeData->isRelationship()) {
+        if (!empty($customRoute)) {
+            $parts = explode('/', $customRoute);
+            $controllerId = $parts[count($parts) - 2];
+        } elseif ($routeData->isRelationship()) {
             $controllerId = $routeData->controller;
             $modelClass = Inflector::id2camel(Inflector::singularize($controllerId));
             $controllerId = isset($this->config->controllerModelMap[$modelClass])
@@ -129,15 +132,17 @@ protected function prepareAction(
             $controllerId = isset($this->config->controllerModelMap[$modelClass])
                 ? Inflector::camel2id($this->config->controllerModelMap[$modelClass])
                 : Inflector::camel2id($modelClass);
-        } elseif (!empty($customRoute)) {
-            $controllerId = explode('/', $customRoute)[0];
         } else {
             $controllerId = $routeData->controller;
         }
         $action = Inflector::camel2id($routeData->action);
+        if (!$action && !$actionType) {
+            $action = 'index';
+        }
         if (!empty($customRoute)) {
             $actionType = '';
-            $action = explode('/', $customRoute)[1];
+            $parts = explode('/', $customRoute);
+            $action = $parts[count($parts) - 1];
         }
         return Yii::createObject(RestAction::class, [
             [
@@ -154,7 +159,9 @@ protected function prepareAction(
                     : null,
                 'responseWrapper' => $responseWrapper,
                 'prefix' => $routeData->getPrefix(),
-                'prefixSettings' => $routeData->getPrefixSettings()
+                'prefixSettings' => $routeData->getPrefixSettings(),
+                'xRoute' => $customRoute,
+                'modulesList' => $routeData->listModules()
             ],
         ]);
     }

src/lib/generators/TransformersGenerator.php

@@ -48,7 +48,7 @@ public function generate():CodeFiles
         if (!$this->config->generateControllers || !$this->config->useJsonApi) {
             return $this->files;
         }
-        $transformerPath = $this->config->getPathFromNamespace($this->config->transformerNamespace);
+        $transformerPath = Config::getPathFromNamespace($this->config->transformerNamespace);
         foreach ($this->models as $model) {
             $transformer = Yii::createObject(Transformer::class, [
                $model,

src/lib/items/OptionsRoutesTrait.php renamed to src/lib/items/ActionHelperTrait.php

@@ -7,27 +7,36 @@
 
 namespace cebe\yii2openapi\lib\items;
 
-trait OptionsRoutesTrait
+trait ActionHelperTrait
 {
+    public ?string $xRoute = null;
+
+    # list of module this action is part of. 'key' is module ID and 'value' is path where Module.php file must be generated
+    public array $modulesList = [];
+
+    /**
+     * @see $isDuplicate
+     * https://github.com/cebe/yii2-openapi/issues/84
+     * see `x-route` in README.md
+     * Used for generating only one action for paths like: `GET /calendar/domains` and `GET /calendar/domains/{id}` given that they have same `x-route`.
+     * If duplicates routes have same params then `false`, else action is generated with no (0) params `true`
+     */
+    public bool $zeroParams = false;
+
+    /**
+     * https://github.com/cebe/yii2-openapi/issues/84
+     * Generate only one action for paths like: `GET /calendar/domains` and `GET /calendar/domains/{id}` given that they have same `x-route`.
+     * @see $zeroParams
+     * see `x-route` in README.md
+     */
+    public bool $isDuplicate = false;
+
     public function getOptionsRoute():string
     {
-        if ($this->prefix && !empty($this->prefixSettings)) {
-            if (isset($this->prefixSettings['module'])) {
-                $prefix = $this->prefixSettings['module'];
-                return static::finalOptionsRoute($prefix, $this->controllerId);
-            } elseif (isset($this->prefixSettings['namespace']) && str_contains($this->prefixSettings['namespace'], '\modules\\')) { # if `module` not present then check in namespace and then in path
-                $prefix = static::computeModule('\\', $this->prefixSettings['namespace']);
-                if ($prefix) {
-                    return static::finalOptionsRoute($prefix, $this->controllerId);
-                }
-            } elseif (isset($this->prefixSettings['path']) && str_contains($this->prefixSettings['path'], '/modules/')) {
-                $prefix = static::computeModule('/', $this->prefixSettings['path']);
-                if ($prefix) {
-                    return static::finalOptionsRoute($prefix, $this->controllerId);
-                }
-            }
-        }
-        return $this->controllerId.'/options';
+        $r = $this->getRoute();
+        $r = explode('/', $r);
+        array_pop($r);
+        return implode('/', $r) . '/options';
     }
 
     /**
@@ -59,4 +68,30 @@ public static function finalOptionsRoute(string $prefix, string $controllerId):
     {
         return trim($prefix, '/') . '/' . $controllerId . '/options';
     }
+
+    public function getRoute(): string
+    {
+        if ($this->xRoute) {
+            return $this->xRoute;
+        }
+
+        if (!empty($this->prefixSettings)) {
+            if (isset($this->prefixSettings['module'])) {
+                $prefix = $this->prefixSettings['module'];
+                return trim($prefix, '/') . '/' . $this->controllerId . ($this->id ? '/' . $this->id : '');
+            } elseif (isset($this->prefixSettings['namespace']) && str_contains($this->prefixSettings['namespace'], '\modules\\')) { # if `module` not present then check in namespace and then in path
+                $prefix = static::computeModule('\\', $this->prefixSettings['namespace']);
+                if ($prefix) {
+                    return trim($prefix, '/') . '/' . $this->controllerId . ($this->id ? '/' . $this->id : '');
+                }
+            } elseif (isset($this->prefixSettings['path']) && str_contains($this->prefixSettings['path'], '/modules/')) {
+                $prefix = static::computeModule('/', $this->prefixSettings['path']);
+                if ($prefix) {
+                    return trim($prefix, '/') . '/' . $this->controllerId . ($this->id ? '/' . $this->id : '');
+                }
+            }
+        }
+
+        return $this->controllerId . ($this->id ? '/' . $this->id : '');
+    }
 }

src/lib/items/FractalAction.php

@@ -32,7 +32,7 @@
  */
 final class FractalAction extends BaseObject
 {
-    use OptionsRoutesTrait;
+    use ActionHelperTrait;
 
     /**@var string* */
     public $id;
@@ -95,15 +95,6 @@ private function templateFactory():FractalActionTemplates
         return $this->templateFactory;
     }
 
-    public function getRoute():string
-    {
-        if ($this->prefix && !empty($this->prefixSettings)) {
-            $prefix = $this->prefixSettings['module'] ?? $this->prefix;
-            return trim($prefix, '/').'/'.$this->controllerId.'/'.$this->id;
-        }
-        return $this->controllerId.'/'.$this->id;
-    }
-
     public function getBaseModelName():string
     {
         return $this->modelFqn ? StringHelper::basename($this->modelFqn) : '';