simple-php-router

simple-router is a lightweight PHP router inspired by Laravel. Key features include:

• HTTP Verbs: Support for GET, POST, PUT, PATCH, UPDATE, DELETE, and custom multiple verbs.
• Route Management: Named routes, route groups, namespaces, route prefixes, and sub-domain routing.
• Parameter Handling: Regular expression constraints and optional parameters.
• Security & Control: Middleware, CSRF protection, and IP-based restrictions.
• Utilities: Input manager for GET, POST, and FILE values, and custom boot managers for URL rewriting.

Route groups allow you to apply shared attributes like middleware, namespace, prefix, or domain to multiple routes at once using SimpleRouter::group().

• Middleware: Executes specified middleware for all routes in the group.
• Namespace: Prepends a PHP namespace to relative controller callbacks.
• Prefix: Adds a URL prefix to all routes in the group.
• Domain: Handles subdomain routing (e.g., {account}.myapp.com).

// Middleware and Prefix example
SimpleRouter::group(['middleware' => \Demo\Middleware\Auth::class, 'prefix' => '/admin'], function () {
    SimpleRouter::get('/users', function () {
        // Matches /admin/users and uses Auth middleware
    });
});

// Subdomain example
SimpleRouter::group(['domain' => '{account}.myapp.com'], function () {
    SimpleRouter::get('/user/{id}', function ($account, $id) {
        // ...
    });
});

A partialGroup is only rendered once its URL pattern has matched. This is useful for loading dynamic routes (like plugin routes) only when a specific URL structure is requested.

Warning: Because these routes are only registered after a match, the url() helper may not be able to find or generate URLs for routes inside a partial group until that group has been matched.

SimpleRouter::partialGroup('/plugin/{name}', function ($plugin) {
    // Routes added here are only available if /plugin/{name} matches
});

You can define a simple route using the SimpleRouter::get method. This example maps the root URL (/) to a closure that returns a string.

SimpleRouter::get('/', function() {
    return 'Hello world';
});

If you are using Nginx, ensure that URL rewriting is enabled. You can enable it by adding the following configuration to your Nginx configuration file:

location / {
    try_files $uri $uri/ /index.php?$query_string;
}

To load routes from a database or external file, implement the IRouterBootManager interface. The boot() method is called before routes are loaded, allowing you to intercept the request and rewrite the URL.

use Pecee\SimpleRouter\IRouterBootManager;
use Pecee\SimpleRouter\Router;

class CustomRouterRules implements IRouterBootManager 
{
    public function boot(Router $router, \Pecee\Http\Request $request): void
    {
        $rewriteRules = [
            '/my-cat-is-beatiful' => '/article/view/1',
            '/horses-are-great'   => '/article/view/2',
        ];

        foreach($rewriteRules as $url => $rule) {
            if($request->getUrl()->contains($url)) {
                $request->setRewriteUrl($rule);
            }
        }
    }
}

// Register in routes.php
SimpleRouter::addBootManager(new CustomRouterRules());

Middlewares are classes that execute before a route is rendered. They must implement the IMiddleware interface. Use them for authentication, logging, or setting request-specific parameters.

namespace Demo\Middlewares;

use Pecee\Http\Middleware\IMiddleware;
use Pecee\Http\Request;

class CustomMiddleware implements IMiddleware {
    public function handle(Request $request): void 
    {
        // Example: Authenticate user and attach to request
        $request->user = User::authenticate();

        if($request->user === null) {
            $request->setRewriteUrl(url('user.login'));
        }
    }
}

Extend the IpRestrictAccess middleware to whitelist or blacklist specific IP addresses. You can use * to represent an IP range.

use \Pecee\Http\Middleware\IpRestrictAccess;

class IpBlockerMiddleware extends IpRestrictAccess 
{
    protected $ipBlacklist = [
        '5.5.5.5',
        '8.8.*',
    ];

    protected $ipWhitelist = [
        '8.8.2.2',
    ];
}

To install the library, navigate to your project folder in the terminal and run the following command:

composer require pecee/simple-router

You can set a custom base path for all routes by registering an EventHandler for the EVENT_ADD_ROUTE event. This allows you to prepend a path to ILoadableRoute or IGroupRoute instances.

$basePath = '/basepath';

$eventHandler = new EventHandler();
$eventHandler->register(EventHandler::EVENT_ADD_ROUTE, function(EventArgument $event) use($basePath) {

    $route = $event->route;

    // Skip routes added by group as these will inherit the url
    if(!$event->isSubRoute) {
        return;
    }
    
    switch (true) {
        case $route instanceof ILoadableRoute:
            $route->prependUrl($basePath);
            break;
        case $route instanceof IGroupRoute:
            $route->prependPrefix($basePath);
            break;
    }
});

SimpleRouter::addEventHandler($eventHandler);