Http Server Router Laravel Package

Getting Started

1. Prerequisite: Ensure you’re using an Amp-based HTTP server (e.g., amphp/http-server, amphp/socket). This router only integrates with Amp—not ReactPHP, Swoole, or traditional FPM stacks.
2. Install: composer require amphp/http-server-router.
3. First route:

   use Amp\Http\Server\Router;
   use Amp\Http\Server\Request;
   use Amp\Http\Server\Response;
   
   $router = new Router();
   $router->addRoute('GET', '/hello', function (Request $request): Response {
       return new Response(200, [], 'Hello, world!');
   });
   // Then pass `$router` to your Amp server’s `serve()` method
   

4. Launch: Start your server (e.g., php server.php) and visit http://localhost:8080/hello.

Implementation Patterns

• Method-specific routes: Use get(), post(), put(), etc. shortcuts for fluency:

  $router->get('/users', $listUsersHandler);
  $router->post('/users', $createUserHandler);
  

• Route grouping & mounting: Build modular route trees:

  $api = new Router();
  $api->get('/users', $listUsersHandler);
  $router->mount('/api', $api); // Matches /api/users
  

• Parameterized routes: Capture path parameters:

  $router->get('/users/{id:\d+}', function (Request $request, string $id): Response {
      // $request->getAttribute('id') also works
      return new Response(200, [], "User {$id}");
  });
  

• Middleware-like composition: Use route callbacks with next() propagation:

  $router->addRoute('GET', '/auth/*', function (Request $request, callable $next): Response {
      $token = $request->getHeaderLine('Authorization');
      if (!$token) throw new Amp\Http\Server\Exception\UnauthorizedException();
      return $next($request);
  });
  

• Sub-routers for service boundaries: Mount independent routers per domain (e.g., /billing, /inventory) for maintainability.

Gotchas and Tips

• Route order matters: The router matches in order—place specific routes before wildcards (e.g., /users/{id} before /users/*).
• * vs {var} wildcards: * matches any path segment, including /; {param} only matches non-empty segments without /. Use {param:.*} for greedy matching.
• Attributes vs. parameters: Use $request->getAttribute('param') inside handlers—parse_str()-style params are not auto-populated.
• Async handlers only: All route callbacks must return Response|Promise, not raw values. Blockers like sleep() or DB calls must use Amp’s async variants (e.g., Amp\MySQL, Amp\Postgres).
• Debugging unmatched routes: Add a fallback last:

  $router->addRoute('*', '/{...}', fn() => new Response(404));
  

• Testing: Wrap Router in Amp\Http\Server\Router\RequestHandler to unit-test handlers in isolation.
• No built-in auth/session: Pair with amphp/http-server extensions (e.g., amphp/http-server-session)—this package focuses only on routing.