Download the PHP package bermudaphp/router without Composer

Bermuda Router

🇷🇺 Русская версия

Flexible and performant routing library for PHP 8.4+ with route caching support.

Table of Contents

• Installation
• Quick Start
• Creating Routes
  • HTTP Verb Helper Methods
  • Using RouteBuilder
• Route Parameters
  • Basic Parameters
  • Predefined Patterns
  • Custom Patterns
  • Default Values
• Route Groups
  • Group Configuration
• URL Generation
• PSR-15 Middleware Integration
  • Basic Setup
  • Using RouteNotFoundHandler
  • Configuring 404 Handler
  • Integration in Middleware Pipeline
• Accessing Route Data in Controllers
• Route Locators
  • Locator Setup
  • Routes File
• PHP Attribute-based Route Location
  • Installation
  • Route Attribute
  • AttributeRouteLocator Setup
  • ClassFinder Integration
• Accessing Route Handler
• Route Caching
  • Creating Cache
  • Using Cache
  • Cache with Context for Closures
  • Caching Limitations
• Error Handling
  • Exception Types

Installation

Requirements: PHP 8.4+

Quick Start

Creating Routes

HTTP Verb Helper Methods

Using RouteBuilder

Route Parameters

Basic Parameters

Predefined Patterns

Custom Patterns

Inline Patterns

Inline patterns allow defining regex patterns directly in route definition. Syntax: [parameter_name:regular_expression]

Setting Patterns via Methods

Pattern Priority

Patterns are applied in the following priority order (highest to lowest):

1. Inline patterns in route: [id:\d+]
2. Method patterns: ->withToken('id', '\d+')
3. Group patterns: $group->setTokens(['id' => '\d+'])
4. Predefined patterns: from table above
5. Default pattern: [^\/]+ (any characters except slash)

Default Values

Route Groups

Groups allow organizing related routes with common settings:

Group Configuration

URL Generation

PSR-15 Middleware Integration

Basic Setup

Using RouteNotFoundHandler

RouteNotFoundHandler handles requests for non-existent routes and can work in two modes:

Integration in Middleware Pipeline

Accessing Route Data in Controllers

Route Locators

For loading routes from configuration files:

Locator Setup

Routes File

PHP Attribute-based Route Location

The library supports automatic route discovery through PHP attributes on controller methods. This allows defining routes declaratively, right next to handlers.

Installation

Attribute support requires an additional package:

Route Attribute

The #[Route] attribute allows defining routes directly on controller methods:

Route Attribute Parameters

AttributeRouteLocator Setup

AttributeRouteLocator works as a decorator for existing route locators:

ClassFinder Integration

For automatic controller discovery with attributes, ClassFinder is used (already included in dependencies):

📋 Detailed documentation: bermudaphp/finder | Russian Guide

Full Application Integration

Groups via Attributes

⚠️ Important: Route groups must be predefined in code (e.g., in base locator's routes file), otherwise RouterException will be thrown.

Route Priorities

Priorities determine the order of route checking when matching requests. Routes with higher priority are checked first.

Priority Rules:

• Default priority = 0
• Higher number = higher priority
• Routes are sorted by descending priority (100, 50, 10, 0, -10)
• Order not guaranteed for same priority

When to use priorities:

• Special routes should be checked before general ones
• Specific patterns — before wide catch-all routes
• API versioning with fallback to older versions

Priority example for API versioning:

Regular routes vs attribute routes:

• Attribute routes: priority determined by priority parameter
• Regular routes: priority determined by addition order (first added = highest priority)

Accessing Route Handler

RouteRecord provides convenient access to various route components:

Route Caching

For improved performance in production:

Creating Cache

Using Cache

Cache with Context for Closures

When routes use closures with external variables (via use), these variables must be available when loading cached routes. Context allows passing necessary objects and data to the cached file scope.

Caching Limitations

The caching system has the following limitations:

❌ What cannot be cached

✅ What can be cached

💡 Recommendations

1. Use string handlers in production for maximum cache compatibility
2. Pass contextual data if using use in closure handlers

Most preferred handler type - class name or class and method combination

Error Handling

Exception Types