Core

Http Service Provider

Server-side HTTP runtime services, PSR-15 middleware and request dispatch.

Responsibility

Registers HTTP-only runtime services for the web kernel: error page rendering, API authentication fallback, global middleware, middleware resolution, request dispatch, HTML minification, request inspection and HTTP log context.

Registered services

HttpServiceProvider registers ErrorPageRenderer, ApiAuthenticatorInterface with NullApiAuthenticator, MiddlewareResolver, MiddlewareStack, DispatchRequestHandler, HttpRequestInspector, HttpLogContext, HtmlMinifier and the built-in middleware classes used by the default stack.

Default stack

The default MiddlewareStack runs global PSR-15 middleware before route dispatch: RequestLoggingMiddleware, BenchmarkMiddleware, ErrorHandlingMiddleware, CorsMiddleware, PoweredByMiddleware, HtmlMinifyMiddleware, ApiAuthorizationMiddleware and OptionsMiddleware.

use Lemonade\Framework\Http\Middleware\MiddlewareStack;

$stack = $container->get(MiddlewareStack::class);
$middlewares = $stack->all();

Kernel flow

Kernel::run() bootstraps HTTP providers and delegates to Framework::run(). The framework creates a request from globals when none is supplied, resolves global middleware through the container, builds a MiddlewarePipeline and falls back to DispatchRequestHandler for route matching and controller execution.

use Psr\Http\Message\ServerRequestInterface;

final class FrontController
{
    public function __construct(
        private readonly Kernel $kernel,
    ) {}

    public function handle(ServerRequestInterface $request): ResponseInterface
    {
        return $this->kernel->run($request);
    }
}

Route middleware

DispatchRequestHandler matches the route, creates a controller request handler and resolves route-level middleware configured on the matched route. Route middleware is executed after the global stack and before the controller action.

$router
    ->postNamed('contact.submit', '/contact', ContactController::class . '@submit')
    ->middleware(CsrfMiddleware::class);

Middleware changes

Applications can configure the global stack through Framework::middleware(). MiddlewareStack supports add(), prepend(), insertBefore(), insertAfter(), remove() and all(); middleware classes must resolve to PSR-15 MiddlewareInterface instances.

use Lemonade\Framework\Http\Middleware\MiddlewareStack;
use Lemonade\Framework\Http\Middleware\PoweredByMiddleware;

$framework->middleware(static function (MiddlewareStack $stack): void {
    $stack->remove(PoweredByMiddleware::class);
    $stack->add(ExampleMiddleware::class);
});

Error handling

ErrorHandlingMiddleware catches route-not-found and not-found exceptions as 404 responses and other throwables as 500 responses. It renders HTML through ErrorPageRenderer and logs exceptions through LogManager with HttpLogContext; error.log.not_found controls 404 exception logging.

Request logging

RequestLoggingMiddleware logs completed responses when the request log channel is enabled. request.log.min_status can restrict logging to responses at or above a status code.

Benchmarking

BenchmarkMiddleware creates or updates the current benchmark run, records request context, marks pipeline milestones, logs benchmark data when benchmark.log.enabled is true and can inject benchmark data into the response through BenchmarkResponseInjector.

CORS and OPTIONS

CorsMiddleware uses cors.* config for allowed origins, methods, headers, exposed headers, credentials and max age. OptionsMiddleware returns a 204 response with an Allow header for implicit OPTIONS requests when a matching path has known allowed methods.

HTML and headers

PoweredByMiddleware adds the framework powered-by header. HtmlMinifyMiddleware minifies non-empty text/html responses when html_minify.enabled is true and updates Content-Length.

API authorization

ApiAuthorizationMiddleware checks registered API endpoints under api.prefix. Public endpoints pass through; protected endpoints use ApiAuthenticatorInterface and scope voting. The HTTP provider registers NullApiAuthenticator as the safe default, so applications must provide a real authenticator for protected APIs.

CLI note

HttpServiceProvider is registered by the HTTP Kernel, not by CliKernel. CLI commands do not execute the HTTP middleware pipeline; CLI runtime uses ConsoleServiceProvider and CommandRegistry instead.

Provider boundary

HttpServiceProvider owns HTTP middleware services and dispatch plumbing. Routing definitions belong to RoutingServiceProvider and app/Config/Routing.php; controllers and responses remain application code; authentication strategy for protected API endpoints is supplied by the application.