Download the PHP package silviosln/arbor-router without Composer

Arbor Router 🌳

🇧🇷 Leia esta documentação em Português: README.pt-BR.md
🤖 Instructions for AI Agents: See ai/ context layer.

Arbor Router is a modern, strictly-typed, and framework-agnostic PHP 8.4+ library providing File-System Based Routing, heavily inspired by the mental model of Next.js App Router. It eliminates the need for manual, bloated routing configuration files by mapping your directory tree inside app/ directly into URL routes, nested layouts, API endpoints, and server actions.

🌟 Key Features

• File-System Routing: Folders and files automatically define URL endpoints (e.g. app/users/page.php handles /users).
• Dynamic Parameters: Folders with brackets like [id] or [...slug] (catch-all) naturally extract route parameters into $params.
• Route Groups (group): Organize layouts, auth, and middlewares without altering public URL segments.
• Hierarchical Layout Cascading: Nested layout.php and layoutroot.php render from the inside out, wrapping child views seamlessly via {{content}} or $children.
• Clear Context Separation:
  • page.php for visual HTML view rendering.
  • route.php for REST API endpoints with HTTP method dispatching (GET, POST, PUT, DELETE).
  • action.php for Server Actions handling mutations and form submissions.
• Cascading Russian Doll Middleware: Directory-scoped middleware.php files compose an onion pipeline from the root down to the target route.
• Zero Heavy Dependencies: Pure PHP 8.4+ utilizing constructor promotion, readonly classes, and property hooks. Requires only ext-json and ext-mbstring.
• Built-in Security: Session-based Anti-CSRF protection, HTTP Security Headers (nosniff, DENY), and API route client gating.
• Smart Content Negotiation: route.php endpoints automatically serialize return arrays into JSON, XML, or plain text based on the client's Accept header.

🚀 Installation

Install via Composer:

Requirements: PHP 8.4 or higher (ext-json and ext-mbstring).

📦 Directory Structure & Resource Conventions

🛠 Quick Start Guide

1. Bootstrapping the Router (public/index.php)

2. Static and Dynamic Pages (page.php)

3. Cascading Layouts (layoutroot.php and layout.php)

4. REST APIs and Content Negotiation (route.php)

Note: By default, route.php endpoints require the X-API-Request: true header to guard against direct browser address bar visits.

5. Server Actions & Form Mutations (action.php)

In your HTML form, embed the built-in CSRF token field:

6. Russian Doll Middleware (middleware.php)

🤖 AI-Native Context Layer

Arbor Router is designed to be AI-Friendly. If you are building with AI coding assistants (Claude, Cursor, Copilot, ChatGPT, Gemini), explore:

• AGENTS.md: Strict rules, entrypoints, and anti-patterns.
• ai/: Modular context directory containing:
  • overview.md: Goals and non-goals.
  • architecture.md: Visual request lifecycle and cascading algorithms.
  • api.md: Complete public class, method, and signature reference.
  • workflows.md: Step-by-step implementation recipes.
  • configuration.md: Cache and security configuration options.
  • errors.md: Exception taxonomy and HTTP status code mappings.
  • anti-patterns.md: Best practices vs forbidden calls.
  • troubleshooting.md: Diagnosis matrix for common errors.
  • examples.md: Copy-pasteable runnable snippets.
  • api-reference.json: Machine-readable schema.

⚖️ License

This library is licensed under the MIT License. See LICENSE for details.