# thephpleague/route architecture

> Architecture diagram of the GitHub repository thephpleague/route, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thephpleague/route
- Repository: https://github.com/thephpleague/route

## Overview

##### Project type and purpose
- This is an open-source PHP routing library that implements PSR-7 (HTTP messages), PSR-11 (Container), PSR-15 (Request Handlers), and related standards.
- It provides a Router, RouteCollection, Dispatching engine, Middleware support, Response Strategies, and optional file-based caching.

##### File structure
- Top-level “src” directory contains the core code, grouped into sub-packages:
- Cache (FileCache, Router cache)
- Http (Request, Exception hierarchy, Response Decorators)
- Middleware (traits/interfaces for PSR-15 middleware)
- Strategy (pluggable response strategies: JSON, Application, etc.)
- Router, Route, RouteCollection, RouteGroup, Dispatcher
- Configuration & build: composer.json, phpunit.xml, phpstan.neon, phpcs.xml
- Tests mirror src structure under “tests”
- Documentation is in “docs” (Jekyll site).

##### Key components
a. HTTP Layer
- PSR-7 ServerRequest (src/Http/Request.php)
- PSR-7 Response + Decorators (src/Http/Response/Decorator)
b. Routing Core
- Router (src/Router.php) ← holds RouteCollection
- Route & RouteGroup (src/Route.php, src/RouteGroup.php)
- RouteCollectionInterface/RouteCollectionTrait
c. Dispatching
- Dispatcher (src/Dispatcher.php)
- Middleware pipeline (PSR-15 handlers, MiddlewareAwareTrait)
d. Strategy Layer
- AbstractStrategy, JsonStrategy, ApplicationStrategy
- OptionsHandler support
e. Caching (optional)
- FileCache + Router cache adapter
f. Container integration
- PSR-11 ContainerAwareInterface/Trait

##### Relationships & interactions
- Client issues HTTP request → PSR-7 ServerRequest
- Request enters Router → matches against RouteCollection
- Matched Route may carry Middleware stack → go through PSR-15 pipeline
- After middleware, Dispatcher invokes the route’s callable/controller
- Response Decorators may wrap/enrich the PSR-7 Response
- Caching layer can intercept Router resolution or cached responses

##### Architectural patterns & principles
- Strategy Pattern for pluggable response formats
- Middleware Pipeline (Chain of Responsibility, PSR-15)
- Dependency Injection via PSR-11 ContainerAware traits
- Single Responsibility (each component focuses on one aspect: routing, dispatch, strategy, caching)
- Interface-driven design to allow swapping implementations

##### Diagramming suggestions
- Blue for PSR interfaces (PSR-7, PSR-15, PSR-11)
- Green for core modules (Router, Dispatcher, Strategy)
- Orange for support modules (Cache, Middleware)

## Diagram (Mermaid)

```mermaid
graph TB
    %% PSR Interfaces
    subgraph "PSR Interfaces"
        PSR7Req["ServerRequest (PSR-7)"]:::psr
        PSR15MI["MiddlewareAwareInterface (PSR-15)"]:::psr
        PSR11CI["ContainerAwareInterface (PSR-11)"]:::psr
    end

    %% HTTP Layer
    subgraph "HTTP Layer"
        HTTPReq["PSR-7 ServerRequest"]:::core
        RespDec["DefaultHeaderDecorator"]:::support
    end

    %% Routing Core
    subgraph "Routing Core"
        Router["Router"]:::core
        Route["Route"]:::core
        RouteGroup["RouteGroup"]:::core
        RouteColInt["RouteCollectionInterface"]:::core
        RouteColTrait["RouteCollectionTrait"]:::core
    end

    %% Dispatching
    subgraph "Dispatching"
        Dispatcher["Dispatcher"]:::core
        MWTrait["MiddlewareAwareTrait"]:::support
    end

    %% Strategy Layer
    subgraph "Strategy Layer"
        AbsStrat["AbstractStrategy"]:::core
        JsonStrat["JsonStrategy"]:::core
        AppStrat["ApplicationStrategy"]:::core
        OptHandler["OptionsHandlerInterface"]:::support
    end

    %% Caching
    subgraph "Caching"
        FileCache["FileCache"]:::support
        RouterCache["Router Cache Adapter"]:::support
    end

    %% Container Integration
    subgraph "Container Integration"
        ContainerTrait["ContainerAwareTrait"]:::support
    end

    %% Flow
    Client["HTTP Client"] --> PSR7Req
    PSR7Req --> HTTPReq
    HTTPReq --> Router
    FileCache --> RouterCache
    RouterCache --> Router
    Router -->|"match route"| Route
    Router --> RouteGroup
    Router --> RouteColInt
    Router --> RouteColTrait
    Route -->|"invoke middleware pipeline"| Dispatcher
    Dispatcher --> MWTrait
    Dispatcher -->|"invoke handler"| AbsStrat
    AbsStrat --> JsonStrat
    AbsStrat --> AppStrat
    AbsStrat --> OptHandler
    JsonStrat --> RespDec
    AppStrat --> RespDec
    RespDec --> Client

    %% Container links
    ContainerTrait --> Router
    ContainerTrait --> Dispatcher
    ContainerTrait --> AbsStrat

    %% Click Events
    click PSR7Req "https://github.com/thephpleague/route/blob/6.x/src/Http/Request.php"
    click RespDec "https://github.com/thephpleague/route/blob/6.x/src/Http/Response/Decorator/DefaultHeaderDecorator.php"
    click Router "https://github.com/thephpleague/route/blob/6.x/src/Router.php"
    click Route "https://github.com/thephpleague/route/blob/6.x/src/Route.php"
    click RouteGroup "https://github.com/thephpleague/route/blob/6.x/src/RouteGroup.php"
    click RouteColInt "https://github.com/thephpleague/route/blob/6.x/src/RouteCollectionInterface.php"
    click RouteColTrait "https://github.com/thephpleague/route/blob/6.x/src/RouteCollectionTrait.php"
    click Dispatcher "https://github.com/thephpleague/route/blob/6.x/src/Dispatcher.php"
    click MWTrait "https://github.com/thephpleague/route/blob/6.x/src/Middleware/MiddlewareAwareTrait.php"
    click PSR15MI "https://github.com/thephpleague/route/blob/6.x/src/Middleware/MiddlewareAwareInterface.php"
    click AbsStrat "https://github.com/thephpleague/route/blob/6.x/src/Strategy/AbstractStrategy.php"
    click JsonStrat "https://github.com/thephpleague/route/blob/6.x/src/Strategy/JsonStrategy.php"
    click AppStrat "https://github.com/thephpleague/route/blob/6.x/src/Strategy/ApplicationStrategy.php"
    click OptHandler "https://github.com/thephpleague/route/blob/6.x/src/Strategy/OptionsHandlerInterface.php"
    click FileCache "https://github.com/thephpleague/route/blob/6.x/src/Cache/FileCache.php"
    click RouterCache "https://github.com/thephpleague/route/blob/6.x/src/Cache/Router.php"
    click PSR11CI "https://github.com/thephpleague/route/blob/6.x/src/ContainerAwareInterface.php"
    click ContainerTrait "https://github.com/thephpleague/route/blob/6.x/src/ContainerAwareTrait.php"

    %% Styles
    classDef psr fill:#cce5ff,stroke:#333,stroke-width:1px;
    classDef core fill:#d4edda,stroke:#333,stroke-width:1px;
    classDef support fill:#ffe5b4,stroke:#333,stroke-width:1px;
```
