Abstracting lookup method

.gitignore

@@ -1,3 +1,4 @@
 tests/trees
 
 /vendor/
+composer.lock

composer.json

@@ -15,5 +15,8 @@
             "email": "email@sharkk.net"
         }
     ],
-    "minimum-stability": "stable"
+    "minimum-stability": "stable",
+    "require-dev": {
+        "phpunit/phpunit": "^11.5"
+    }
 }

src/RouterInterface.php

@@ -4,6 +4,6 @@ namespace Sharkk\Router;
 
 interface RouterInterface
 {
-	public function add(string $method, string $route, callable $handler): RouterInterface;
+    public static function add(array &$routes, string $method, string $route, callable $handler): void;
-	public function lookup(string $method, string $uri): array;
+    public static function lookup(array &$routes, string $method, string $uri): array;
 }

src/SegmentRouter.php

@@ -2,188 +2,7 @@
 
 namespace Sharkk\Router;
 
-trait SegmentRouterTrait
-{
-	/**
-	 * Add a route to the route tree. The route must be a URI path, and contain dynamic segments
-	 * using a colon prefix. (:id, :slug, etc)
-	 *
-	 * Example:
-	 * `$r->add('GET', '/posts/:id', function($id) { echo "Viewing post $id"; });`
-	 */
-	public function add(string $method, string $route, callable $handler): RouterInterface
-	{
-		// Recursively build the node tree
-		$this->addNode(
-			$this->routes,
-			array_map( // Expand the route into segments and make dynamic segments into a common placeholder
-				fn($segment) => str_starts_with($segment, ':') ? ':x' : $segment,
-				explode('/', trim($route, '/'))
-			),
-			$method,
-			$handler
-		);
-
-		return $this;
-	}
-
-	private function addNode(array &$node, array $segments, string $method, callable $handler): void
-    {
-		// Base case: if no more segments, add the handler
-		if (empty($segments)) {
-			$node[$method] = $handler;
-			return;
-		}
-
-		// Get the current segment
-		$segment = array_shift($segments);
-
-		// Skip empty segments
-		if ($segment === '') {
-			$this->addNode($node, $segments, $method, $handler);
-			return;
-		}
-
-		// Ensure the segment exists in the node
-		if (!isset($node[$segment])) {
-			$node[$segment] = [];
-		}
-
-		// Recur for the next segment
-		$this->addNode($node[$segment], $segments, $method, $handler);
-    }
-
-	/**
-	 * Perform a lookup in the route tree for a given method and URI. Returns an array with a result code,
-	 * a handler if found, and any dynamic parameters. Codes are 200 for success, 404 for not found, and
-	 * 405 for method not allowed.
-	 *
-	 * @return array ['code', 'handler', 'params']
-	 */
-	public function lookup(string $method, string $uri): array
-	{
-		// node is a reference to our current location in the node tree
-		$node = $this->routes;
-
-		// if the URI is just a slash, we can return the handler for the root node
-		if ($uri === '/') {
-			return isset($node[$method])
-				? ['code' => 200, 'handler' => $node[$method], 'params' => null]
-				: ['code' => 405, 'handler' => null, 'params' => null];
-		}
-
-		// params will hold any dynamic segments we find
-		$params = array_reduce(
-			explode('/', trim($uri, '/')),
-			function ($carry, $segment) use (&$node) {
-				if (isset($node[$segment])) {
-					$node = $node[$segment];
-				} elseif (isset($node[':x'])) {
-					$carry[] = $segment;
-					$node = $node[':x'];
-				} else {
-					throw new \Exception('404');
-				}
-				return $carry;
-			},
-			[]
-		);
-
-		// if we found a handler for the method, return it and any params. if not, return a 405
-		return isset($node[$method])
-			? [
-				'code' => 200,
-				'handler' => $node[$method],
-				'params' => $params ?? []]
-			: [
-				'code' => 405,
-				'handler' => null,
-				'params' => []
-			];
-	}
-
-	/**
-	 * Clear all routes from the router.
-	 */
-	public function clear(): RouterInterface
-	{
-		$this->routes = [];
-		return $this;
-	}
-
-	/**
-	 * Dump the route tree as an array.
-	 */
-	public function dump(): array
-	{
-		return $this->routes;
-	}
-
-	/**
-	 * Register a GET route.
-	 */
-	public function get(string $route, callable $handler): RouterInterface
-	{
-		return $this->add('GET', $route, $handler);
-	}
-
-	/**
-	 * Register a POST route.
-	 */
-	public function post(string $route, callable $handler): RouterInterface
-	{
-		return $this->add('POST', $route, $handler);
-	}
-
-	/**
-	 * Register a PUT route.
-	 */
-	public function put(string $route, callable $handler): RouterInterface
-	{
-		return $this->add('PUT', $route, $handler);
-	}
-
-	/**
-	 * Register a PATCH route.
-	 */
-	public function patch(string $route, callable $handler): RouterInterface
-	{
-		return $this->add('PATCH', $route, $handler);
-	}
-
-	/**
-	 * Register a DELETE route.
-	 */
-	public function delete(string $route, callable $handler): RouterInterface
-	{
-		return $this->add('DELETE', $route, $handler);
-	}
-
-	/**
-	 * Register a HEAD route.
-	 */
-	public function head(string $route, callable $handler): RouterInterface
-	{
-		return $this->add('HEAD', $route, $handler);
-	}
-}
-
-interface SegmentRouterInterface extends RouterInterface
-{
-	//private function addNode(array &$node, array $segments, string $method, callable $handler): void;
-	public function clear(): RouterInterface;
-	public function dump(): array;
-	public function get(string $route, callable $handler): RouterInterface;
-	public function post(string $route, callable $handler): RouterInterface;
-	public function put(string $route, callable $handler): RouterInterface;
-	public function patch(string $route, callable $handler): RouterInterface;
-	public function delete(string $route, callable $handler): RouterInterface;
-	public function head(string $route, callable $handler): RouterInterface;
-}
-
 class SegmentRouter implements SegmentRouterInterface
 {
-	private array $routes = [];
-
     use SegmentRouterTrait;
 }

