Download the PHP package neuron-php/routing without Composer

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.

Attribute-Based Routing

Modern PHP 8+ attribute-based routing allows you to define routes directly on controller methods using PHP attributes, providing a modern alternative to YAML configuration files.

Basic Usage

Simple Route

HTTP Method Attributes

Route Names and Filters

Route Groups

Apply common settings to all routes in a controller:

Multiple Routes on Same Method

Configuration

Enable Attribute Routing in MVC Application

Add controller paths to your config/routing.yaml:

For backward compatibility, controller paths can also be configured in config/neuron.yaml:

Note: If both files exist, routing.yaml takes precedence.

Benefits

• Co-location: Routes live with controller logic
• Type Safety: IDE autocomplete and validation
• Refactor-Friendly: Routes update when controllers change
• No Sync Issues: Can't have orphaned routes
• Modern Standard: Used by Symfony, Laravel, ASP.NET, Spring Boot
• Self-Documenting: Route definition IS the documentation

Performance

Route scanning uses PHP Reflection, which could be slow. For production:

1. Routes are scanned once during application initialization
2. The Router caches RouteMap objects in memory
3. No reflection happens during request handling
4. Future: Add route caching to file for zero-cost production routing

Migration from YAML

Before (YAML):

After (Attributes):

See tests/unit/RouteScannerTest.php for working examples of basic route definition, route groups with prefixes, filter composition, and multiple routes per method.

URL Rewrites

URL rewrites provide transparent URL rewriting before route matching. Unlike HTTP redirects (301/302), rewrites are internal and invisible to the client—the browser URL stays the same while the application routes to a different path.

Use Cases

• Override Package Routes: Applications can override default routes from packages (e.g., CMS homepage)
• Legacy URL Support: Support old URLs without creating duplicate routes
• Clean URLs: Map user-friendly URLs to internal route structures
• Environment-Specific Routing: Different rewrites for dev/staging/production

Configuration

Add rewrites to config/routing.yaml:

How It Works

Example: CMS Homepage Override

Problem: CMS defines GET / but you want a custom homepage.

Solution:

Now requests to / are transparently routed to your custom landing page without any HTTP redirect.

Rewrite Rules

• Exact Match Only: Rewrites use exact string matching, no wildcards or regex
• Applied Before Route Matching: Rewrites happen before the router looks for routes
• Original URL Preserved: Client never sees the rewritten URL
• Logging: Rewrites are logged at debug level for troubleshooting

vs. HTTP Redirects

Duplicate Route Detection

The router includes strict duplicate route detection to catch configuration errors early and prevent hard-to-debug routing issues.

What Gets Detected

1. Duplicate Method + Path

Error Message:

2. Duplicate Route Names

Error Message:

What's Allowed

Different HTTP Methods (RESTful)

This is standard RESTful routing and is fully supported.

Multiple Attributes on Same Method (Aliases)

Configuration

Strict mode is enabled by default. To disable (not recommended):

Benefits

• Catches Errors Early: Fails at application boot, not during user requests
• Clear Error Messages: Shows both conflicting routes with file locations
• Prevents Production Bugs: No silent overwrites or unexpected behavior
• Developer-Friendly: Suggests solutions in error messages

Why This Matters

Without duplicate detection:

• Same route defined twice? Second silently ignored, first wins
• Same name used twice? URL generation picks random route
• Debugging nightmare when routes mysteriously don't work

With duplicate detection:

• Application fails to start with clear error
• Developer fixes the conflict immediately
• Production deployments are safer

Rate Limiting

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

Basic Usage

Configuration Options

Storage Backends

Redis (Recommended for Production)

Best for distributed systems and high-traffic applications:

File Storage

Simple solution for single-server deployments:

Memory Storage (Testing Only)

For unit tests and development:

Whitelisting and Blacklisting

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

More Information

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