README

A lightweight, enterprise-grade PHP router with Domain-Driven Design (DDD) architecture, featuring powerful validation, middleware pipeline, and zero dependencies.

// It's this simple
$router = new Router();

$router->post('/users', function(Request $request) {
    $validated = $request->validated([
        'name' => 'required|min:3|max:50',
        'email' => 'required|email',
        'age' => 'required|integer|min:18'
    ]);
    
    return Response::json($validated, 201);
});

$router->run();

✨ Features

🎯 Clean Architecture - Domain-Driven Design (DDD) with clear separation of concerns
⚡ Zero Dependencies - Pure PHP 8.2+, no external packages required
🛡️ Type Safety - Full type hints with strict types enabled
🔒 Built-in Validation - 17+ validation rules with custom messages
🔄 Middleware Pipeline - Powerful middleware system with built-in CORS, Rate Limiting, and Logging
🎨 Flexible Routing - RESTful routes, route groups, named routes, and multiple HTTP methods
📝 Smart Parameters - Type-safe route parameters (int, uuid, slug, alpha, etc.)
🧪 100+ Tests - Comprehensive test suite with PHPUnit
📖 Rich Documentation - Complete examples and API reference

📦 Installation

composer require celiovmjr/simplerouter

Or download the latest release and include via autoloader:

require_once 'vendor/autoload.php';

🚀 Quick Start

Basic Route

use SimpleRouter\Application\Router;
use SimpleRouter\Application\Http\{Request, Response};

$router = new Router();

$router->get('/hello/{name}', function(Request $request) {
    $name = $request->input('name');
    return Response::json(['message' => "Hello, {$name}!"]);
});

$router->run();

With Validation

$router->post('/register', function(Request $request) {
    $validated = $request->validated([
        'name' => 'required|alpha|min:3|max:50',
        'email' => 'required|email|onError("Please provide a valid email")',
        'password' => 'required|min:8',
        'age' => 'required|integer|min:18|onError("You must be 18 or older")'
    ]);
    
    // Create user...
    
    return Response::json([
        'message' => 'User registered successfully',
        'user' => $validated
    ], 201);
});

With Middleware

use SimpleRouter\Application\Middleware\Builtin\{
    CorsMiddleware,
    RateLimitMiddleware,
    LoggingMiddleware
};

$router->group([
    'prefix' => '/api',
    'middleware' => [
        CorsMiddleware::production(['https://app.example.com']),
        RateLimitMiddleware::api(),
        LoggingMiddleware::production(__DIR__ . '/logs/api.log')
    ]
], function($router) {
    $router->get('/users', [UserController::class, 'index']);
    $router->post('/users', [UserController::class, 'store']);
});

📚 Documentation

Getting Started - Installation and first steps
Architecture - DDD structure and design principles
Routing Guide - Complete routing documentation
Validation Guide - Validation rules and usage
Middleware Guide - Built-in and custom middleware
Testing Guide - Running and writing tests
Examples - Code examples and demos

🛣️ Routing

// HTTP Methods
$router->get('/users', $handler);
$router->post('/users', $handler);
$router->put('/users/{id}', $handler);
$router->delete('/users/{id}', $handler);

// Typed Parameters
$router->get('/users/{id:int}', $handler);
$router->get('/posts/{uuid:uuid}', $handler);
$router->get('/blog/{slug:slug}', $handler);

// Route Groups
$router->group(['prefix' => '/api/v1'], function($router) {
    $router->get('/users', $handler);
});

// Named Routes
$router->get('/dashboard', $handler)->withName('dashboard');
$url = $router->route('dashboard');

→ Full Routing Documentation

✅ Validation

$validated = $request->validated([
    'email' => 'required|email',
    'age' => 'required|integer|min:18|max:120',
    'username' => 'required|alphanumeric|min:3|max:20',
    'role' => 'required|in:admin,user,guest'
]);

17+ Built-in Rules:

required, email, url, uuid
integer, numeric, boolean, alpha, alphanumeric
min, max, in, regex, date

→ Full Validation Documentation

🛡️ Middleware

Built-in Middleware

// CORS
CorsMiddleware::production(['https://app.example.com']);