src/SegmentRouterInterface.php

@@ -0,0 +1,16 @@
+<?php declare(strict_types=1);
+
+namespace Sharkk\Router;
+
+interface SegmentRouterInterface extends RouterInterface
+{
+    //private function addNode(array &$node, array $segments, string $method, callable $handler): void;
+    public static function clear(array &$routes): void;
+    //public static function dump(array &$routes): array; // Deprecated, routes are now passed by reference
+    public static function get(array &$routes, string $route, callable $handler): void;
+    public static function post(array &$routes, string $route, callable $handler): void;
+    public static function put(array &$routes, string $route, callable $handler): void;
+    public static function patch(array &$routes, string $route, callable $handler): void;
+    public static function delete(array &$routes, string $route, callable $handler): void;
+    public static function head(array &$routes, string $route, callable $handler): void;
+}

src/SegmentRouterTrait.php

@@ -0,0 +1,215 @@
+<?php declare(strict_types=1);
+
+namespace Sharkk\Router;
+
+trait SegmentRouterTrait
+{
+    /**
+     * Add a route to the route tree. The route must be a URI path, and contain dynamic segments
+     * using a colon prefix. (:id, :slug, etc)
+     *
+     * Example:
+     * `$r->add('GET', '/posts/:id', function($id) { echo "Viewing post $id"; });`
+     */
+    public static function add(array &$routes, string $method, string $route, callable $handler): void
+    {
+        // Recursively build the node tree
+        self::addNode(
+            $routes,
+            array_map( // Expand the route into segments and make dynamic segments into a common placeholder
+                fn($segment) => str_starts_with($segment, ':') ? ':x' : $segment,
+                explode('/', trim($route, '/'))
+            ),
+            $method,
+            $handler
+        );
+    }
+
+    /**
+     * Adds a handler to the routing node based on the provided segments and method.
+     *
+     * This method recursively traverses the segments array, creating nested nodes as needed,
+     * and assigns the handler to the final node corresponding to the method.
+     *
+     * @param array $node The current routing node.
+     * @param array $segments The segments of the route to add.
+     * @param string $method The HTTP method (e.g., 'GET', 'POST') for which the handler is being added.
+     * @param callable $handler The handler to be executed for the given route and method.
+     *
+     * @return void
+     */
+    private static function addNode(array &$node, array $segments, string $method, callable $handler): void
+    {
+        // Base case: if no more segments, add the handler
+        if (empty($segments)) {
+            $node[$method] = $handler;
+            return;
+        }
+
+        // Get the current segment
+        $segment = array_shift($segments);
+
+        // Skip empty segments
+        if ($segment === '') {
+            self::addNode($node, $segments, $method, $handler);
+            return;
+        }
+
+        // Ensure the segment exists in the node
+        if (!isset($node[$segment])) {
+            $node[$segment] = [];
+        }
+
+        // Recur for the next segment
+        self::addNode($node[$segment], $segments, $method, $handler);
+    }
+
+    /**
+     * Perform a lookup in the route tree for a given method and URI. Returns an array with a result code,
+     * a handler if found, and any dynamic parameters. Codes are 200 for success, 404 for not found, and
+     * 405 for method not allowed.
+     *
+     * @return array ['code', 'handler', 'params']
+     */
+    public static function lookup(array &$routes, string $method, string $uri): array
+    {
+        // node is a reference to our current location in the node tree
+        $node = $routes;
+
+        // if the URI is the root, and the method is defined, return the handler
+        if (self::isRootUri($uri, $node, $method)) {
+            return ['code' => 200, 'handler' => $node[$method], 'params' => null];
+        }
+
+        // params will hold any dynamic segments we find
+        $params = [];
+        $segments = explode('/', trim($uri, '/'));
+        if (!self::traverseSegments($node, $segments, $params)) {
+            return ['code' => 404, 'handler' => null, 'params' => []];
+        }
+
+        return self::getHandler($node, $method, $params) ?? ['code' => 405, 'handler' => null, 'params' => []];
+    }
+
+    /**
+     * Traverses the given segments and updates the node and params accordingly.
+     *
+     * This method iterates over the segments and attempts to match each segment
+     * with the corresponding node. If a segment matches, it continues to the next
+     * segment. If a segment does not match but a wildcard ':x' is found, the segment
+     * is added to the params array and traversal continues. If no match is found,
+     * the traversal stops and returns false.
+     *
+     * @param array $node The current node to traverse.
+     * @param array $segments The segments to traverse through the node.
+     * @param array $params The parameters collected during traversal.
+     * @return bool Returns true if traversal is successful, otherwise false.
+     */
+    private static function traverseSegments(array &$node, array $segments, array &$params): bool
+    {
+        return ($node = array_reduce($segments, function ($carry, $segment) use (&$params) {
+            if (isset($carry[$segment])) {
+                return $carry[$segment];
+            }
+            if (isset($carry[':x'])) {
+                $params[] = $segment;
+                return $carry[':x'];
+            }
+            return false;
+        }, $node)) !== false;
+    }
+
+    /**
+     * Checks if the given URI is the root URI and if the specified method exists in the node array.
+     *
+     * @param string $uri The URI to check.
+     * @param array &$node The node array to check against.
+     * @param string $method The HTTP method to check for in the node array.
+     * @return bool Returns true if the URI is the root URI and the method exists in the node array, false otherwise.
+     */
+    public static function isRootUri(string $uri, array &$node, string $method): bool
+    {
+        return ($uri === '/' && isset($node[$method]) && array_key_exists($method, $node));
+    }
+
+    // if we found a handler for the method, return it and any params. if not, return a 405
+    
+    /**
+     * Retrieves the handler for a given node and method.
+     *
+     * @param array $node The node containing possible handlers.
+     * @param string $method The method to look up in the node.
+     * @param array $params The parameters to pass to the handler.
+     * @return array|null An array containing the handler information if found, or null if not found.
+     */
+    public static function getHandler($node, $method, $params): ?array
+    {
+         return array_key_exists($method, $node)
+            ? ['code' => 200, 'handler' => $node[$method], 'params' => $params]
+            : null;
+    }
+    
+    /**
+     * Clear all routes from the router.
+     */
+    public static function clear(array &$routes): void
+    {
+        $routes = [];
+    }
+
+    /**
+     * Dump the route tree as an array.
+     */
+    /*public static function dump(array &$routes): array
+    {
+        return $routes;
+    }*/
+
+    /**
+     * Register a GET route.
+     */
+    public static function get(array &$routes, string $route, callable $handler): void
+    {
+        self::add($routes, 'GET', $route, $handler);
+    }
+
+    /**
+     * Register a POST route.
+     */
+    public static function post(array &$routes, string $route, callable $handler): void
+    {
+        self::add($routes, 'POST', $route, $handler);
+    }
+
+    /**
+     * Register a PUT route.
+     */
+    public static function put(array &$routes, string $route, callable $handler): void
+    {
+        self::add($routes, 'PUT', $route, $handler);
+    }
+
+    /**
+     * Register a PATCH route.
+     */
+    public static function patch(array &$routes, string $route, callable $handler): void
+    {
+        self::add($routes, 'PATCH', $route, $handler);
+    }
+
+    /**
+     * Register a DELETE route.
+     */
+    public static function delete(array &$routes, string $route, callable $handler): void
+    {
+        self::add($routes, 'DELETE', $route, $handler);
+    }
+
+    /**
+     * Register a HEAD route.
+     */
+    public static function head(array &$routes, string $route, callable $handler): void
+    {
+        self::add($routes, 'HEAD', $route, $handler);
+    }
+}

