Download the PHP package pig/router without Composer

Pig Router

A simple and lightweight PHP routing library that supports HTTP methods, route grouping, middleware, and parameter handling.

Note: This repository includes a multilingual README. Please check other language versions for more information.

• English
• 中文

Installation

Install via Composer:

Usage

Basic Example

Defining Routes

Create an api.php file to define your routes:

HTTP Methods

The router supports the following HTTP methods:

• get($pattern, $callback)
• post($pattern, $callback)
• put($pattern, $callback)
• delete($pattern, $callback)
• patch($pattern, $callback)
• head($pattern, $callback)
• options($pattern, $callback)
• get_post($pattern, $callback) - Accepts both GET and POST
• any($pattern, $callback) - Accepts all methods

Route Parameters

• Named parameters: /user/{id} - Captured as $id in the callback
• Regex parameters: /user/(\d+) - Captured as positional parameters

Middleware

Add middleware to routes or groups:

You can also add global before and after middleware:

Middleware can be:

• A callable function
• A class with a handle() method
• An array of middleware

Route Grouping

Group routes with common prefixes and middleware:

Callbacks

Callbacks can be:

• Anonymous functions
• Controller@method strings (e.g., 'App\Controllers\UserController@index')
• [Controller::class, 'method'] arrays
• Objects with a handle() method

Compatible Mode

For compatibility with certain frameworks or legacy code that uses a query parameter to carry the route, use compatible_mode() to tell the router to read the route from a specific GET key instead of parsing the request URI.

Basic usage:

Examples

• Simple web example (index.php receives ?r=/path):

• Using compatible mode for frameworks or servers that forward the path into a query param (Apache/nginx rewrite):

Now requests to /users/123 will be passed to index.php?r=/users/123 and the router will read the path from $_GET['r'].

• Manual/CLI dispatch (useful for testing):

Compatible mode only changes how the router determines the request URI; all other features (route definitions, middleware, groups) work the same.

Manual Dispatch

You can manually dispatch routes for testing or CLI usage:

API Reference

Router Class

Methods

• get(string $pattern, callable|array|string $callback): Register a GET route
• post(string $pattern, callable|array|string $callback): Register a POST route
• put(string $pattern, callable|array|string $callback): Register a PUT route
• delete(string $pattern, callable|array|string $callback): Register a DELETE route
• patch(string $pattern, callable|array|string $callback): Register a PATCH route
• head(string $pattern, callable|array|string $callback): Register a HEAD route
• options(string $pattern, callable|array|string $callback): Register an OPTIONS route
• get_post(string $pattern, callable|array|string $callback): Register GET and POST routes
• any(string $pattern, callable|array|string $callback): Register all HTTP method routes
• group(string $prefix, array|string $middleware, callable $callback): Group routes
• dispatch(string|null $method, string|null $uri): Dispatch the request
• loadRoutes(string $file): Load routes from a file
• compatible_mode(string $string): Enable compatible mode
• before(mixed $middleware): Add global before middleware
• after(mixed $middleware): Add global after middleware

Route Class

Methods

• middleware(array|string $middleware): Add middleware to the route

Exceptions

• NotFoundException: Thrown when no route matches
• InvalidCallbackException: Thrown when callback is invalid
• MethodNotFoundException: Thrown when a method does not exist in a controller

Testing

The router includes a comprehensive test suite using PHPUnit.

Running Tests

Install dependencies and run tests:

Or run PHPUnit directly:

Test Coverage

The test suite covers:

• Route registration for all HTTP methods
• Route dispatching with and without parameters
• Route grouping and middleware
• Exception handling
• Compatible mode functionality
• CLI dispatching
• Controller callbacks (array and string formats)
• Before/after middleware

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

sn01615