Download the PHP package alexoliverwd/basic-router without Composer

Basic Router

This application is a minimalistic yet powerful PHP class designed to handle routing in web applications. It's a dependency-free solution that offers a straightforward approach to mapping HTTP requests to specific PHP functions or methods.

Installation

Preferred installation is via Composer:

Basic Usage

When a request comes in to the application, the Router instance will examine the request method (GET, POST, PUT, DELETE) and the requested URL. If a matching route is found, the associated callback function will be executed.

Attribute-Based Controller Routing

Attributes provide a modern, native way to declare route metadata directly in your code. This approach is now recommended for defining routes, while conventional methods will remain supported for compatibility.

Registering Multiple Controllers

In the below example, multiple controllers can be registered with the router in a single call using the registerRouteController() method. Each controller class defines its own set of routes through PHP attributes, the router will automatically scan and map them.

Conventional Method

In this example, if a GET request is made to the root URL (/), the function function () { echo 'get'; } will be called, and the string "get" will be output.

Registering an endpoint

The register method registers a new route in the routing system.

Parameters

1. Method: The HTTP method (e.g., GET, POST, PUT, DELETE).
2. Route: The URL pattern for the route.
3. Callback: The callable function or method to be executed when the route is matched.

Return Value:

• true: If the route is successfully registered.
• false: If the route already exists for the specified method.

Executing registered routes

The run() method is the core of the routing system. It's responsible for:

1. Parsing the Request: Extracts the requested URL path and HTTP method from the server environment.
2. Matching Routes: Compares the parsed request against registered routes to find a matching route.
3. Executing Callback: If a match is found, the associated callback function is executed.
4. Handling 404 Errors: If no match is found, the registered 404 error handler is invoked.

Unregistering an endpoint

This method unregisters a previously registered route from the routing system.

Parameters

1. Method: The HTTP method (e.g., GET, POST, PUT, DELETE) in lowercase.
2. Route: The URL pattern of the route to be unregistered.

Return Value:

• true: If the route is successfully unregistered.
• false: If the route doesn't exist or couldn't be unregistered.

Handling 404 errors

The register404 method registers a callback function to be executed when a 404 Not Found error occurs. This allows you to customize the error handling behavior for your application.

Parameters

1. Callback: A callable function or method that will be invoked when a 404 error is encountered. This callback can be used to generate custom error messages, redirect to a specific page, or perform other error handling actions.

Middleware

Middleware in this routing API provides a way to intercept and process requests before they reach your route handler. This allows you to implement reusable logic such as authentication, logging, CORS handling, rate limiting, or response modification without duplicating code inside your route controllers.

Middleware classes must implement the AOWD\Interfaces\Middleware interface, which requires a handle() method. When a route is matched, any attached middleware will be executed in the order they are defined.

Usage

1. Creating a Middleware

To create a middleware, implement the MiddlewareInterface and define the handle() method.

This simple example outputs Hello World before the route logic executes.

2. Attaching Middleware to a Route

Middleware can be attached to a route using the #[Middleware()] attribute.

In this example:

• A GET request to /hello-world-middleware will first run the helloWorld middleware.
• The middleware prints "Hello World ".
• Then the route handler executes and prints "GET".
• The final response is:

3. Registering Routes and Running the Router

After defining routes and middleware, register your route controller with the Router and start it:

Full Example

Here’s everything combined into a single working example: