Download the PHP package julienlinard/php-router without Composer

PHP Router

🇬🇧 Read in English

💝 Support the project

If this bundle is useful to you, consider becoming a sponsor to support the development and maintenance of this open source project.

A modern and complete PHP router for managing your application routes with support for dynamic routes, middlewares, and all essential features.

📋 Table of Contents

• Installation
• Quick Start
• Route Definition
• Dynamic Routes
• Route Groups
• URL Generation
• Request
• Response
• Middlewares
• Error Handling
• API Reference
• Complete Examples

🚀 Installation

Use Composer to install the package:

Requirements: PHP 8.0 or higher

⚡ Quick Start

🛣️ Route Definition

Routes are defined in your controllers using the Route attribute (PHP 8).

Simple Route

Routes with Multiple HTTP Methods

Route Registration

Route Groups

Route groups allow you to organize your routes with a common prefix and shared middlewares.

Complete Example:

🔄 Dynamic Routes

The router supports dynamic routes with parameters automatically extracted from the URL.

Route with One Parameter

Example URL: /user/123 → $userId = '123'

Route with Multiple Parameters

Example URL: /user/123/post/my-article → $userId = '123', $slug = 'my-article'

Accessing Parameters

📥 Request

The Request class provides complete access to HTTP request data.

Path and Method

Query Parameters

HTTP Headers

Cookies

Body (POST/PUT/PATCH)

Utility Methods

Customization for Tests

📤 Response

The Response class allows you to create and send HTTP responses.

Simple Response

JSON Response

Custom Headers

Available Methods

🔌 Dependency Injection

The Router now supports dependency injection via a Container. This allows automatic injection of dependencies into controllers and middlewares.

Configuration with Container

Controllers with Dependencies

Note: If no Container is set, the Router instantiates controllers directly with new.

🛡️ Middlewares

Middlewares allow you to execute code before request processing.

Important : The Middleware interface has been improved. The handle() method now returns ?Response instead of void. If a middleware returns a Response, execution stops and that response is returned. If it returns null, execution continues with the next middleware.

Global Middlewares

Route-Specific Middlewares

Available Middlewares

CorsMiddleware

AuthMiddleware

RoleMiddleware

LoggingMiddleware

Create a Custom Middleware

⚠️ Error Handling

The router automatically handles common errors:

• 404 Not Found: Route not found
• 405 Method Not Allowed: HTTP method not supported for this route
• 500 Internal Server Error: Server error (exceptions)

Customize Error Handling

📚 API Reference

Router

registerRoutes(string $controller): void

Registers all routes of a controller.

addMiddleware(Middleware $middleware): void

Adds a global middleware.

handle(Request $request): Response

Processes a request and returns the response.

getRoutes(): array

Returns all registered routes (debug).

getRouteByName(string $name): ?array

Returns a route by its name.

url(string $name, array $params = [], array $queryParams = []): ?string

Generates a URL from a route name and its parameters.

group(string $prefix, array $middlewares, callable $callback): void

Creates a route group with a prefix and common middlewares.

Request

Main Methods

• getPath(): string - Request path
• getMethod(): string - HTTP method
• getQueryParams(): array - All query parameters
• getQueryParam(string $key, $default = null) - A query parameter
• getHeaders(): array - All headers
• getHeader(string $name, ?string $default = null): ?string - A header
• getCookies(): array - All cookies
• getCookie(string $name, $default = null) - A cookie
• getBody(): ?array - Parsed body
• getBodyParam(string $key, $default = null) - A body parameter
• getRawBody(): string - Raw body
• getRouteParams(): array - All route parameters
• getRouteParam(string $key, $default = null) - A route parameter
• isAjax(): bool - Checks if it's an AJAX request
• wantsJson(): bool - Checks if client accepts JSON

Response

Constructor

Static Methods

• Response::json($data, int $statusCode = 200): self - Creates a JSON response

Instance Methods

• setHeader(string $name, string $value): void - Sets a header
• send(): void - Sends the HTTP response
• getStatusCode(): int - Status code
• getContent(): string - Content
• getHeaders(): array - All headers

🔗 Integration with Other Packages

Integration with core-php

core-php automatically includes php-router. The router is accessible via Application::getRouter().

Integration with auth-php

Use authentication middlewares with php-router.

Standalone Usage

php-router can be used independently of all other packages.

🔗 URL Generation

The router allows you to generate URLs from route names, which facilitates maintenance and avoids hardcoded URLs.

Simple URL Generation

URL Generation with Query Parameters

Usage in Responses

Note: To use $router in your controllers, you can inject it via a dependency container or pass it as a parameter.

💡 Complete Examples

Example 1: Complete REST API with Groups

Example 2: Web Application with Authentication and Groups

🧪 Tests

The package includes a complete test suite. To run the tests:

📝 License

MIT License - See the LICENSE file for more details.

🤝 Contributing

Contributions are welcome! Feel free to open an issue or a pull request.

📧 Support

For any questions or issues, please open an issue on GitHub.

💝 Support the project

If this bundle is useful to you, consider becoming a sponsor to support the development and maintenance of this open source project.

Developed with ❤️ by Julien Linard