From 24f3fdd610c8c12a00fd13e651171e9bada2fa1e Mon Sep 17 00:00:00 2001
From: Ibrahim BinAlshikh <ibinalshikh@hotmail.com>
Date: Sun, 14 Jun 2026 12:21:56 +0300
Subject: [PATCH 1/4] feat: add ServiceRouter::discover() for auto-registering
 API routes

Scans a namespace for routable classes and registers API routes:
- #[RestController] attributed classes (uses attribute name or derived)
- WebService subclasses without attribute (uses getName())
- WebServicesManager subclasses (registered as manager routes)
- Non-service classes are skipped

Includes DI container integration for service instantiation.

Closes #382
Closes #384
---
 WebFiori/Framework/Router/ServiceRouter.php   | 193 ++++++++++++++++++
 tests/ServiceRouterFixtures/HelperUtil.php    |  11 +
 tests/ServiceRouterFixtures/LegacyService.php |  13 ++
 tests/ServiceRouterFixtures/OrderService.php  |  15 ++
 .../ServiceRouterFixtures/ProductService.php  |  15 ++
 tests/ServiceRouterFixtures/UsersManager.php  |  10 +
 .../Tests/Router/ServiceRouterTest.php        | 132 ++++++++++++
 tests/phpunit10.xml                           |   1 +
 8 files changed, 390 insertions(+)
 create mode 100644 WebFiori/Framework/Router/ServiceRouter.php
 create mode 100644 tests/ServiceRouterFixtures/HelperUtil.php
 create mode 100644 tests/ServiceRouterFixtures/LegacyService.php
 create mode 100644 tests/ServiceRouterFixtures/OrderService.php
 create mode 100644 tests/ServiceRouterFixtures/ProductService.php
 create mode 100644 tests/ServiceRouterFixtures/UsersManager.php
 create mode 100644 tests/WebFiori/Framework/Tests/Router/ServiceRouterTest.php

