README

Neuron-PHP Routing

Overview

The neuron router is a lightweight router/dispatcher is the vein of Ruby's Sinatra or Python's Flask. It allows for a very quick method for creating an app using restful routes or to add them to an existing application.

Easily map restful http requests to functions.
Extract one or many variables from routes using masks.
Create custom 404 responses.

Installation

Install php composer from https://getcomposer.org/

Install the neuron routing component:

composer require neuron-php/routing

.htaccess

This example .htaccess file shows how to get and pass the route to the example application.

RewriteEngine on

RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d

RewriteRule ^(.*)$ index.php?route=$1 [L,QSA]

Example App

Here is an example of a fully functional application that processes several routes including one with a variable.

<?php
require_once 'vendor/autoload.php';

Route::get( '/',
        function()
        {
            echo 'Home Page';
        }
    );

Route::get( '/about',
        function()
        {
            echo 'About Page';
        }
    );

Route::get( '/test/:name',
        function( $parameters )
        {
            echo "Name = $parameters[name]";
        }
    );

Route::get( '/404',
        function( $parameters )
        {
            echo "No route found for $parameters[route]";
        }
    );

$Get    = new \Neuron\Data\Filter\Get();
$Server = new \Neuron\Data\Filter\Server();

Route::dispatch(
    [
        'route' => $Get->filterScalar( 'route' ),
        'type'  => $Server->filterScalar( 'METHOD' )
    ]
);

If present, the extra element is merged into the parameters array before it is passed to the routes closure.

Rate Limiting

The routing component includes a powerful rate limiting system with multiple storage backends and flexible configuration options.

Basic Usage

use Neuron\Routing\Router;
use Neuron\Routing\Filters\RateLimitFilter;
use Neuron\Routing\RateLimit\RateLimitConfig;

$router = Router::instance();

// Create rate limit configuration
$config = new RateLimitConfig([
    'enabled' => true,
    'storage' => 'redis',  // Options: redis, file, memory (testing only)
    'requests' => 100,      // Max requests per window
    'window' => 3600        // Time window in seconds (1 hour)
]);

// Create and register the filter
$rateLimitFilter = new RateLimitFilter($config);
$router->registerFilter('rate_limit', $rateLimitFilter);

// Apply globally to all routes
$router->addFilter('rate_limit');

// Or apply to specific routes
$router->get('/api/data', $handler, 'rate_limit');

Configuration Options

Rate limiting can be configured via array or environment variables:

// Array configuration
$config = new RateLimitConfig([
    'enabled' => true,
    'storage' => 'redis',
    'requests' => 100,
    'window' => 3600,
    'redis_host' => '127.0.0.1',
    'redis_port' => 6379,
    'file_path' => 'cache/rate_limits'
]);

// From settings/environment variables (flat structure)
// RATE_LIMIT_ENABLED=true
// RATE_LIMIT_STORAGE=redis
// RATE_LIMIT_REQUESTS=100
// RATE_LIMIT_WINDOW=3600
$config = RateLimitConfig::fromSettings($settingsSource);

Storage Backends

Redis (Recommended for Production)

Best for distributed systems and high-traffic applications:

$config = new RateLimitConfig([
    'storage' => 'redis',
    'redis_host' => '127.0.0.1',
    'redis_port' => 6379,
    'redis_database' => 0,
    'redis_prefix' => 'rate_limit_',
    'redis_auth' => 'password',  // Optional
    'redis_persistent' => true    // Use persistent connections
]);

File Storage

Simple solution for single-server deployments:

$config = new RateLimitConfig([
    'storage' => 'file',
    'file_path' => 'cache/rate_limits'  // Directory for rate limit files
]);

Memory Storage (Testing Only)

For unit tests and development:

$config = new RateLimitConfig([
    'storage' => 'memory'  // Data lost when PHP process ends
]);

Advanced Features

Key Strategies

Control how rate limits are applied:

// Limit by IP address (default)
$filter = new RateLimitFilter($config, 'ip');

// Limit by authenticated user
$filter = new RateLimitFilter($config, 'user');

// Limit by IP + route combination
$filter = new RateLimitFilter($config, 'route');

// Custom key generation
class CustomRateLimitFilter extends RateLimitFilter {
    protected function getCustomKey(RouteMap $route): string {
        // Your custom logic here
        return $_SESSION['tenant_id'] ?? $this->getClientIp();
    }
}

Whitelisting and Blacklisting

$filter = new RateLimitFilter(
    $config,
    'ip',
    ['192.168.1.100', '10.0.0.1'],  // Whitelist - no limits
    ['45.67.89.10']                  // Blacklist - stricter limits (1/10th)
);

Custom Responses

Rate limit exceeded responses include appropriate headers:

X-RateLimit-Limit: Maximum requests allowed
X-RateLimit-Remaining: Requests remaining
X-RateLimit-Reset: Unix timestamp when limit resets
Retry-After: Seconds until retry allowed

The response format (JSON/HTML) is automatically determined from the Accept header.

Example: API Rate Limiting

// Different limits for different endpoints
$publicConfig = new RateLimitConfig([
    'enabled' => true,
    'storage' => 'redis',
    'requests' => 10,
    'window' => 60  // 10 requests per minute
]);

$apiConfig = new RateLimitConfig([
    'enabled' => true,
    'storage' => 'redis',
    'requests' => 1000,
    'window' => 3600  // 1000 requests per hour
]);

$router->registerFilter('public_limit', new RateLimitFilter($publicConfig));
$router->registerFilter('api_limit', new RateLimitFilter($apiConfig));

// Apply different limits
$router->get('/public/search', $searchHandler, 'public_limit');
$router->get('/api/users', $usersHandler, 'api_limit');

More Information

You can read more about the Neuron components at neuronphp.com

neuron-php / routing

Maintainers

Details