Refactor HTTP router for PHP 8.1, method override, controller formats

Author: muhammetsafak

README.md

@@ -1,161 +1,130 @@
 # InitPHP Router
 
-This is an open source library that lets you create and manage advanced routes for HTTP requests.
+A fast, framework-agnostic HTTP router for PHP. Define expressive routes for any
+HTTP method, group them by prefix, domain, port or client IP, attach middleware,
+inject dependencies into your handlers, generate URLs from named routes and
+serve static files — all on top of any [PSR-7](https://www.php-fig.org/psr/psr-7/)
+request/response implementation.
 
-[![Latest Stable Version](http://poser.pugx.org/initphp/router/v)](https://packagist.org/packages/initphp/router) [![Total Downloads](http://poser.pugx.org/initphp/router/downloads)](https://packagist.org/packages/initphp/router) [![Latest Unstable Version](http://poser.pugx.org/initphp/router/v/unstable)](https://packagist.org/packages/initphp/router) [![License](http://poser.pugx.org/initphp/router/license)](https://packagist.org/packages/initphp/router) [![PHP Version Require](http://poser.pugx.org/initphp/router/require/php)](https://packagist.org/packages/initphp/router)
+[![Latest Stable Version](http://poser.pugx.org/initphp/router/v)](https://packagist.org/packages/initphp/router) [![Total Downloads](http://poser.pugx.org/initphp/router/downloads)](https://packagist.org/packages/initphp/router) [![License](http://poser.pugx.org/initphp/router/license)](https://packagist.org/packages/initphp/router) [![PHP Version Require](http://poser.pugx.org/initphp/router/require/php)](https://packagist.org/packages/initphp/router)
 
 ## Features
 
-- Full support for GET, POST, PUT, DELETE, OPTIONS, PATCH, HEAD and ANY request methods.
-- Variable request methods with (Laravel-like) `$_REQUEST['_method']`. (Default is off, optionally can be activated)
-- Controller support. (HomeController@about or HomeController::about)
-- Middleware/Filter (before and after) support.
-- Static and dynamic route patterns.
-- Ability to create custom parameter pattern.
-- Namespace support.
-- Route grouping support.
-- Domain-based routing support.
-- Ability to define custom 404 errors
-- Ability to name routes
-- Ability to call a class in (Symfony-like) callable functions or parameters of controller methods.
-- Routing by request ports.
-- Routing by client IP address (Via `$_SERVER['REMOTE_ADDR']`. Locally, this value can be something like `::1` or `127.0.0.1`.)
-- A directory path can be defined as a virtual link.
+- GET, POST, PUT, DELETE, OPTIONS, PATCH, HEAD and ANY methods (plus virtual `LINK` routes).
+- Optional Laravel-style method override via `$_REQUEST['_method']`.
+- Controller handlers (`Home@about`, `Home::about`, `Home->about`, or `[Home::class, 'about']`).
+- Before/after middleware (filters), per route and per controller.
+- Static and dynamic route patterns, with a customizable pattern registry.
+- Route grouping by prefix, domain, port and client IP.
+- Named routes and URL generation.
+- Reflection-based dependency injection for handlers, with optional [PSR-11](https://www.php-fig.org/psr/psr-11/) container support.
+- Customizable 404 handling.
+- Serve files or whole directories as virtual links (with path-traversal protection).
+- Optional route caching.
 
 ## Requirements
 
-- PHP 7.2 or later
-- Apache is; **AllowOverride All** should be set to and **mod_rewrite** should be on.
-- Any library that implements the [Psr-7 HTTP Message Interface](https://www.php-fig.org/psr/psr-7/) and an emitter written for Psr-7. For example; [InitPHP HTTP](https://github.com/InitPHP/HTTP) Library
+- PHP 8.1 or later
+- Any [PSR-7](https://www.php-fig.org/psr/psr-7/) HTTP message implementation and a PSR-7 emitter. The examples below use [InitPHP HTTP](https://github.com/InitPHP/HTTP).
+- For pretty URLs, a front controller (`index.php`) with URL rewriting (see below).
 
 ## Installation
 
-```
+```bash
 composer require initphp/router
 ```
 
-Is Apache `.htaccess`
+The examples in the documentation use the InitPHP HTTP library:
 
+```bash
+composer require initphp/http
 ```
+
+### Web server
+
+Apache (`.htaccess`):
+
+```apacheconf
 RewriteEngine On
 RewriteCond %{REQUEST_FILENAME} !-f
 RewriteCond %{REQUEST_FILENAME} !-d
 RewriteRule ^(.*)$ index.php [L]
 ```
 
-Is NGINX;
+NGINX:
 
-```
-server {
-	listen 80;
-	server_name myinitphpdomain.dev;
-	root /var/www/myInitPHPDomain/public;
-	index index.php;
-	location / {
-		try_files $uri $uri/ /index.php?$query_string;
-	}
-	location ~ \.php$ {
-		fastcgi_split_path_info ^(.+\.php)(/.+)$;
-		fastcgi_pass unix:/var/run/php7.4-fpm.sock;
-		fastcgi_index index.php;
-		include fastcgi.conf;
-		fastcgi_intercept_errors on;
-	}
+```nginx
+location / {
+    try_files $uri $uri/ /index.php?$query_string;
 }
 ```
 
-## Configuration
+## Quick start
 
 ```php
-$config = [
-    'paths'                 => [
-        'controller'            => null, //The full path to the directory where the Controller classes are kept.
-        'middleware'            => null, //The full path to the directory where the Middleware classes are kept.
-    ],
-    'namespaces'            => [
-        'controller'            => null, //Namespace prefix of Controller classes, if applicable.
-        'middleware'            => null, //Namespace prefix of Middleware classes, if applicable.
-    ],
-    'base_path'             => '/', // If you are working in a subdirectory; identifies your working directory.
-    'variable_method'       => false, // It makes the request method mutable with Laravel-like $_REQUEST['_method'].
-    'argument_new_instance' => false, // This configuration is used for Request and Response objects that you want as arguments.
-];
-```
-
-## Usage
-
-The following example uses the [InitPHP HTTP](https://github.com/InitPHP/HTTP) library. If you wish, you can use this library using the command below, or you can perform similar operations using another library that uses the Psr-7 HTTP Message interface.
-
-```
-composer require initphp/http
-```
+<?php
+require_once 'vendor/autoload.php';
 
-_**See the Wiki for detailed documentation.**_
-
-```php
-require_once "vendor/autoload.php";
-use \InitPHP\HTTP\Message\{Request, Response, Stream};
-use \InitPHP\HTTP\Emitter\Emitter;
-use \InitPHP\Router\Router;
+use InitPHP\HTTP\Message\{Request, Response};
+use InitPHP\HTTP\Emitter\Emitter;
+use InitPHP\Router\Router;
 
-$request = Request::createFromGlobals();
+$request  = Request::createFromGlobals();
 $response = new Response();
 
-// Create the router object.
-$router = new Router($request, $response, []);
+$router = new Router($request, $response);
 
-// ... Create routes.
 $router->get('/', function () {
     return 'Hello World!';
 });
 
 $router->post('/login', function (Request $request, Response $response) {
-    return $response->json([
-        'status'        => 0,
-        'message'       => 'Unauthorized',
-    ], 401);
+    return $response->withStatus(401);
 });
 
-// If you do not make a definition for 404 errors; An exception is thrown if there is no match with the request.
-$router->error_404(function () {
-    echo 'Page Not Found';
+// Optional: customise the 404 response (otherwise a PageNotFoundException is thrown).
+$router->setNotFoundHandler(function () {
+    return 'Page Not Found';
 });
 
-// Resolve the current route and get the generated HTTP response object.
+// Resolve the current request and build the response.
 $response = $router->dispatch();
 
-// Publish the HTTP response object.
-$emitter = new Emitter;
-$emitter->emit($response);
+// Emit it.
+(new Emitter())->emit($response);
 ```
 
-## Getting Help
+## Documentation
 
-If you have questions, concerns, bug reports, etc, please file an issue in this repository's Issue Tracker.
+Full, example-driven documentation lives in [`docs/`](./docs/README.md):
 
-## Getting Involved
+- [Installation](./docs/installation.md) · [Getting started](./docs/getting-started.md) · [Configuration](./docs/configuration.md)
+- [Routing](./docs/routing.md) · [Route parameters & patterns](./docs/route-parameters.md) · [Route groups](./docs/groups.md)
+- [Controllers](./docs/controllers.md) · [Dependency injection](./docs/dependency-injection.md) · [Middleware](./docs/middleware.md)
+- [Named routes & URLs](./docs/named-routes.md) · [Static file links](./docs/static-file-links.md)
+- [Error handling](./docs/error-handling.md) · [Caching](./docs/caching.md)
+- [Upgrading from 1.x to 2.0](./docs/upgrading-1.x-to-2.0.md)
 
-> All contributions to this project will be published under the MIT License. By submitting a pull request or filing a bug, issue, or feature request, you are agreeing to comply with this waiver of copyright interest.
+## Testing
 
-There are two primary ways to help:
-
-- Using the issue tracker, and
-- Changing the code-base.
-
-### Using the issue tracker
-
-Use the issue tracker to suggest feature requests, report bugs, and ask questions. This is also a great way to connect with the developers of the project as well as others who are interested in this solution.
-
-Use the issue tracker to find ways to contribute. Find a bug or a feature, mention in the issue that you will take on that effort, then follow the Changing the code-base guidance below.
+```bash
+composer test            # PHPUnit
+composer phpstan         # static analysis (level max)
+composer cs:check        # coding standards (PSR-12)
+composer coverage:check  # line coverage with an enforced floor
+```
 
-### Changing the code-base
+## Contributing
 
-Generally speaking, you should fork this repository, make changes in your own fork, and then submit a pull request. All new code should have associated unit tests that validate implemented features and the presence or lack of defects. Additionally, the code should follow any stylistic and architectural guidelines prescribed by the project. In the absence of such guidelines, mimic the styles and patterns in the existing code-base.
+Contributions are welcome. Please read the org-wide
+[Contributing guide](https://github.com/InitPHP/.github/blob/main/CONTRIBUTING.md)
+and the [Code of Conduct](https://github.com/InitPHP/.github/blob/main/CODE_OF_CONDUCT.md)
+before opening a pull request.
 
 ## Credits
 
 - [Muhammet ŞAFAK](https://www.muhammetsafak.com.tr) <<info@muhammetsafak.com.tr>>
 
 ## License
 
-Copyright &copy; 2022 [MIT Licence](./LICENSE)
+Released under the [MIT License](./LICENSE).

docs/README.md

@@ -0,0 +1,44 @@
+# InitPHP Router — Documentation
+
+Welcome to the InitPHP Router documentation. Every page is self-contained and
+built around runnable examples.
+
+## Getting around
+
+1. [Installation](./installation.md)
+2. [Getting started](./getting-started.md)
+3. [Configuration](./configuration.md)
+
+## Routing
+
+4. [Routing](./routing.md) — HTTP verbs, `register()`, `add()`, `any()`
+5. [Route parameters & patterns](./route-parameters.md) — `:type` vs `{name}`, custom patterns, optional segments
+6. [Route groups](./groups.md) — prefix, domain, port and client-IP grouping
+7. [Controllers](./controllers.md) — handler formats and resource controllers
+8. [Named routes & URLs](./named-routes.md) — naming routes and generating URLs
+
+## Handling requests
+
+9. [Dependency injection](./dependency-injection.md) — handler arguments and PSR-11 containers
+10. [Middleware](./middleware.md) — before/after filters
+11. [Static file links](./static-file-links.md) — serving files and directories
+12. [Error handling](./error-handling.md) — 404 handling and exceptions
+13. [Caching](./caching.md) — caching the compiled route table
+
+## Migrating
+
+14. [Upgrading from 1.x to 2.0](./upgrading-1.x-to-2.0.md)
+
+---
+
+Throughout the docs, `$router` is an instance built like this:
+
+```php
+use InitPHP\HTTP\Message\{Request, Response};
+use InitPHP\Router\Router;
+
+$router = new Router(Request::createFromGlobals(), new Response());
+```
+
+Any PSR-7 request/response pair works; [InitPHP HTTP](https://github.com/InitPHP/HTTP)
+is used here for concreteness.

docs/caching.md

@@ -0,0 +1,51 @@
+# Caching
+
+Building the route table on every request is cheap, but for large applications
+you can cache the compiled table to a file and skip re-registration.
+
+## Enabling the cache
+
+```php
+$router = new Router($request, $response, [
+    'cache' => [
+        'enable' => true,
+        'path'   => __DIR__ . '/var/cache/routes.cache',
+        'ttl'    => 86400, // seconds (default: 1 day)
+    ],
+]);
+```
+
+## How it works
+
+- On construction, if a fresh (non-expired) cache file exists, the route table is
+  loaded from it and the router is marked as **cached**.
+- While the router is cached, registration calls (`get()`, `group()`, …) are
+  **no-ops** — the routes already came from the cache.
+- When the router is destroyed and it was **not** loaded from cache, the current
+  route table is written to the cache file.
+
+A typical front controller registers routes unconditionally; on the first
+request they are compiled and cached, and on subsequent requests (until the TTL
+expires) they are loaded from the cache:
+
+```php
+$router = new Router($request, $response, [
+    'cache' => ['enable' => true, 'path' => $cacheFile],
+]);
+
+// These run normally the first time, and are skipped once cached.
+$router->get('/', 'HomeController@index');
+$router->resource('photos', 'PhotoController');
+
+$response = $router->dispatch();
+```
+
+## Limitations
+
+- **Handlers must be cacheable.** String (`'Controller@method'`) and array
+  handlers cache fine. **Closures cannot be serialized**, so don't enable caching
+  if your routes use closure handlers.
+- Delete the cache file (or wait for the TTL) after changing your routes.
+- A write failure is reported as a warning and never interrupts the response.
+
+Next: [Upgrading from 1.x to 2.0](./upgrading-1.x-to-2.0.md).