diff --git a/WebFiori/Framework/Router/ServiceRouter.php b/WebFiori/Framework/Router/ServiceRouter.php
new file mode 100644
index 000000000..78a978efd
--- /dev/null
+++ b/WebFiori/Framework/Router/ServiceRouter.php
@@ -0,0 +1,193 @@
+<?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\Router;
+
+use ReflectionClass;
+use WebFiori\Container\ContainerFacade;
+use WebFiori\Framework\App;
+use WebFiori\Http\Annotations\RestController;
+use WebFiori\Http\RequestProcessor;
+use WebFiori\Http\WebService;
+use WebFiori\Http\WebServicesManager;
+
+/**
+ * Discovers and registers API routes from a namespace.
+ *
+ * Supports three types of classes:
+ * - Classes with #[RestController] attribute (uses attribute name or derived name)
+ * - WebService subclasses without attribute (uses getName())
+ * - WebServicesManager subclasses (registered as manager routes)
+ *
+ * @author Ibrahim
+ */
+class ServiceRouter {
+    /**
+     * @var array Discovered service map for introspection.
+     */
+    private static array $discovered = [];
+
+    /**
+     * Discover and register routes for all services in a namespace.
+     *
+     * @param string $namespace Fully qualified namespace (e.g. 'App\\Apis').
+     * @param string $basePath URL prefix (e.g. '/apis').
+     * @param array $routeOptions Shared route options applied to all routes.
+     * @param string|null $directory Directory to scan. If null, derived from namespace relative to ROOT_PATH.
+     *
+     * @return int Number of routes registered.
+     */
+    public static function discover(string $namespace, string $basePath, array $routeOptions = [], ?string $directory = null): int {
+        $dir = $directory ?? self::namespaceToPath($namespace);
+        $map = self::scanNamespace($namespace, $dir);
+        $count = 0;
+        $basePath = rtrim($basePath, '/');
+
+        foreach ($map as $name => $entry) {
+            $class = $entry['class'];
+            $type = $entry['type'];
+            $path = $basePath . '/' . $name;
+
+            $options = array_merge($routeOptions, [
+                RouteOption::PATH => $path,
+            ]);
+
+            if ($type === 'manager') {
+                $options[RouteOption::TO] = $class;
+            } else {
+                $options[RouteOption::TO] = self::createServiceClosure($class);
+            }
+
+            Router::api($options);
+            self::$discovered[$name] = [
+                'class' => $class,
+                'type' => $type,
+                'path' => $path,
+            ];
+            $count++;
+        }
+
+        return $count;
+    }
+
+    /**
+     * Returns all discovered services.
+     *
+     * @return array Associative array keyed by name with class, type, and path.
+     */
+    public static function getDiscovered(): array {
+        return self::$discovered;
+    }
+
+    /**
+     * Reset discovered services.
+     */
+    public static function reset(): void {
+        self::$discovered = [];
+    }
+
+    /**
+     * Scan a namespace directory for routable classes.
+     *
+     * @param string $namespace The namespace to scan.
+     * @param string $dir The directory to scan.
+     *
+     * @return array Map of name => ['class' => FQCN, 'type' => 'service'|'manager']
+     */
+    private static function scanNamespace(string $namespace, string $dir): array {
+        $map = [];
+
+        if (!is_dir($dir)) {
+            return $map;
+        }
+
+        $files = glob($dir . DIRECTORY_SEPARATOR . '*.php');
+
+        if ($files === false) {
+            return $map;
+        }
+
+        foreach ($files as $file) {
+            $className = basename($file, '.php');
+            $fqcn = $namespace . '\\' . $className;
+
+            if (!class_exists($fqcn)) {
+                continue;
+            }
+
+            $ref = new ReflectionClass($fqcn);
+
+            if ($ref->isAbstract() || $ref->isInterface()) {
+                continue;
+            }
+
+            // Priority 1: #[RestController] attribute
+            $attrs = $ref->getAttributes(RestController::class);
+
+            if (!empty($attrs)) {
+                $attr = $attrs[0]->newInstance();
+                $name = !empty($attr->name) ? $attr->name : self::deriveNameFromClass($className);
+                $map[$name] = ['class' => $fqcn, 'type' => 'service'];
+
+                continue;
+            }
+
+            // Priority 2: WebServicesManager subclass
+            if ($ref->isSubclassOf(WebServicesManager::class)) {
+                $name = self::deriveNameFromClass($className);
+                $map[$name] = ['class' => $fqcn, 'type' => 'manager'];
+
+                continue;
+            }
+
+            // Priority 3: WebService subclass without attribute
+            if ($ref->isSubclassOf(WebService::class)) {
+                $instance = new $fqcn();
+                $name = $instance->getName();
+
+                if (!empty($name)) {
+                    $map[$name] = ['class' => $fqcn, 'type' => 'service'];
+                }
+            }
+        }
+
+        return $map;
+    }
+
+    /**
+     * Convert namespace to filesystem path.
+     */
+    private static function namespaceToPath(string $namespace): string {
+        return ROOT_PATH . DIRECTORY_SEPARATOR . str_replace('\\', DIRECTORY_SEPARATOR, $namespace);
+    }
+
+    /**
+     * Derive route name from class name.
+     * OrderService → orders, ProductManager → product
+     */
+    private static function deriveNameFromClass(string $className): string {
+        $name = preg_replace('/(Service|Manager|Controller)$/', '', $className);
+
+        return strtolower($name);
+    }
+
+    /**
+     * Create a closure that instantiates and processes a service.
+     */
+    private static function createServiceClosure(string $class): callable {
+        return function () use ($class) {
+            $service = ContainerFacade::has($class)
+                ? ContainerFacade::make($class)
+                : new $class();
+            (new RequestProcessor())->process($service, App::getRequest());
+        };
+    }
+}
diff --git a/tests/ServiceRouterFixtures/HelperUtil.php b/tests/ServiceRouterFixtures/HelperUtil.php
new file mode 100644
index 000000000..14bf646b5
--- /dev/null
+++ b/tests/ServiceRouterFixtures/HelperUtil.php
@@ -0,0 +1,11 @@
+<?php
+namespace WebFiori\Tests\ServiceRouterFixtures;
+
+/**
+ * A helper class that is NOT a WebService or Manager — should be skipped.
+ */
+class HelperUtil {
+    public function doSomething(): string {
+        return 'not a service';
+    }
+}
diff --git a/tests/ServiceRouterFixtures/LegacyService.php b/tests/ServiceRouterFixtures/LegacyService.php
new file mode 100644
index 000000000..1ca98d810
--- /dev/null
+++ b/tests/ServiceRouterFixtures/LegacyService.php
@@ -0,0 +1,13 @@
+<?php
+namespace WebFiori\Tests\ServiceRouterFixtures;
+
+use WebFiori\Http\WebService;
+
+class LegacyService extends WebService {
+    public function __construct() {
+        parent::__construct('legacy');
+    }
+
+    public function processRequest() {
+    }
+}
diff --git a/tests/ServiceRouterFixtures/OrderService.php b/tests/ServiceRouterFixtures/OrderService.php
new file mode 100644
index 000000000..a7eb3dc11
--- /dev/null
+++ b/tests/ServiceRouterFixtures/OrderService.php
@@ -0,0 +1,15 @@
+<?php
+namespace WebFiori\Tests\ServiceRouterFixtures;
+
+use WebFiori\Http\Annotations\RestController;
+use WebFiori\Http\WebService;
+
+#[RestController('orders')]
+class OrderService extends WebService {
+    public function __construct() {
+        parent::__construct('orders');
+    }
+
+    public function processRequest() {
+    }
+}
diff --git a/tests/ServiceRouterFixtures/ProductService.php b/tests/ServiceRouterFixtures/ProductService.php
new file mode 100644
index 000000000..6e74b7d0c
--- /dev/null
+++ b/tests/ServiceRouterFixtures/ProductService.php
@@ -0,0 +1,15 @@
+<?php
+namespace WebFiori\Tests\ServiceRouterFixtures;
+
+use WebFiori\Http\Annotations\RestController;
+use WebFiori\Http\WebService;
+
+#[RestController]
+class ProductService extends WebService {
+    public function __construct() {
+        parent::__construct('products');
+    }
+
+    public function processRequest() {
+    }
+}
diff --git a/tests/ServiceRouterFixtures/UsersManager.php b/tests/ServiceRouterFixtures/UsersManager.php
new file mode 100644
index 000000000..819259e6d
--- /dev/null
+++ b/tests/ServiceRouterFixtures/UsersManager.php
@@ -0,0 +1,10 @@
+<?php
+namespace WebFiori\Tests\ServiceRouterFixtures;
+
+use WebFiori\Http\WebServicesManager;
+
+class UsersManager extends WebServicesManager {
+    public function __construct() {
+        parent::__construct();
+    }
+}
diff --git a/tests/WebFiori/Framework/Tests/Router/ServiceRouterTest.php b/tests/WebFiori/Framework/Tests/Router/ServiceRouterTest.php
new file mode 100644
index 000000000..32549ce8c
--- /dev/null
+++ b/tests/WebFiori/Framework/Tests/Router/ServiceRouterTest.php
@@ -0,0 +1,132 @@
+<?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\Test\Router;
+
+use PHPUnit\Framework\TestCase;
+use WebFiori\Framework\Router\Router;
+use WebFiori\Framework\Router\ServiceRouter;
+
+class ServiceRouterTest extends TestCase {
+    private string $fixturesDir;
+    private string $namespace = 'WebFiori\\Tests\\ServiceRouterFixtures';
+
+    protected function setUp(): void {
+        parent::setUp();
+        ServiceRouter::reset();
+        $this->fixturesDir = dirname(__DIR__, 4) . DIRECTORY_SEPARATOR . 'ServiceRouterFixtures';
+    }
+
+    protected function tearDown(): void {
+        ServiceRouter::reset();
+        parent::tearDown();
+    }
+
+    /** @test */
+    public function testDiscoverFindsAttributedService() {
+        ServiceRouter::discover($this->namespace, '/apis', [], $this->fixturesDir);
+        $discovered = ServiceRouter::getDiscovered();
+
+        $this->assertArrayHasKey('orders', $discovered);
+        $this->assertEquals('WebFiori\\Tests\\ServiceRouterFixtures\\OrderService', $discovered['orders']['class']);
+        $this->assertEquals('service', $discovered['orders']['type']);
+        $this->assertEquals('/apis/orders', $discovered['orders']['path']);
+    }
+
+    /** @test */
+    public function testDiscoverDerivesNameFromClassWhenAttributeNameEmpty() {
+        ServiceRouter::discover($this->namespace, '/apis', [], $this->fixturesDir);
+        $discovered = ServiceRouter::getDiscovered();
+
+        $this->assertArrayHasKey('product', $discovered);
+        $this->assertEquals('service', $discovered['product']['type']);
+    }
+
+    /** @test */
+    public function testDiscoverFindsLegacyWebService() {
+        ServiceRouter::discover($this->namespace, '/apis', [], $this->fixturesDir);
+        $discovered = ServiceRouter::getDiscovered();
+
+        $this->assertArrayHasKey('legacy', $discovered);
+        $this->assertEquals('WebFiori\\Tests\\ServiceRouterFixtures\\LegacyService', $discovered['legacy']['class']);
+        $this->assertEquals('service', $discovered['legacy']['type']);
+    }
+
+    /** @test */
+    public function testDiscoverFindsWebServicesManager() {
+        ServiceRouter::discover($this->namespace, '/apis', [], $this->fixturesDir);
+        $discovered = ServiceRouter::getDiscovered();
+
+        $this->assertArrayHasKey('users', $discovered);
+        $this->assertEquals('WebFiori\\Tests\\ServiceRouterFixtures\\UsersManager', $discovered['users']['class']);
+        $this->assertEquals('manager', $discovered['users']['type']);
+        $this->assertEquals('/apis/users', $discovered['users']['path']);
+    }
+
+    /** @test */
+    public function testDiscoverSkipsNonServiceClasses() {
+        ServiceRouter::discover($this->namespace, '/apis', [], $this->fixturesDir);
+        $discovered = ServiceRouter::getDiscovered();
+
+        foreach ($discovered as $name => $entry) {
+            $this->assertNotEquals('WebFiori\\Tests\\ServiceRouterFixtures\\HelperUtil', $entry['class']);
+        }
+    }
+
+    /** @test */
+    public function testDiscoverReturnsCount() {
+        $count = ServiceRouter::discover($this->namespace, '/apis', [], $this->fixturesDir);
+
+        $this->assertEquals(4, $count); // orders, product, legacy, users
+    }
+
+    /** @test */
+    public function testDiscoverWithNonExistentNamespace() {
+        $count = ServiceRouter::discover(
+            'WebFiori\\Tests\\Fixtures\\NonExistent',
+            '/apis'
+        );
+
+        $this->assertEquals(0, $count);
+        $this->assertEmpty(ServiceRouter::getDiscovered());
+    }
+
+    /** @test */
+    public function testDiscoverWithoutDirectoryUsesNamespaceToPath() {
+        // App\Apis is a real directory relative to ROOT_PATH
+        // This exercises namespaceToPath() with a valid path
+        $count = ServiceRouter::discover('App\\Apis', '/app-apis');
+        // May find services or may not — depends on what's in App/Apis
+        // The point is it doesn't crash
+        $this->assertIsInt($count);
+    }
+
+    /** @test */
+    public function testDiscoverAppliesBasePath() {
+        ServiceRouter::discover($this->namespace, '/v2/apis', [], $this->fixturesDir);
+        $discovered = ServiceRouter::getDiscovered();
+
+        $this->assertEquals('/v2/apis/orders', $discovered['orders']['path']);
+    }
+
+    /** @test */
+    public function testGetDiscoveredInitiallyEmpty() {
+        $this->assertEmpty(ServiceRouter::getDiscovered());
+    }
+
+    /** @test */
+    public function testResetClearsDiscovered() {
+        ServiceRouter::discover($this->namespace, '/apis', [], $this->fixturesDir);
+        $this->assertNotEmpty(ServiceRouter::getDiscovered());
+
+        ServiceRouter::reset();
+        $this->assertEmpty(ServiceRouter::getDiscovered());
+    }
+}
diff --git a/tests/phpunit10.xml b/tests/phpunit10.xml
index d21277ca0..0afbe7972 100644
--- a/tests/phpunit10.xml
+++ b/tests/phpunit10.xml
@@ -86,6 +86,7 @@
 
       <file>../WebFiori/Framework/Router/RouteOption.php</file>
       <file>../WebFiori/Framework/Router/Router.php</file>
