README

Deprecated: Development of this package has moved to meritum/http. This package will not receive further updates.

A PSR-15 HTTP kernel built on top of georgeff/kernel. Provides routing, a global middleware stack, per-route middleware, exception handling, and response emission.

Installation

composer require georgeff/http-kernel

Quick Start

use Georgeff\HttpKernel\HttpKernel;
use Georgeff\Kernel\Environment;

$kernel = new HttpKernel(Environment::Production);

$kernel->addMiddleware(SessionMiddleware::class);

$kernel->addRoute('GET', '/users/{id}', UserHandler::class);

$kernel->withExceptionHandler(function (Throwable $e, ServerRequestInterface $request) {
    $status = $e instanceof HttpExceptionInterface ? $e->getStatusCode() : 500;
    return new JsonResponse([
        'error' => $e->getMessage(),
    ], $status);
});

$kernel->boot();
$kernel->run();

Routing

Routes are registered before boot via addRoute(). The handler can be a RequestHandlerInterface instance or a string service ID resolved from the container.

// Single method
$kernel->addRoute('GET', '/users', ListUsersHandler::class);

// Multiple methods
$kernel->addRoute(['GET', 'POST'], '/users', UsersHandler::class);

Route parameters are available through the matched route object, which is stored as the __route__ request attribute:

$route = $request->getAttribute('__route__');
$id = $route->getArgument('id');

Per-Route Middleware

Routes support their own middleware stack, processed in FIFO order before the route handler:

$route = $kernel->addRoute('GET', '/admin', AdminHandler::class);
$route->addMiddleware(AuthMiddleware::class)
      ->addMiddleware(RoleMiddleware::class);

Middleware

Global middleware is added before boot and runs on every request in FIFO order:

$kernel->addMiddleware(CorsMiddleware::class);
$kernel->addMiddleware($loggingMiddleware);

Middleware can be a MiddlewareInterface instance or a string service ID resolved from the container.

Exception Handling

Register an exception handler to convert exceptions into HTTP responses. Without a handler, exceptions are rethrown. The handler receives the raw Throwable — check instanceof HttpExceptionInterface for HTTP-specific data.

$kernel->withExceptionHandler(function (Throwable $e, ServerRequestInterface $request) {
    $status = $e instanceof HttpExceptionInterface ? $e->getStatusCode() : 500;
    return new JsonResponse([
        'error' => $e->getMessage(),
    ], $status);
});

HTTP Exceptions

The package provides a set of HTTP exception classes:

All extend HttpException and implement HttpExceptionInterface.

MethodNotAllowedHttpException provides getAllowedMethods() and TooManyRequestsHttpException provides getRetryAfter().

Lifecycle Events

The kernel dispatches PSR-14 events at key points in the request lifecycle. Register a Psr\EventDispatcher\EventDispatcherInterface in the container to listen for them:

$kernel->addDefinition(EventDispatcherInterface::class, function () {
    return $myEventDispatcher;
});

All events extend Georgeff\Kernel\Event\KernelEvent and carry the kernel instance along with relevant request, response, or exception data as readonly public properties.

Debugging

Enable debug mode to profile the request lifecycle. Pass debug: true to the kernel constructor:

$kernel = new HttpKernel(Environment::Development, debug: true);

When debug mode is enabled, the kernel profiles the following phases:

The requestResolution, emission, and terminate phases are only recorded when using run(). When calling handle() directly, only handle, middleware, and exceptionHandling (if applicable) are recorded.

Retrieve profiling data via getDebugInfo():

$info = $kernel->getDebugInfo();

// Boot profile from the parent kernel
$info['bootProfile'];

// Request lifecycle profile
$info['requestProfile']['duration'];
$info['requestProfile']['phases']['middleware']['duration'];

Response Helpers

Convenience response classes under Georgeff\HttpKernel\Response:

• JsonResponse
• EmptyResponse
• RedirectResponse

License

MIT