Download the PHP package mathsgod/light-server without Composer

Light Server

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

Quick Start

1. Create an entry point

The server supports both pages/ next to the entry point and the common project layout with public/index.php and pages/ at the project root.

2. Create a page handler

Routing

Routes are generated automatically from the pages/ directory structure:

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

Routes use a canonical path without a trailing slash, but both /blog and /blog/ dispatch to the same page handler. A page file and a directory index cannot define the same canonical route: pages/blog.php and pages/blog/index.php cause a startup route-collision error.

HTTP Methods

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

HEAD requests use the head() method when defined; otherwise they reuse get() and return the response headers without a body. OPTIONS requests use the options() method when defined; otherwise routes return 204 No Content.

Dynamic Routes

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

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:

Dependency Injection

Method parameters are resolved automatically by type hint:

• ServerRequestInterface — injects the current HTTP request
• Class and interface type hints — resolved from the PSR-11 container (if provided)
• Scalar and union types — use their declared default value, or null when nullable; route and request values should be read from the request
• Required parameters that cannot be resolved — throw a RuntimeException with the parameter name

Pass a PSR-11 container when creating the server:

Middleware

Global Middleware

Use pipe() to apply middleware to all routes:

Attribute-based Middleware (per method)

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

Built-in Middleware

CorsMiddleware

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

• CORS preflight requests (with Origin and Access-Control-Request-Method) return 204 No Content with CORS headers
• All other requests pass through normally with CORS headers appended

All constructor parameters are optional:

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

SecurityHeadersMiddleware

Adds common security response headers:

Testing

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.