+      <file>../WebFiori/Framework/Router/ServiceRouter.php</file>
       <file>../WebFiori/Framework/Router/RouterUri.php</file>
 
       <file>../WebFiori/Framework/Scheduler/AbstractTask.php</file>

From e2446f602fcd8c99e28e97b3d0cea2ab23cab663 Mon Sep 17 00:00:00 2001
From: Ibrahim BinAlshikh <ibinalshikh@hotmail.com>
Date: Sun, 14 Jun 2026 12:34:06 +0300
Subject: [PATCH 2/4] 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
---
 WebFiori/Framework/App.php                    |  1 +
 .../Cli/Commands/ServicesListCommand.php      | 55 ++++++++++++++
 WebFiori/Framework/Router/RouteOption.php     |  4 +
 WebFiori/Framework/Router/ServiceRouter.php   | 74 +++++++++++++++++++
 .../Tests/Cli/ServicesListCommandTest.php     | 34 +++++++++
 .../Tests/Router/ServiceRouterTest.php        | 15 ++++
 6 files changed, 183 insertions(+)
 create mode 100644 WebFiori/Framework/Cli/Commands/ServicesListCommand.php
 create mode 100644 tests/WebFiori/Framework/Tests/Cli/ServicesListCommandTest.php

diff --git a/WebFiori/Framework/App.php b/WebFiori/Framework/App.php
index eee3e6b6c..6f97b6e05 100644
--- a/WebFiori/Framework/App.php
+++ b/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) {
diff --git a/WebFiori/Framework/Cli/Commands/ServicesListCommand.php b/WebFiori/Framework/Cli/Commands/ServicesListCommand.php
new file mode 100644
index 000000000..09b4d84b0
--- /dev/null
+++ b/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;
+    }
+}
diff --git a/WebFiori/Framework/Router/RouteOption.php b/WebFiori/Framework/Router/RouteOption.php
index 7934ede46..3c1be445d 100644
--- a/WebFiori/Framework/Router/RouteOption.php
+++ b/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';
 }