tests/SegmentRouterTest.php

@@ -0,0 +1,84 @@
+<?php declare(strict_types=1);
+
+use PHPUnit\Framework\TestCase;
+use Sharkk\Router\SegmentRouter;
+
+final class SegmentRouterTest extends TestCase
+{
+    private SegmentRouter $router;
+
+    protected function setUp(): void
+    {
+        $this->router = new SegmentRouter();
+    }
+
+    public function testAddAndLookupRoute(): void
+    {
+        $routes = [];
+        SegmentRouter::add($routes, 'GET', '/blog/:id', function($id) {
+            return "Blog post $id";
+        });
+
+        $result = SegmentRouter::lookup($routes, 'GET', '/blog/123');
+        $this->assertEquals(200, $result['code']);
+        $this->assertIsCallable($result['handler']);
+        $this->assertEquals(['123'], $result['params']);
+        $this->assertEquals("Blog post 123", $result['handler'](...$result['params']));
+    }
+
+    public function testLookupNotFound(): void
+    {
+        $routes = [];
+        SegmentRouter::add($routes, 'GET', '/blog/:id', function($id) {
+            return "Blog post $id";
+        });
+
+        $result = SegmentRouter::lookup($routes, 'GET', '/nonexistent');
+        $this->assertEquals(404, $result['code']);
+        $this->assertNull($result['handler']);
+        $this->assertEmpty($result['params']);
+    }
+
+    public function testMethodNotAllowed(): void
+    {
+        $routes = [];
+        SegmentRouter::add($routes, 'GET', '/blog/:id', function($id) {
+            return "Blog post $id";
+        });
+
+        $result = SegmentRouter::lookup($routes, 'POST', '/blog/123');
+        $this->assertEquals(405, $result['code']);
+        $this->assertNull($result['handler']);
+        $this->assertEmpty($result['params']);
+    }
+
+    public function testClearRoutes(): void
+    {
+        $routes = [];
+        SegmentRouter::add($routes, 'GET', '/blog/:id', function($id) {
+            return "Blog post $id";
+        });
+
+        SegmentRouter::clear($routes);
+        $this->assertEmpty($routes);
+    }
+
+    public function testAddMultipleMethods(): void
+    {
+        $routes = [];
+        SegmentRouter::add($routes, 'GET', '/blog/:id', function($id) {
+            return "GET Blog post $id";
+        });
+        SegmentRouter::add($routes, 'POST', '/blog/:id', function($id) {
+            return "POST Blog post $id";
+        });
+
+        $resultGet = SegmentRouter::lookup($routes, 'GET', '/blog/123');
+        $this->assertEquals(200, $resultGet['code']);
+        $this->assertEquals("GET Blog post 123", $resultGet['handler'](...$resultGet['params']));
+
+        $resultPost = SegmentRouter::lookup($routes, 'POST', '/blog/123');
+        $this->assertEquals(200, $resultPost['code']);
+        $this->assertEquals("POST Blog post 123", $resultPost['handler'](...$resultPost['params']));
+    }
+}

