README

A lightweight PHP 8.1+ web framework with file-based routing, PSR-7 support, and automatic dependency injection.

Requirements

PHP 8.1+

Features

📄 File-system based routing — drop a file in pages/, get a route automatically
🔀 Dynamic routes — pages/blog/{id}/index.php → /blog/{id}
🛠️ PSR-7 / PSR-15 standard — standard HTTP message and middleware interfaces
💉 Automatic dependency injection — method parameters resolved from a PSR-11 container
🎯 Attribute-based middleware — attach PSR-15 middleware directly to handler methods via PHP attributes
💪 Global middleware — pipe middleware at the server level
🔒 Built-in security headers — optional SecurityHeadersMiddleware

Installation

composer require mathsgod/light-server

Quick Start

1. Create an entry point

<?php
// public/index.php

require 'vendor/autoload.php';

(new Light\Server())->run();

2. Create a page handler

<?php
// pages/index.php

use Laminas\Diactoros\Response\TextResponse;

return new class {
    public function get(): TextResponse
    {
        return new TextResponse("Hello, World!");
    }

    public function post(): TextResponse
    {
        return new TextResponse("POST request received");
    }
};

Routing

Routes are generated automatically from the pages/ directory structure:

File	Route
`pages/index.php`	`/`
`pages/about.php`	`/about`
`pages/blog/index.php`	`/blog/`
`pages/blog/{id}/index.php`	`/blog/{id}`

If the pages/ directory does not exist, the server starts normally with no routes.

HTTP Methods

Define public methods matching the HTTP verb (case-insensitive):

return new class {
    public function get(): ResponseInterface { }
    public function post(): ResponseInterface { }
    public function put(): ResponseInterface { }
    public function delete(): ResponseInterface { }
    public function patch(): ResponseInterface { }
};

Dynamic Routes

Route parameters are available via $request->getAttribute():

<?php
// pages/blog/{id}/index.php

use Laminas\Diactoros\Response\JsonResponse;
use Psr\Http\Message\ServerRequestInterface;

return new class {
    public function get(ServerRequestInterface $request): JsonResponse
    {
        $id = $request->getAttribute('id');
        return new JsonResponse(['id' => $id]);
    }
};

Route Constraints

Since routing is powered by League\Route, you can constrain route parameters directly in the folder/file name using {param:type} syntax:

Constraint	Pattern	Example match
`{id:number}`	`[0-9]+`	`123`
`{name:word}`	`[a-zA-Z]+`	`raymond`
`{slug:slug}`	`[a-z0-9-]+`	`my-post`
`{token:alphanum_dash}`	`[a-zA-Z0-9-_]+`	`abc-123_x`
`{id:uuid}`	UUID format	`550e8400-e29b-41d4-a716-446655440000`
`{path:any}`	`.+`	`foo/bar/baz`

Example: Only match when id is numeric and name is alphabetic:

pages/
└── user/
    └── {id:number}/
        └── {name:word}/
            └── index.php   →   /user/{id:number}/{name:word}/

/user/1/raymond/   ✅  matches  (id=1, name=raymond)
/user/test/raymond/ ❌  no match (id is not numeric)

<?php
// pages/user/{id:number}/{name:word}/index.php

use Laminas\Diactoros\Response\TextResponse;
use Psr\Http\Message\ServerRequestInterface;

return new class {
    public function get(ServerRequestInterface $request): TextResponse
    {
        $id   = $request->getAttribute('id');
        $name = $request->getAttribute('name');
        return new TextResponse("User ID: $id, Name: $name");
    }
};

Dependency Injection

Method parameters are resolved automatically by type hint:

ServerRequestInterface — injects the current HTTP request
Any other type hint — resolved from the PSR-11 container (if provided)
Unresolvable parameters — receive null

<?php
// pages/users.php

use Laminas\Diactoros\Response\JsonResponse;
use Psr\Http\Message\ServerRequestInterface;

return new class {
    public function get(ServerRequestInterface $request, UserRepository $repo): JsonResponse
    {
        return new JsonResponse($repo->findAll());
    }
};

Pass a PSR-11 container when creating the server:

$container = /* your PSR-11 container */;
(new Light\Server($container))->run();

Middleware

Global Middleware

Use pipe() to apply middleware to all routes:

$server = new Light\Server();
$server->pipe(new Light\Server\SecurityHeadersMiddleware());
$server->run();

Attribute-based Middleware (per method)

Attach PSR-15 middleware to a specific handler method using PHP attributes:

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Server\MiddlewareInterface;
use Psr\Http\Server\RequestHandlerInterface;

#[\Attribute]
class AuthMiddleware implements MiddlewareInterface
{
    public function process(ServerRequestInterface $request, RequestHandlerInterface $handler): ResponseInterface
    {
        // auth logic ...
        return $handler->handle($request);
    }
}

return new class {
    #[AuthMiddleware]
    public function get(): ResponseInterface { /* ... */ }
};

Built-in Middleware

CorsMiddleware

Handles CORS preflight (OPTIONS) requests and adds CORS headers to all responses.

OPTIONS requests are intercepted before routing and return 204 No Content with CORS headers
All other requests pass through normally with CORS headers appended

$server = new Light\Server();
$server->pipe(new Light\Server\CorsMiddleware(
    allowedOrigins:   ['https://example.com'],
    allowedMethods:   ['GET', 'POST', 'PUT', 'DELETE'],
    allowedHeaders:   ['Content-Type', 'Authorization'],
    allowCredentials: true,
    maxAge:           3600,
));
$server->run();

All constructor parameters are optional:

Parameter	Default	Description
`allowedOrigins`	`['*']`	Allowed origins. Use `['*']` for wildcard
`allowedMethods`	`['GET','POST','PUT','PATCH','DELETE','OPTIONS']`	Allowed HTTP methods
`allowedHeaders`	`['Content-Type','Authorization']`	Allowed request headers
`allowCredentials`	`false`	Set `true` to send `Access-Control-Allow-Credentials: true`
`maxAge`	`86400`	Preflight cache duration in seconds

Note: When using allowCredentials: true, allowedOrigins must list specific origins — wildcard * does not work with credentials.

SecurityHeadersMiddleware

Adds common security response headers:

Header	Value
`X-Content-Type-Options`	`nosniff`
`X-Frame-Options`	`DENY`
`X-XSS-Protection`	`1; mode=block`
`Referrer-Policy`	`strict-origin-when-cross-origin`
`Content-Security-Policy`	`default-src 'self'`

$server = new Light\Server();
$server->pipe(new Light\Server\SecurityHeadersMiddleware());
$server->run();

Testing

composer install
./vendor/bin/phpunit

The test suite runs against PHP 8.1, 8.2, 8.3, 8.4, and 8.5 via the GitHub Actions matrix in .github/workflows/tests.yml.

License

MIT — see the LICENSE file for details.

mathsgod / light-server

Maintainers

Package info

Statistics

Security