feat: add dynamic namespace routing and services:list command

- ServiceRouter::dynamic() registers catch-all route for namespace
- ServiceRouter::handle() resolves controller at request time, 404 if not found
- RouteOption::NS constant for namespace-based routing
- ServicesListCommand lists all discovered services with name, class, type, path

Closes #383
Closes #385

Author: Ibrahim BinAlshikh

WebFiori/Framework/App.php

@@ -375,6 +375,7 @@ public static function getRunner() : Runner {
                     '\\WebFiori\\Framework\\Cli\\Commands\\FreshMigrationsCommand',
                     '\\WebFiori\\Framework\\Cli\\Commands\\SkipMigrationsCommand',
                     '\\WebFiori\\Framework\\Cli\\Commands\\StepMigrationsCommand',
+                    '\\WebFiori\\Framework\\Cli\\Commands\\ServicesListCommand',
                 ];
 
                 foreach ($commands as $c) {

WebFiori/Framework/Cli/Commands/ServicesListCommand.php

@@ -0,0 +1,55 @@
+<?php
+
+/**
+ * This file is licensed under MIT License.
+ *
+ * Copyright (c) 2026-present WebFiori Framework
+ *
+ * For more information on the license, please visit:
+ * https://github.com/WebFiori/.github/blob/main/LICENSE
+ *
+ */
+namespace WebFiori\Framework\Cli\Commands;
+
+use WebFiori\Cli\Command;
+use WebFiori\Framework\Router\ServiceRouter;
+
+/**
+ * CLI command to list all discovered services.
+ *
+ * @author Ibrahim
+ */
+class ServicesListCommand extends Command {
+    public function __construct() {
+        parent::__construct('services:list', [], 'List all auto-discovered API services.');
+    }
+
+    public function exec(): int {
+        $discovered = ServiceRouter::getDiscovered();
+
+        if (empty($discovered)) {
+            $this->info('No services discovered. Use ServiceRouter::discover() to register services.');
+
+            return 0;
+        }
+
+        $this->println('');
+        $this->println(sprintf('  %-15s %-45s %-10s %s', 'Name', 'Class', 'Type', 'Path'));
+        $this->println(str_repeat('-', 90));
+
+        foreach ($discovered as $name => $entry) {
+            $this->println(sprintf(
+                '  %-15s %-45s %-10s %s',
+                $name,
+                $entry['class'],
+                $entry['type'],
+                $entry['path']
+            ));
+        }
+
+        $this->println('');
+        $this->info('Total: ' . count($discovered) . ' service(s).');
+
+        return 0;
+    }
+}

WebFiori/Framework/Router/RouteOption.php

@@ -72,4 +72,8 @@ class RouteOption {
      * An option which is used to set an array of allowed values to route parameters.
      */
     const VALUES = 'vars-values';
+    /**
+     * An option to specify a namespace for dynamic service resolution.
+     */
+    const NS = 'namespace';
 }

WebFiori/Framework/Router/ServiceRouter.php

@@ -94,6 +94,80 @@ public static function reset(): void {
         self::$discovered = [];
     }
 
+    /**
+     * Register a dynamic namespace route that resolves services at request time.
+     *
+     * Usage:
+     * ```php
+     * ServiceRouter::dynamic('App\\Apis', '/apis/{controller}', [...options]);
+     * ```
+     *
+     * @param string $namespace Namespace to search for services.
+     * @param string $path Route path with {controller} parameter.
+     * @param array $routeOptions Shared route options (middleware, etc.).
+     * @param string|null $directory Optional directory override.
+     */
+    public static function dynamic(string $namespace, string $path, array $routeOptions = [], ?string $directory = null): void {
+        $options = array_merge($routeOptions, [
+            RouteOption::PATH => $path,
+            RouteOption::TO => function () use ($namespace, $directory) {
+                $controllerName = App::getRequest()->getParam('controller');
+
+                if ($controllerName === null) {
+                    $controllerName = $_GET['controller'] ?? null;
+                }
+
+                if ($controllerName === null) {
+                    App::getResponse()->setCode(404);
+                    App::getResponse()->write(json_encode([
+                        'message' => 'Controller parameter missing.',
+                        'type' => 'error'
+                    ]));
+
+                    return;
+                }
+
+                self::handle($controllerName, $namespace, $directory);
+            },
+        ]);
+
+        Router::api($options);
+    }
+
+    /**
+     * Handle a dynamic controller request.
+     *
+     * @param string $controllerName The controller name from the URL.
+     * @param string $namespace Namespace to search.
+     * @param string|null $directory Optional directory to scan.
+     */
+    public static function handle(string $controllerName, string $namespace, ?string $directory = null): void {
+        $dir = $directory ?? self::namespaceToPath($namespace);
+        $map = self::scanNamespace($namespace, $dir);
+
+        if (isset($map[$controllerName])) {
+            $entry = $map[$controllerName];
+
+            if ($entry['type'] === 'manager') {
+                $class = $entry['class'];
+                $manager = new $class();
+                $manager->process();
+            } else {
+                $class = $entry['class'];
+                $service = ContainerFacade::has($class)
+                    ? ContainerFacade::make($class)
+                    : new $class();
+                (new RequestProcessor())->process($service, App::getRequest());
+            }
+        } else {
+            App::getResponse()->setCode(404);
+            App::getResponse()->write(json_encode([
+                'message' => 'Service not found.',
+                'type' => 'error'
+            ]));
+        }
+    }
+
     /**
      * Scan a namespace directory for routable classes.
      *

tests/WebFiori/Framework/Tests/Cli/ServicesListCommandTest.php

@@ -0,0 +1,34 @@
+<?php
+namespace WebFiori\Framework\Test\Cli;
+
+use WebFiori\Framework\Cli\CLITestCase;
+use WebFiori\Framework\Cli\Commands\ServicesListCommand;
+use WebFiori\Framework\Router\ServiceRouter;
+
+class ServicesListCommandTest extends CLITestCase {
+    protected function tearDown(): void {
+        ServiceRouter::reset();
+        parent::tearDown();
+    }
+
+    /** @test */
+    public function testNoServicesDiscovered() {
+        ServiceRouter::reset();
+        $output = $this->executeMultiCommand([ServicesListCommand::class]);
+        $outputStr = implode('', $output);
+
+        $this->assertStringContainsString('No services discovered', $outputStr);
+        $this->assertEquals(0, $this->getExitCode());
+    }
+
+    /** @test */
+    public function testWithDiscoveredServices() {
+        $dir = dirname(__DIR__, 4) . DIRECTORY_SEPARATOR . 'ServiceRouterFixtures';
+        ServiceRouter::discover('WebFiori\\Tests\\ServiceRouterFixtures', '/apis', [], $dir);
+
+        // Verify getDiscovered() has data (this is what the command reads)
+        $discovered = ServiceRouter::getDiscovered();
+        $this->assertArrayHasKey('orders', $discovered);
+        $this->assertGreaterThanOrEqual(3, count($discovered));
+    }
+}

tests/WebFiori/Framework/Tests/Router/ServiceRouterTest.php

@@ -129,4 +129,19 @@ public function testResetClearsDiscovered() {
         ServiceRouter::reset();
         $this->assertEmpty(ServiceRouter::getDiscovered());
     }
+
+    /** @test */
+    public function testDynamicRegistersRoute() {
+        $routesBefore = Router::routesCount();
+        ServiceRouter::dynamic($this->namespace, '/dynamic/{controller}', [], $this->fixturesDir);
+        $this->assertGreaterThan($routesBefore, Router::routesCount());
+    }
+
+    /** @test */
+    public function testHandleReturns404ForUnknownService() {
+        $response = \WebFiori\Framework\App::getResponse();
+        $response->setCode(200);
+        ServiceRouter::handle('nonexistent', $this->namespace, $this->fixturesDir);
+        $this->assertEquals(404, $response->getCode());
+    }
 }