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:

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:

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:

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

SecurityHeadersMiddleware

Adds common security response headers:

$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.