gen routes for module controllers, fix doc generation

Author: hinanaya

core/data/routes/templates/header.php

@@ -29,7 +29,7 @@
           $nav_name = substr($nav_name, 0, strlen($nav_name) - 5);
         }
       ?>
-        <a href="<?=$nav_package . '.' . $nav_item?>.html"><?=($nav_package == 'pages' ? '' : (strtolower($nav_package) . '.')) . $nav_name?></a>
+        <a href="<?=$nav_package . '.' . $nav_item?>.html"><?=$nav_name?></a>
       <?php } ?>
     <?php } ?>
     </nav>

core/routes/RouteClass.php

@@ -7,14 +7,16 @@ class RouteClass
     public $name;
     public $description;
     public $package;
+    public $module;
 
     private $methods;
 
-    public function __construct($name, $description = [], $package = "NoPak")
+    public function __construct($name, $description = [], $package = "NoPak", $module = null)
     {
         $this->name = $name;
         $this->description = $description;
         $this->package = $package;
+        $this->module = $module;
 
         $this->methods = array();
     }

core/support/Routes.php

@@ -22,6 +22,9 @@ public function __construct()
         $this->targetJson = OB_CACHE . '/routes.json';
         $this->sourceDirs = [
             OB_LOCAL . '/core/controllers/',
+            OB_LOCAL . '/core/models/',
+            ...glob(OB_LOCAL . '/modules/*/controllers/'),
+            ...glob(OB_LOCAL . '/modules/*/models/'),
         ];
     }
 
@@ -39,6 +42,10 @@ public function needsUpdate(): bool
         }
 
         foreach ($this->sourceDirs as $dir) {
+            if (! str_ends_with($dir, '/controllers/')) {
+                continue;
+            }
+
             foreach (new \FilesystemIterator($dir) as $file) {
                 if ($file->isDir()) {
                     continue;
@@ -53,7 +60,7 @@ public function needsUpdate(): bool
                     continue;
                 }
 
-                if (! $updated[$file->getRealPath()] || $updated[$file->getRealPath()] !== $file->getMTime()) {
+                if (! ($updated[$file->getRealPath()] ?? null) || $updated[$file->getRealPath()] !== $file->getMTime()) {
                     return true;
                 }
             }
@@ -67,6 +74,10 @@ public function genRoutes(): bool
         $docFiles = [];
         $updated = [];
         foreach ($this->sourceDirs as $dir) {
+            if (! str_ends_with($dir, '/controllers/')) {
+                continue;
+            }
+
             foreach (new \FilesystemIterator($dir) as $file) {
                 if ($file->isDir()) {
                     continue;
@@ -85,7 +96,7 @@ public function genRoutes(): bool
                 $blocks = $this->parse_blocks($content);
                 $updated[$file->getRealPath()] = $file->getMTime();
 
-                $docFiles[] = $this->generate_tree($blocks, $file->getFilename(), basename($dir));
+                $docFiles[] = $this->generate_tree($blocks, $file->getFilename(), $dir);
             }
         }
 
@@ -94,6 +105,19 @@ public function genRoutes(): bool
             foreach ($file->getClass()->getMethods() as $method) {
                 if (count($method->routes) > 0) {
                     foreach ($method->routes as $route) {
+                        // Each route is stored in JSON as an array containing elements in the format
+                        // [
+                        //      /api/v2/route/string,
+                        //      controller,
+                        //      method
+                        // ]
+                        //
+                        // When a route comes from a module, it is instead stored as
+                        // [
+                        //      /api/v2/module/ModuleName/route/string,
+                        //      controller,
+                        //      method
+                        // ]
                         $routes[$route[0]][] = [$route[1], strtolower($file->getClass()->name), $method->name];
                     }
                 }
@@ -159,7 +183,13 @@ public function genDocs(string $targetDir): bool
                 $content = $this->parse_clean(file_get_contents($file->getPathname()));
                 $blocks = $this->parse_blocks($content);
 
-                $doc_files[] = $this->generate_tree($blocks, $file->getFilename(), basename($dir));
+                if (! str_ends_with(rtrim($dir, '/'), '/core/controllers')) {
+                    $moduleStr = '/modules/' . basename(dirname($dir)) . '/controllers';
+                } else {
+                    $moduleStr = '/core/controllers';
+                }
+
+                $doc_files[] = $this->generate_tree($blocks, $file->getFilename(), $moduleStr);
             }
         }
 
@@ -434,6 +464,11 @@ private function generate_tree(array $blocks, string $filename, string $dir): Ro
                                 break;
                         }
                     }
+
+                    if (! str_ends_with(rtrim($dir, '/'), '/core/controllers')) {
+                        $moduleStr = basename(dirname($dir));
+                        $doc_class->module = $moduleStr;
+                    }
                     break;
                 case 'method':
                     $method = new RouteMethod($decl['name'], $doc['description'], $decl['visibility'], $decl['args']);
@@ -455,7 +490,12 @@ private function generate_tree(array $blocks, string $filename, string $dir): Ro
                             case 'route':
                                 $route_method = substr($tag[1], 0, strpos($tag[1], " "));
                                 $route_url = substr($tag[1], strpos($tag[1], " ") + 1);
-                                $route_url = '/api/' . trim($route_url, '/');
+
+                                if ($doc_class !== null && $doc_class->module !== null) {
+                                    $route_url = '/api/v2/module/' . $doc_class->module . '/' . trim($route_url, '/');
+                                } else {
+                                    $route_url = '/api/' . trim($route_url, '/');
+                                }
 
                                 if (!in_array($route_method, ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'])) {
                                     error_log('[E] Unsupported HTTP method used in @route tag: ' . $tag[1] . ".\n");

modules/Logger/controllers/Logger.php

@@ -3,6 +3,11 @@
 // Copyright 2012-2024 OpenBroadcaster, Inc.
 // SPDX-License-Identifier: AGPL-3.0-or-later
 
+/**
+ * Logger example module.
+ *
+ * @package Controller.Logger
+ */
 namespace OpenBroadcaster\Modules\Logger\Controllers;
 
 use OpenBroadcaster\Base\Controller;
@@ -20,6 +25,15 @@ public function __construct()
 
 	}
 
+	/**
+	 * View log.
+	 *
+	 * @param limit
+	 * @param offset
+	 * @return [entries, total]
+	 *
+	 * @route GET /logger
+	 */
 	public function viewLog()
 	{
 
@@ -32,6 +46,11 @@ public function viewLog()
 		return array(true,'Log Entries.',array('entries'=>$entries, 'total'=>$total));
 	}
 
+	/**
+	 * Clear log.
+	 *
+	 * @route DELETE /logger
+	 */
 	public function clearLog()
 	{
 		$this->LoggerModel('logClear');