// Rate Limiting
RateLimitMiddleware::api();        // 100 req/min
RateLimitMiddleware::auth();       // 5 req/min
RateLimitMiddleware::perUser(1000, 60);

// Logging
LoggingMiddleware::production('/var/log/api.log');
LoggingMiddleware::debug('/var/log/debug.log');

Custom Middleware

class AuthMiddleware implements Middleware
{
    public function handle(Request $request, Closure $next): Response
    {
        // Authentication logic
        return $next($request);
    }
}

→ Full Middleware Documentation

📥📤 Request & Response

Request

// Input
$request->input('name');
$request->all();
$request->only(['name', 'email']);
$request->validated($rules);

// Headers & Query
$request->header('Authorization');
$request->query('page', 1);

// Request Info
$request->method();
$request->ip();
$request->path();

Response

// JSON
Response::json(['data' => 'value'], 200);

// HTML
Response::html('<h1>Hello</h1>');

// Redirect
Response::redirect('/dashboard');

// Fluent Interface
Response::make('OK')
    ->withStatus(201)
    ->withHeader('X-Custom', 'Value');

→ Full Request/Response Documentation

🧪 Testing

# Run all tests
./run-tests.sh

# Run specific suite
./run-tests.sh router
./run-tests.sh validation

# Generate coverage
./run-tests.sh coverage

100+ Tests covering:

Router functionality
Validation rules
Request/Response handling
Middleware pipeline

→ Full Testing Documentation

🏗️ Architecture

SimpleRouter follows Domain-Driven Design (DDD):

src/
├── Domain/              # Business logic
│   ├── Contracts/       # Interfaces (Middleware, ValidationRule, Validator)
│   ├── Entities/        # Domain entities (Route, RouteCollection)
│   └── ValueObjects/    # Value objects (HttpMethod, Uri)
└── Application/         # Application logic
    ├── Router.php       # Main router
    ├── Http/            # Request/Response
    ├── Validation/      # Validation system
    │   ├── RequestValidator.php
    │   ├── RuleParser.php
    │   ├── ValidationResult.php
    │   └── Rules/       # Individual rule files (17 rules)
    ├── Middleware/      # Middleware pipeline
    │   ├── MiddlewarePipeline.php
    │   └── Builtin/     # CorsMiddleware, RateLimitMiddleware, LoggingMiddleware
    └── Exceptions/      # Custom exceptions

→ Full Architecture Documentation

Design Principles:

✅ SOLID principles
✅ Clean Code practices
✅ DDD architecture (Domain/Application layers)
✅ Type safety (PHP 8.2+)
✅ Zero global state
✅ Interface-based design
✅ 17 individual validation rule files
✅ 3 production-ready built-in middleware

📖 Examples

API with Database

$router->get('/users', function(Request $request) {
    $page = $request->query('page', 1);
    $limit = $request->query('limit', 10);
    
    $users = User::paginate($page, $limit);
    
    return Response::json([
        'data' => $users,
        'page' => $page,
        'total' => User::count()
    ]);
});

Authentication

$router->post('/login', function(Request $request) {
    $validated = $request->validated([
        'email' => 'required|email',
        'password' => 'required|min:8'
    ]);
    
    $token = Auth::attempt($validated);
    
    return Response::json([
        'token' => $token,
        'expires_in' => 3600
    ]);
});

File Upload

$router->post('/upload', function(Request $request) {
    $file = $request->file('document');
    
    if ($file && $file->isValid()) {
        $path = $file->store('uploads');
        return Response::json(['path' => $path], 201);
    }
    
    return Response::json(['error' => 'Invalid file'], 400);
});

→ More Examples

🤝 Contributing

Contributions welcome! Please read CONTRIBUTING.md for guidelines.

📄 License

MIT License - see LICENSE file.

🙏 Acknowledgments

Built with ❤️ by Celio Junior
Inspired by Laravel and Symfony
Architecture based on DDD principles

📞 Support

📧 Email: profissional.celiojunior@outlook.com
🐛 Issues: GitHub Issues
📖 Docs: Documentation

Made with ❤️ and PHP 8.2+

celiovmjr / simplerouter

Maintainers

Details