tests/test.php

@@ -2,6 +2,8 @@
 
 require_once 'color.php';
 require_once __DIR__ . '/../src/RouterInterface.php';
+require_once __DIR__ . '/../src/SegmentRouterTrait.php';
+require_once __DIR__ . '/../src/SegmentRouterInterface.php';
 require_once __DIR__ . '/../src/SegmentRouter.php';
 
 const ROUTES = __DIR__ . '/routes/';
@@ -18,42 +20,42 @@ if (in_array('-f', $argv)) {
 // create the trees directory if it doesn't exist
 if (!is_dir(TREES)) mkdir(TREES);
 
-$r = new SegmentRouter();
+$routes = [];
 
 // Blog lookups
-$blog = readAndAddRoutes(ROUTES . 'blog.txt', $r);
+$blog = readAndAddRoutes(ROUTES . 'blog.txt', $routes);
-writeRoutesToFile($r->dump(), TREES . 'blog.txt');
+writeRoutesToFile($routes, TREES . 'blog.txt');
 echoTitle("Starting blog lookups");
-runIterations(10000, $r, $blog);
+runIterations(10000, $routes, $blog);
-runIterations(100000, $r, $blog);
+runIterations(100000, $routes, $blog);
-runIterations(1000000, $r, $blog);
+runIterations(1000000, $routes, $blog);
 unset($blog);
 
 // Github lookups
-$r->clear();
+SegmentRouter::clear($routes);
-$github = readAndAddRoutes(ROUTES . 'github.txt', $r);
+$github = readAndAddRoutes(ROUTES . 'github.txt', $routes);
-writeRoutesToFile($r->dump(), TREES . 'github.txt');
+writeRoutesToFile($routes, TREES . 'github.txt');
 echoTitle("Starting github lookups");
-runIterations(10000, $r, $github);
+runIterations(10000, $routes, $github);
-runIterations(100000, $r, $github);
+runIterations(100000, $routes, $github);
-runIterations(1000000, $r, $github);
+runIterations(1000000, $routes, $github);
 unset($github);
 
 // Big lookups
-$r->clear();
+SegmentRouter::clear($routes);
-$big = readAndAddRoutes(ROUTES . 'big.txt', $r);
+$big = readAndAddRoutes(ROUTES . 'big.txt', $routes);
-writeRoutesToFile($r->dump(), TREES . 'big.txt');
+writeRoutesToFile($routes, TREES . 'big.txt');
 echoTitle("Starting big lookups");
-runIterations(10000, $r, $big);
+runIterations(10000, $routes, $big);
-runIterations(100000, $r, $big);
+runIterations(100000, $routes, $big);
-runIterations(1000000, $r, $big);
+runIterations(1000000, $routes, $big);
 unset($big);
 
 // Parameter testing
-$r->clear();
+SegmentRouter::clear($routes);
 echoTitle("Testing parameters");
 
-$routes = [
+$testRoutes = [
     ['GET', '/blog/:id', function($id) {
         echo $id."\n";
     }],
@@ -68,10 +70,10 @@ $routes = [
     }],
 ];
 
-array_walk($routes, fn($route) => $r->add($route[0], $route[1], $route[2]));
+foreach ($testRoutes as $route) SegmentRouter::add($routes, ...$route);
 
 for ($i = 0; $i < 10; $i++) {
-	[$method, $uri] = $routes[array_rand($routes)];
+    [$method, $uri] = $testRoutes[array_rand($testRoutes)];
 
     // Generate some random parameters
     $uri = str_replace(':id', rand(1, 100), $uri);
@@ -79,22 +81,22 @@ for ($i = 0; $i < 10; $i++) {
     $uri = str_replace(':page', rand(1, 100), $uri);
     $uri = str_replace(':extra', 'extra-' . rand(1, 100), $uri);
 
-	$res = $r->lookup($method, $uri);
+    $res = SegmentRouter::lookup($routes, $method, $uri);
     if ($res['code'] !== 200) {
-		echo "Failed to handle request for $uri - $res\n";
+		echo "Failed to handle request for $uri - " . json_encode($res) . "\n";
         exit(1);
     }
     $res['handler'](...$res['params']);
 }
 
-$r->clear();
+SegmentRouter::clear($routes);
 echoTitle('Testing root node');
 
-$r->add('GET', '/', function() {
+SegmentRouter::add($routes, 'GET', '/', function() {
     echo "Root node is gtg!\n";
 });
 
-$res = $r->lookup('GET', '/');
+$res = SegmentRouter::lookup($routes, 'GET', '/');
 if ($res['code'] !== 200) {
     echo "Failed to handle request for /\n";
     exit(1);
@@ -113,17 +115,26 @@ function echoTitle(string $title) {
     echo "\n";
 }
 
-function readAndAddRoutes(string $file, &$r): array
+function readAndAddRoutes(string $file, &$routes): array
 {
-	return array_map(function($route) use ($r) {
+    return array_map(function($route) use (&$routes) {
         [$method, $path] = explode(' ', $route);
         $path = trim($path);
-		$r->add($method, $path, fn() => true);
+        SegmentRouter::add($routes, $method, $path, fn() => true);
         return [$method, $path];
     }, file($file));
 }
 
-function runIterations(int $iterations, $r, array $routes) {
+function addRoutes($routes): array
+{
+	return array_map(function($route) use (&$routes) {
+		[$method, $path, $handler] = $route;
+		SegmentRouter::add($routes, $method, $path, $handler);
+		return [$method, $path, $handler];
+	}, $routes);
+}
+
+function runIterations(int $iterations, &$routes, array $routesList) {
     echo "\n🚀 Running $iterations iterations...\n";
 
     $start = microtime(true); // start the timer
@@ -135,7 +146,7 @@ function runIterations(int $iterations, $r, array $routes) {
 
     for ($i = 0; $i < $iterations; $i++) {
         // pick a random route from the array
-		[$method, $path] = $routes[array_rand($routes)];
+        [$method, $path] = $routesList[array_rand($routesList)];
 
         // replace all :params/ with random values
         $uri = preg_replace_callback('/:(\w+)/', function($matches) {
@@ -144,7 +155,7 @@ function runIterations(int $iterations, $r, array $routes) {
 
         $start2 = microtime(true); // start the timer for the lookup
 
-		$res = $r->lookup($method, $uri); // run the lookup
+        $res = SegmentRouter::lookup($routes, $method, $uri); // run the lookup
 
         $reqs += microtime(true) - $start2; // add this lookup time
         if ($shortest == 0 || microtime(true) - $start2 < $shortest) {