diff --git a/WebFiori/Framework/Router/ServiceRouter.php b/WebFiori/Framework/Router/ServiceRouter.php
index 78a978efd..ff7b45541 100644
--- a/WebFiori/Framework/Router/ServiceRouter.php
+++ b/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.
      *
diff --git a/tests/WebFiori/Framework/Tests/Cli/ServicesListCommandTest.php b/tests/WebFiori/Framework/Tests/Cli/ServicesListCommandTest.php
new file mode 100644
index 000000000..66f66b22f
--- /dev/null
+++ b/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));
+    }
+}
diff --git a/tests/WebFiori/Framework/Tests/Router/ServiceRouterTest.php b/tests/WebFiori/Framework/Tests/Router/ServiceRouterTest.php
index 32549ce8c..4a8239b90 100644
--- a/tests/WebFiori/Framework/Tests/Router/ServiceRouterTest.php
+++ b/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());
+    }
 }

From 86f3507cedf81a2a0265992aa8fb384780a87608 Mon Sep 17 00:00:00 2001
From: Ibrahim BinAlshikh <ibinalshikh@hotmail.com>
Date: Sun, 14 Jun 2026 13:09:33 +0300
Subject: [PATCH 3/4] feat: add recursive scanning and kebab-case route
 derivation

- discover() accepts recursive flag for subdirectory scanning
- Subdirectory names become kebab-cased URL path segments
- Class names converted to kebab-case via CaseConverter
- #[RestController] name with '/' is rejected (skipped)
- Explicit attribute name is always flat (ignores directory nesting)
- Non-recursive remains the default
---
 WebFiori/Framework/Router/ServiceRouter.php   | 54 +++++++++++++++----
 .../UserAuth/LoginService.php                 | 15 ++++++
 .../Tests/Router/ServiceRouterTest.php        | 31 +++++++++++
 3 files changed, 90 insertions(+), 10 deletions(-)
 create mode 100644 tests/ServiceRouterFixtures/UserAuth/LoginService.php

diff --git a/WebFiori/Framework/Router/ServiceRouter.php b/WebFiori/Framework/Router/ServiceRouter.php
index ff7b45541..04f9798e8 100644
--- a/WebFiori/Framework/Router/ServiceRouter.php
+++ b/WebFiori/Framework/Router/ServiceRouter.php
@@ -18,6 +18,7 @@
 use WebFiori\Http\RequestProcessor;
 use WebFiori\Http\WebService;
 use WebFiori\Http\WebServicesManager;
+use WebFiori\Json\CaseConverter;
 
 /**
  * Discovers and registers API routes from a namespace.
@@ -42,12 +43,13 @@ class ServiceRouter {
      * @param string $basePath URL prefix (e.g. '/apis').
      * @param array $routeOptions Shared route options applied to all routes.
      * @param string|null $directory Directory to scan. If null, derived from namespace relative to ROOT_PATH.
+     * @param bool $recursive If true, scan subdirectories. Subdirectory names become URL path segments.
      *
      * @return int Number of routes registered.
      */
-    public static function discover(string $namespace, string $basePath, array $routeOptions = [], ?string $directory = null): int {
+    public static function discover(string $namespace, string $basePath, array $routeOptions = [], ?string $directory = null, bool $recursive = false): int {
         $dir = $directory ?? self::namespaceToPath($namespace);
-        $map = self::scanNamespace($namespace, $dir);
+        $map = self::scanNamespace($namespace, $dir, '', $recursive);
         $count = 0;
         $basePath = rtrim($basePath, '/');
 
@@ -173,10 +175,12 @@ public static function handle(string $controllerName, string $namespace, ?string
      *
      * @param string $namespace The namespace to scan.
      * @param string $dir The directory to scan.
+     * @param string $pathPrefix Relative path prefix for recursive scanning (kebab-cased).
+     * @param bool $recursive Whether to scan subdirectories.
      *
      * @return array Map of name => ['class' => FQCN, 'type' => 'service'|'manager']
      */
-    private static function scanNamespace(string $namespace, string $dir): array {
+    private static function scanNamespace(string $namespace, string $dir, string $pathPrefix = '', bool $recursive = false): array {
         $map = [];
 
         if (!is_dir($dir)) {
@@ -208,7 +212,17 @@ private static function scanNamespace(string $namespace, string $dir): array {
 
             if (!empty($attrs)) {
                 $attr = $attrs[0]->newInstance();
-                $name = !empty($attr->name) ? $attr->name : self::deriveNameFromClass($className);
+
+                if (!empty($attr->name)) {
+                    if (str_contains($attr->name, '/')) {
+                        continue; // Invalid: name must not contain slashes
+                    }
+
+                    $name = $attr->name;
+                } else {
+                    $name = $pathPrefix . self::deriveNameFromClass($className);
+                }
+
                 $map[$name] = ['class' => $fqcn, 'type' => 'service'];
 
                 continue;
@@ -216,7 +230,7 @@ private static function scanNamespace(string $namespace, string $dir): array {
 
             // Priority 2: WebServicesManager subclass
             if ($ref->isSubclassOf(WebServicesManager::class)) {
-                $name = self::deriveNameFromClass($className);
+                $name = $pathPrefix . self::deriveNameFromClass($className);
                 $map[$name] = ['class' => $fqcn, 'type' => 'manager'];
 
                 continue;
@@ -225,14 +239,30 @@ private static function scanNamespace(string $namespace, string $dir): array {
             // Priority 3: WebService subclass without attribute
             if ($ref->isSubclassOf(WebService::class)) {
                 $instance = new $fqcn();
-                $name = $instance->getName();
+                $svcName = $instance->getName();
 
-                if (!empty($name)) {
+                if (!empty($svcName)) {
+                    $name = $pathPrefix . $svcName;
                     $map[$name] = ['class' => $fqcn, 'type' => 'service'];
                 }
             }
         }
 
+        // Recursive: scan subdirectories
+        if ($recursive) {
+            $subdirs = glob($dir . DIRECTORY_SEPARATOR . '*', GLOB_ONLYDIR);
+
+            if ($subdirs !== false) {
+                foreach ($subdirs as $subdir) {
+                    $subDirName = basename($subdir);
+                    $subNamespace = $namespace . '\\' . $subDirName;
+                    $subPrefix = $pathPrefix . CaseConverter::toKebabCase($subDirName, 'lower') . '/';
+                    $subMap = self::scanNamespace($subNamespace, $subdir, $subPrefix, true);
+                    $map = array_merge($map, $subMap);
+                }
+            }
+        }
+
         return $map;
     }
 
@@ -244,13 +274,17 @@ private static function namespaceToPath(string $namespace): string {
     }
 
     /**
-     * Derive route name from class name.
-     * OrderService → orders, ProductManager → product
+     * Derive route name from class name using kebab-case.
+     * OrderService → order, UserProfileService → user-profile
      */
     private static function deriveNameFromClass(string $className): string {
         $name = preg_replace('/(Service|Manager|Controller)$/', '', $className);
 
-        return strtolower($name);
+        if (empty($name)) {
+            $name = $className;
+        }
+
+        return CaseConverter::toKebabCase($name, 'lower');
     }
 
     /**
diff --git a/tests/ServiceRouterFixtures/UserAuth/LoginService.php b/tests/ServiceRouterFixtures/UserAuth/LoginService.php
new file mode 100644
index 000000000..161033cd4
--- /dev/null
+++ b/tests/ServiceRouterFixtures/UserAuth/LoginService.php
@@ -0,0 +1,15 @@
+<?php
+namespace WebFiori\Tests\ServiceRouterFixtures\UserAuth;
+
+use WebFiori\Http\Annotations\RestController;
+use WebFiori\Http\WebService;
+
+#[RestController]
+class LoginService extends WebService {
+    public function __construct() {
+        parent::__construct('login');
+    }
+
+    public function processRequest() {
+    }
+}
diff --git a/tests/WebFiori/Framework/Tests/Router/ServiceRouterTest.php b/tests/WebFiori/Framework/Tests/Router/ServiceRouterTest.php
index 4a8239b90..173ab293d 100644
--- a/tests/WebFiori/Framework/Tests/Router/ServiceRouterTest.php
+++ b/tests/WebFiori/Framework/Tests/Router/ServiceRouterTest.php
@@ -130,6 +130,37 @@ public function testResetClearsDiscovered() {
         $this->assertEmpty(ServiceRouter::getDiscovered());
     }
 
+    /** @test */
+    public function testDiscoverRecursiveFindsNestedServices() {
+        ServiceRouter::discover($this->namespace, '/apis', [], $this->fixturesDir, true);
+        $discovered = ServiceRouter::getDiscovered();
+
+        // LoginService in UserAuth/ subdirectory
+        $this->assertArrayHasKey('user-auth/login', $discovered);
+        $this->assertEquals('/apis/user-auth/login', $discovered['user-auth/login']['path']);
+    }
+
+    /** @test */
+    public function testDiscoverNonRecursiveSkipsSubdirectories() {
+        ServiceRouter::discover($this->namespace, '/apis', [], $this->fixturesDir, false);
+        $discovered = ServiceRouter::getDiscovered();
+
+        $this->assertArrayNotHasKey('user-auth/login', $discovered);
+    }
+
+    /** @test */
+    public function testDiscoverSkipsAttributeNameWithSlash() {
+        // OrderService has #[RestController('orders')] — valid
+        // If we had one with slash it would be skipped
+        ServiceRouter::discover($this->namespace, '/apis', [], $this->fixturesDir);
+        $discovered = ServiceRouter::getDiscovered();
+
+        // All discovered names should not contain slashes (non-recursive)
+        foreach ($discovered as $name => $entry) {
+            $this->assertStringNotContainsString('/', $name);
+        }
+    }
+
     /** @test */
     public function testDynamicRegistersRoute() {
         $routesBefore = Router::routesCount();

From 8f978c565c0364c9ea3a7af99af1c305c2495fd5 Mon Sep 17 00:00:00 2001
From: Ibrahim BinAlshikh <ibinalshikh@hotmail.com>
Date: Sun, 14 Jun 2026 13:38:48 +0300
Subject: [PATCH 4/4] feat: add route caching for production performance

- RouteCache class: build/load/clear cached service discovery results
- Uses app's existing cache backend (file, Redis, etc.)
- routes:cache CLI command to build cache
- routes:clear CLI command to clear cache
- Enabled via ROUTE_CACHE_ENABLED env variable
- 100% test coverage (12 tests, 35/35 lines)

Closes #386
---
 WebFiori/Framework/App.php                    |   2 +
 .../Cli/Commands/RoutesCacheCommand.php       |  48 +++++
 .../Cli/Commands/RoutesClearCommand.php       |  42 ++++
 WebFiori/Framework/Router/RouteCache.php      | 150 +++++++++++++++
 WebFiori/Framework/Router/ServiceRouter.php   |   9 +
 .../Framework/Tests/Router/RouteCacheTest.php | 180 ++++++++++++++++++
 tests/phpunit10.xml                           |   1 +
 7 files changed, 432 insertions(+)
 create mode 100644 WebFiori/Framework/Cli/Commands/RoutesCacheCommand.php
 create mode 100644 WebFiori/Framework/Cli/Commands/RoutesClearCommand.php
 create mode 100644 WebFiori/Framework/Router/RouteCache.php
 create mode 100644 tests/WebFiori/Framework/Tests/Router/RouteCacheTest.php

diff --git a/WebFiori/Framework/App.php b/WebFiori/Framework/App.php
index 6f97b6e05..836f6c2e4 100644
--- a/WebFiori/Framework/App.php
+++ b/WebFiori/Framework/App.php
@@ -376,6 +376,8 @@ public static function getRunner() : Runner {
                     '\\WebFiori\\Framework\\Cli\\Commands\\SkipMigrationsCommand',
                     '\\WebFiori\\Framework\\Cli\\Commands\\StepMigrationsCommand',
                     '\\WebFiori\\Framework\\Cli\\Commands\\ServicesListCommand',
+                    '\\WebFiori\\Framework\\Cli\\Commands\\RoutesCacheCommand',
+                    '\\WebFiori\\Framework\\Cli\\Commands\\RoutesClearCommand',
                 ];
 
                 foreach ($commands as $c) {
diff --git a/WebFiori/Framework/Cli/Commands/RoutesCacheCommand.php b/WebFiori/Framework/Cli/Commands/RoutesCacheCommand.php
new file mode 100644
index 000000000..af6a05069
--- /dev/null
+++ b/WebFiori/Framework/Cli/Commands/RoutesCacheCommand.php
@@ -0,0 +1,48 @@
+<?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\Cache\Cache;
+use WebFiori\Cache\FileStorage;
+use WebFiori\Cli\Command;
+use WebFiori\Framework\Router\RouteCache;
+use WebFiori\Framework\Router\Router;
+
+/**
+ * CLI command to build the route cache.
+ *
+ * @author Ibrahim
+ */
+class RoutesCacheCommand extends Command {
+    public function __construct() {
+        parent::__construct('routes:cache', [], 'Build the route cache for production.');
+    }
+
+    public function exec(): int {
+        $cache = $this->createRouteCache();
+        $cache->setEnabled(true);
+        $count = $cache->build();
+        $this->success("Route cache built: $count route(s) cached.");
+
+        return 0;
+    }
+
+    private function createRouteCache(): RouteCache {
+        $storagePath = APP_PATH . 'Storage';
+
+        if (!is_dir($storagePath)) {
+            mkdir($storagePath, 0755, true);
+        }
+
+        return new RouteCache(new Cache(new FileStorage($storagePath)), true);
+    }
+}
diff --git a/WebFiori/Framework/Cli/Commands/RoutesClearCommand.php b/WebFiori/Framework/Cli/Commands/RoutesClearCommand.php
new file mode 100644
index 000000000..9a226f3ee
--- /dev/null
+++ b/WebFiori/Framework/Cli/Commands/RoutesClearCommand.php
@@ -0,0 +1,42 @@
+<?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\Cache\Cache;
+use WebFiori\Cache\FileStorage;
+use WebFiori\Cli\Command;
+use WebFiori\Framework\Router\RouteCache;
+
+/**
+ * CLI command to clear the route cache.
+ *
+ * @author Ibrahim
+ */
+class RoutesClearCommand extends Command {
+    public function __construct() {
+        parent::__construct('routes:clear', [], 'Clear the route cache.');
+    }
+
+    public function exec(): int {
+        $cache = $this->createRouteCache();
+        $cache->clear();
+        $this->success('Route cache cleared.');
+
+        return 0;
+    }
+
+    private function createRouteCache(): RouteCache {
+        $storagePath = APP_PATH . 'Storage';
+
+        return new RouteCache(new Cache(new FileStorage($storagePath)), true);
+    }
+}
diff --git a/WebFiori/Framework/Router/RouteCache.php b/WebFiori/Framework/Router/RouteCache.php
new file mode 100644
index 000000000..d369f9910
--- /dev/null
+++ b/WebFiori/Framework/Router/RouteCache.php
@@ -0,0 +1,150 @@
+<?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\Router;
+
+use WebFiori\Cache\Cache;
+
+/**
+ * Caches route definitions to avoid discovery/registration overhead in production.
+ *
+ * @author Ibrahim
+ */
+class RouteCache {
+    /**
+     * @var Cache The cache instance.
+     */
+    private Cache $cache;
+    /**
+     * @var string Cache key for route data.
+     */
+    private string $cacheKey;
+    /**
+     * @var bool Whether caching is enabled.
+     */
+    private bool $enabled;
+
+    /**
+     * Creates new instance.
+     *
+     * @param Cache $cache The cache instance to use.
+     * @param bool $enabled Whether route caching is enabled.
+     * @param string $cacheKey The cache key for route data.
+     */
+    public function __construct(Cache $cache, bool $enabled = false, string $cacheKey = 'wf_routes_cache') {
+        $this->cache = $cache;
+        $this->enabled = $enabled;
+        $this->cacheKey = $cacheKey;
+    }
+
+    /**
+     * Returns whether route caching is enabled.
+     *
+     * @return bool
+     */
+    public function isEnabled(): bool {
+        return $this->enabled;
+    }
+
+    /**
+     * Sets whether route caching is enabled.
+     *
+     * @param bool $enabled
+     */
+    public function setEnabled(bool $enabled): void {
+        $this->enabled = $enabled;
+    }
+
+    /**
+     * Checks if a route cache exists.
+     *
+     * @return bool
+     */
+    public function isCached(): bool {
+        return $this->cache->get($this->cacheKey) !== null;
+    }
+
+    /**
+     * Load cached routes into the Router.
+     *
+     * @return bool True if cache was loaded, false if no cache exists.
+     */
+    public function load(): bool {
+        if (!$this->enabled) {
+            return false;
+        }
+
+        $data = $this->cache->get($this->cacheKey);
+
+        if ($data === null) {
+            return false;
+        }
+
+        $discovered = $data['discovered'] ?? [];
+
+        if (!empty($discovered)) {
+            ServiceRouter::setDiscovered($discovered);
+        }
+
+        // Re-register routes from the cached service map
+        $configs = $data['configs'] ?? [];
+
+        foreach ($configs as $config) {
+            ServiceRouter::discover(
+                $config['namespace'],
+                $config['basePath'],
+                $config['options'] ?? [],
+                $config['directory'] ?? null,
+                $config['recursive'] ?? false
+            );
+        }
+
+        return true;
+    }
+
+    /**
+     * Build route cache from current ServiceRouter state.
+     *
+     * @param array $discoverConfigs Array of discover() call configs to replay on load.
+     *
+     * @return int Number of discovered services cached.
+     */
+    public function build(array $discoverConfigs = []): int {
+        $discovered = ServiceRouter::getDiscovered();
+
+        $data = [
+            'discovered' => $discovered,
+            'configs' => $discoverConfigs,
+            'built_at' => date('c'),
+            'total' => count($discovered),
+        ];
+
+        $this->cache->set($this->cacheKey, $data, 31536000, true);
+
+        return count($discovered);
+    }
+
+    /**
+     * Clear the route cache.
+     */
+    public function clear(): void {
+        $this->cache->delete($this->cacheKey);
+    }
+
+    /**
+     * Returns the cache key.
+     *
+     * @return string
+     */
+    public function getCacheKey(): string {
+        return $this->cacheKey;
+    }
+}
diff --git a/WebFiori/Framework/Router/ServiceRouter.php b/WebFiori/Framework/Router/ServiceRouter.php
index 04f9798e8..0c5caac19 100644
--- a/WebFiori/Framework/Router/ServiceRouter.php
+++ b/WebFiori/Framework/Router/ServiceRouter.php
@@ -96,6 +96,15 @@ public static function reset(): void {
         self::$discovered = [];
     }
 
+    /**
+     * Set discovered services from cache.
+     *
+     * @param array $discovered The cached discovered map.
+     */
+    public static function setDiscovered(array $discovered): void {
+        self::$discovered = $discovered;
+    }
+
     /**
      * Register a dynamic namespace route that resolves services at request time.
      *
diff --git a/tests/WebFiori/Framework/Tests/Router/RouteCacheTest.php b/tests/WebFiori/Framework/Tests/Router/RouteCacheTest.php
new file mode 100644
index 000000000..1e1bb5485
--- /dev/null
+++ b/tests/WebFiori/Framework/Tests/Router/RouteCacheTest.php
@@ -0,0 +1,180 @@
+<?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\Test\Router;
+
+use PHPUnit\Framework\TestCase;
+use WebFiori\Cache\Cache;
+use WebFiori\Cache\FileStorage;
+use WebFiori\Framework\Router\RouteCache;
+use WebFiori\Framework\Router\RouteOption;
+use WebFiori\Framework\Router\Router;
+use WebFiori\Framework\Router\ServiceRouter;
+
+class RouteCacheTest extends TestCase {
+    private string $cacheDir;
+    private Cache $cache;
+
+    protected function setUp(): void {
+        parent::setUp();
+        $this->cacheDir = sys_get_temp_dir() . DIRECTORY_SEPARATOR . 'wf-route-cache-test';
+
+        if (!is_dir($this->cacheDir)) {
+            mkdir($this->cacheDir, 0755, true);
+        }
+
+        $this->cache = new Cache(new FileStorage($this->cacheDir));
+        ServiceRouter::reset();
+    }
+
+    protected function tearDown(): void {
+        // Clean up cache files
+        $files = glob($this->cacheDir . DIRECTORY_SEPARATOR . '*');
+
+        foreach ($files ?: [] as $file) {
+            if (is_file($file)) {
+                unlink($file);
+            }
+        }
+
+        @rmdir($this->cacheDir);
+        ServiceRouter::reset();
+        parent::tearDown();
+    }
+
+    /** @test */
+    public function testConstructorDefaults() {
+        $rc = new RouteCache($this->cache);
+        $this->assertFalse($rc->isEnabled());
+        $this->assertEquals('wf_routes_cache', $rc->getCacheKey());
+    }
+
+    /** @test */
+    public function testConstructorCustomValues() {
+        $rc = new RouteCache($this->cache, true, 'custom_key');
+        $this->assertTrue($rc->isEnabled());
+        $this->assertEquals('custom_key', $rc->getCacheKey());
+    }
+
+    /** @test */
+    public function testSetEnabled() {
+        $rc = new RouteCache($this->cache);
+        $rc->setEnabled(true);
+        $this->assertTrue($rc->isEnabled());
+        $rc->setEnabled(false);
+        $this->assertFalse($rc->isEnabled());
+    }
+
+    /** @test */
+    public function testLoadReturnsFalseWhenDisabled() {
+        $rc = new RouteCache($this->cache, false);
+        $this->assertFalse($rc->load());
+    }
+
+    /** @test */
+    public function testLoadReturnsFalseWhenNoCache() {
+        $rc = new RouteCache($this->cache, true);
+        $this->assertFalse($rc->load());
+    }
+
+    /** @test */
+    public function testIsCachedReturnsFalseInitially() {
+        $rc = new RouteCache($this->cache, true);
+        $this->assertFalse($rc->isCached());
+    }
+
+    /** @test */
+    public function testBuildCachesRoutes() {
+        $fixturesDir = dirname(__DIR__, 4) . DIRECTORY_SEPARATOR . 'ServiceRouterFixtures';
+        ServiceRouter::discover('WebFiori\\Tests\\ServiceRouterFixtures', '/cache-test', [], $fixturesDir);
+
+        $rc = new RouteCache($this->cache, true);
+        $count = $rc->build([
+            ['namespace' => 'WebFiori\\Tests\\ServiceRouterFixtures', 'basePath' => '/cache-test', 'options' => [], 'directory' => $fixturesDir, 'recursive' => false]
+        ]);
+
+        $this->assertGreaterThan(0, $count);
+        $this->assertTrue($rc->isCached());
+    }
+
+    /** @test */
+    public function testBuildAndLoadRestoresRoutes() {
+        $fixturesDir = dirname(__DIR__, 4) . DIRECTORY_SEPARATOR . 'ServiceRouterFixtures';
+        ServiceRouter::discover('WebFiori\\Tests\\ServiceRouterFixtures', '/restore-test', [], $fixturesDir);
+
+        $rc = new RouteCache($this->cache, true);
+        $rc->build([
+            ['namespace' => 'WebFiori\\Tests\\ServiceRouterFixtures', 'basePath' => '/restore-test', 'options' => [], 'directory' => $fixturesDir, 'recursive' => false]
+        ]);
+
+        ServiceRouter::reset();
+        $this->assertEmpty(ServiceRouter::getDiscovered());
+
+        $result = $rc->load();
+        $this->assertTrue($result);
+        $this->assertNotEmpty(ServiceRouter::getDiscovered());
+    }
+
+    /** @test */
+    public function testClearRemovesCache() {
+        $fixturesDir = dirname(__DIR__, 4) . DIRECTORY_SEPARATOR . 'ServiceRouterFixtures';
+        ServiceRouter::discover('WebFiori\\Tests\\ServiceRouterFixtures', '/clear-test', [], $fixturesDir);
+
+        $rc = new RouteCache($this->cache, true);
+        $rc->build([]);
+        $this->assertTrue($rc->isCached());
+
+        $rc->clear();
+        $this->assertFalse($rc->isCached());
+    }
+
+    /** @test */
+    public function testBuildWithNoDiscoveredServices() {
+        $rc = new RouteCache($this->cache, true);
+        $count = $rc->build([]);
+        $this->assertEquals(0, $count);
+        $this->assertTrue($rc->isCached());
+    }
+
+    /** @test */
+    public function testBuildIncludesDiscoveredServices() {
+        $fixturesDir = dirname(__DIR__, 4) . DIRECTORY_SEPARATOR . 'ServiceRouterFixtures';
+        ServiceRouter::discover('WebFiori\\Tests\\ServiceRouterFixtures', '/cached-apis', [], $fixturesDir);
+
+        $rc = new RouteCache($this->cache, true);
+        $rc->build([
+            ['namespace' => 'WebFiori\\Tests\\ServiceRouterFixtures', 'basePath' => '/cached-apis', 'options' => [], 'directory' => $fixturesDir, 'recursive' => false]
+        ]);
+
+        // Clear discovered and reload from cache
+        ServiceRouter::reset();
+        $this->assertEmpty(ServiceRouter::getDiscovered());
+
+        $rc->load();
+        $this->assertNotEmpty(ServiceRouter::getDiscovered());
+        $this->assertArrayHasKey('orders', ServiceRouter::getDiscovered());
+    }
+
+    /** @test */
+    public function testLoadWithEmptyRoutesArray() {
+        // Manually set cache with empty routes
+        $this->cache->set('wf_routes_cache', [
+            'routes' => [],
+            'discovered' => [],
+            'built_at' => date('c'),
+            'total' => 0,
+            'skipped' => 0,
+        ], 86400);
+
+        $rc = new RouteCache($this->cache, true);
+        $result = $rc->load();
+        $this->assertTrue($result);
+    }
+}
diff --git a/tests/phpunit10.xml b/tests/phpunit10.xml
index 0afbe7972..c3f5d976a 100644
--- a/tests/phpunit10.xml
+++ b/tests/phpunit10.xml
@@ -87,6 +87,7 @@
       <file>../WebFiori/Framework/Router/RouteOption.php</file>
       <file>../WebFiori/Framework/Router/Router.php</file>
       <file>../WebFiori/Framework/Router/ServiceRouter.php</file>
+      <file>../WebFiori/Framework/Router/RouteCache.php</file>
       <file>../WebFiori/Framework/Router/RouterUri.php</file>
 
       <file>../WebFiori/Framework/Scheduler/AbstractTask.php</file>