6.x release prep

CHANGELOG.md

@@ -4,24 +4,43 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](http://keepachangelog.com/) and this project adheres to [Semantic Versioning](http://semver.org/).
 
+## [6.0.0] 2024-11
+
+> Note: While this is a major release, there are no breaking changes to the public API. The major version bump is due to the removal of support for PHP 8.0 and below.
+> 
+> This being said, there are some internal changes that may affect you if you have extended the library in any way. Please test thoroughly before upgrading.
+
+### Added
+- Added full support for PHP 8.1 to 8.4.
+- Ability to use a PSR-15 middleware as a controller.
+- Ability to pass an array of HTTP methods to `Router::map` to create a route that matches multiple methods.
+  - This method still accepts a string so is not a breaking change.
+- Ability to add a custom key to a caching router.
+
+### Changed
+- Fixes and improvements throughout for PHP 8.1 to 8.4.
+
+### Removed
+- Removed support for PHP < 8.1.
+
 ## [5.1.0] 2021-07
 
-## Added
+### Added
 - Support for named routes within groups (@Fredrik82)
 
 ## [5.0.1] 2021-03
 
-## Added
+### Added
 - Support for `psr/container:2.0`
 
 ## [5.0.0] 2021-01
 
-## Added
+### Added
 - A cached router, a way to have a fully built router cached and resolved from cache on subsequent requests.
 - Response decorators, a way to manipulate a response object returned from a matched route.
 - Automatic generation of OPTIONS routes if they have not been defined.
 
-## Changed
+### Changed
 - Minimum PHP requirement bumped to 7.2.
 - `Router` no longer extends FastRoute `RouteCollecter`.
     - `Router` constructor no longer accepts optional FastRoute `RouteParser` and `DataGenerator`.

CONTRIBUTING.md

@@ -7,7 +7,7 @@ We accept contributions via Pull Requests on [Github](https://github.com/thephpl
 
 ## Pull Requests
 
-- **[PSR-2 Coding Standard](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md)** - The easiest way to apply the conventions is to install [PHP Code Sniffer](http://pear.php.net/package/PHP_CodeSniffer).
+- **[PSR-12 Coding Standard](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-12-extended-coding-style-guide.md)** - The easiest way to apply the conventions is to install [PHP Code Sniffer](http://pear.php.net/package/PHP_CodeSniffer).
 
 - **Add tests!** - Your patch won't be accepted if it doesn't have tests.
 

LICENSE.md

@@ -1,6 +1,6 @@
 # The MIT License (MIT)
 
-Copyright (c) 2020 Phil Bennett <[email protected]>
+Copyright (c) 2024 Phil Bennett <[email protected]>
 
 > Permission is hereby granted, free of charge, to any person obtaining a copy
 > of this software and associated documentation files (the "Software"), to deal

README.md

@@ -8,13 +8,14 @@
 [![Quality Score](https://img.shields.io/scrutinizer/g/thephpleague/route.svg?style=flat-square)](https://scrutinizer-ci.com/g/thephpleague/route)
 [![Total Downloads](https://img.shields.io/packagist/dt/league/route.svg?style=flat-square)](https://packagist.org/packages/league/route)
 
-This package is compliant with [PSR-1], [PSR-2], [PSR-4], [PSR-7], [PSR-11] and [PSR-15]. If you notice compliance oversights, please send a patch via pull request.
+This package is compliant with [PSR-1], [PSR-2], [PSR-4], [PSR-7], [PSR-11], [PSR-12] and [PSR-15]. If you notice compliance oversights, please send a patch via pull request.
 
 [PSR-1]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-1-basic-coding-standard.md
 [PSR-2]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md
 [PSR-4]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader.md
 [PSR-7]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-7-http-message.md
 [PSR-11]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-11-container.md
+[PSR-12]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-12-extended-coding-style-guide.md
 [PSR-15]: https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-15-request-handlers.md
 
 ## Install

docs/6.x/controllers.md

@@ -264,6 +264,44 @@ $router = new League\Route\Router;
 $router->map('GET', '/', 'Acme\controller');
 ~~~
 
+### PSR-15 Middleware
+~~~php
+<?php declare(strict_types=1);
+
+namespace Acme;
+
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+
+class SomeController implements \Psr\Http\Server\RequestHandlerInterface
+{
+    /**
+     * Controller.
+     *
+     * @param \Psr\Http\Message\ServerRequestInterface $request
+     *
+     * @return \Psr\Http\Message\ResponseInterface
+     */
+    public function handle(ServerRequestInterface $request): ResponseInterface
+    {
+        // ...
+    }
+}
+~~~
+
+~~~php
+<?php declare(strict_types=1);
+
+$router = new League\Route\Router;
+
+$router->map('GET', '/', new Acme\SomeController);
+
+// or you can use lazy loading and the container will resolve the controller,
+// any resolved controller that implements RequestHandlerInterface will be treated as a PSR-15 middleware
+// and the handle method will be invoked
+$router->map('GET', '/', Acme\SomeController::class);
+~~~
+
 ## Dependency Injection
 
 Where Route is instantiating the objects for your defined controller, a dependency injection container can be used to resolve those objects. Read more on dependency injection [here](/5.x/dependency-injection/).

docs/_data/releases.yml

@@ -2,7 +2,7 @@
   version: unstable
   name: League\Route (dev-5.x)
   type: Unstable
-  requires: PHP >= 7.2.0
+  requires: PHP >= 8.1.0
   release: None
   support: Own Risk
   url: /unstable/
@@ -17,12 +17,30 @@
     Cached Router (BETA): '/unstable/cached-router/'
     Dependency Injection: '/unstable/dependency-injection/'
 -
-  default: true
+    default: true
+    version: 6.x
+    name: League\Route 6.x
+    type: Current
+    requires: PHP >= 8.1.0
+    release: 6.0.0 - 2024-11
+    support: Ongoing
+    url: /6.x/
+    menu:
+        Getting Started: '/6.x/'
+        Basic Usage: '/6.x/usage/'
+        HTTP: '/6.x/http/'
+        Routes: '/6.x/routes/'
+        Controllers: '/6.x/controllers/'
+        Strategies: '/6.x/strategies/'
+        Middleware: '/6.x/middleware/'
+        Cached Router (BETA): '/6.x/cached-router/'
+        Dependency Injection: '/6.x/dependency-injection/'
+-
   version: 5.x
   name: League\Route 5.x
   type: Current
   requires: PHP >= 7.2.0
-  release: 5.1.0 - 2021-07
+  release: 5.1.2 - 2021-07
   support: Ongoing
   url: /5.x/
   menu:
@@ -52,16 +70,3 @@
     Strategies: '/4.x/strategies/'
     Middleware: '/4.x/middleware/'
     Dependency Injection: '/4.x/dependency-injection/'
--
-  version: 3.x
-  name: League\Route 3.x
-  type: Legacy
-  requires: PHP >= 5.4.0
-  release: 3.1.0 - 2018-07
-  support: 2019-02
-  url: /3.x/
-  menu:
-    Getting Started: '/3.x/'
-    Basic Usage: '/3.x/usage/'
-    Concepts: '/3.x/concepts/'
-    Strategies: '/3.x/strategies/'

docs/unstable/cached-router.md

@@ -55,7 +55,7 @@ $cachedRouter = new League\Route\Cache\Router(function (League\Route\Router $rou
     });
 
     return $router;
-}, $cacheStore);
+}, $cacheStore, cacheEnabled: true, cacheKey: 'my-router');
 
 $request = Laminas\Diactoros\ServerRequestFactory::fromGlobals(
     $_SERVER, $_GET, $_POST, $_COOKIE, $_FILES

docs/unstable/controllers.md

@@ -9,9 +9,9 @@ sections:
 ---
 ## Introduction
 
-Every defined route requires a `callable` to invoke when dispatched, something that could be described as a controller in MVC. By default, Route only imposes that the callable is defined with a specific signature, it is given a request object as the first argument, an associative array of wildcard route arguments as the second argument, and expects a response object to be returned. Read more about this in [HTTP](/4.x/http).
+Every defined route requires a `callable` to invoke when dispatched, something that could be described as a controller in MVC. By default, Route only imposes that the callable is defined with a specific signature, it is given a request object as the first argument, an associative array of wildcard route arguments as the second argument, and expects a response object to be returned. Read more about this in [HTTP](/5.x/http).
 
-This behaviour can be changed by creating/using a different strategy, read more about strategies [here](/4.x/strategies).
+This behaviour can be changed by creating/using a different strategy, read more about strategies [here](/5.x/strategies).
 
 ## Defining Controllers
 
@@ -264,6 +264,44 @@ $router = new League\Route\Router;
 $router->map('GET', '/', 'Acme\controller');
 ~~~
 
+### PSR-15 Middleware
+~~~php
+<?php declare(strict_types=1);
+
+namespace Acme;
+
+use Psr\Http\Message\ResponseInterface;
+use Psr\Http\Message\ServerRequestInterface;
+
+class SomeController implements \Psr\Http\Server\RequestHandlerInterface
+{
+    /**
+     * Controller.
+     *
+     * @param \Psr\Http\Message\ServerRequestInterface $request
+     *
+     * @return \Psr\Http\Message\ResponseInterface
+     */
+    public function handle(ServerRequestInterface $request): ResponseInterface
+    {
+        // ...
+    }
+}
+~~~
+
+~~~php
+<?php declare(strict_types=1);
+
+$router = new League\Route\Router;
+
+$router->map('GET', '/', new Acme\SomeController);
+
+// or you can use lazy loading and the container will resolve the controller,
+// any resolved controller that implements RequestHandlerInterface will be treated as a PSR-15 middleware
+// and the handle method will be invoked
+$router->map('GET', '/', Acme\SomeController::class);
+~~~
+
 ## Dependency Injection
 
-Where Route is instantiating the objects for your defined controller, a dependency injection container can be used to resolve those objects. Read more on dependency injection [here](/4.x/dependency-injection/).
+Where Route is instantiating the objects for your defined controller, a dependency injection container can be used to resolve those objects. Read more on dependency injection [here](/5.x/dependency-injection/).

docs/unstable/dependency-injection.md

@@ -27,7 +27,7 @@ namespace Acme;
 
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
-use Zend\Diactoros\Response;
+use Laminas\Diactoros\Response;
 
 class SomeController
 {

docs/unstable/http.md

@@ -12,7 +12,7 @@ HTTP messages form the core of any modern web application. Route is built with t
 
 We also make use of [PSR-15](https://www.php-fig.org/psr/psr-15/) request handlers and middleware.
 
-Throughout this documentation, we will be using [zend-diactoros](https://zendframework.github.io/zend-diactoros/) to provide our HTTP messages but any implementation is supported.
+Throughout this documentation, we will be using [laminas-diactoros](https://docs.laminas.dev/laminas-diactoros/) to provide our HTTP messages but any implementation is supported.
 
 ## The Request
 
@@ -47,7 +47,7 @@ class SomeMiddleware implements MiddlewareInterface
 }
 ~~~
 
-Read more about middleware [here](/4.x/middleware).
+Read more about middleware [here](/5.x/middleware).
 
 ### Controller Signature
 
@@ -63,7 +63,7 @@ function controller(ServerRequestInterface $request) {
 }
 ~~~
 
-See more about controllers [here](/4.x/controllers).
+See more about controllers [here](/5.x/controllers).
 
 ### Request Input
 
@@ -73,7 +73,7 @@ Route does not provide any functionality for dealing with globals such as `$_GET
 
 Because Route is built around PSR-15, this means that middleware and controllers are handles in a [single pass](https://www.php-fig.org/psr/psr-15/meta/#52-single-pass-lambda) approach. What this means in practice is that all middleware is passed a request object but is expected to build and return its own response or pass off to the next middleware in the stack for that to create one. Any controller that is dispatched via Route is wrapped in a middleware that adheres to this.
 
-Once wrapped, your controller ultimately becomes the last middleware in the stack (this does not mean that it has to be invoked last, see [middleware](/4.x/middleware) for more on this), it just means that it will only be concerned with creating and returning a response object.
+Once wrapped, your controller ultimately becomes the last middleware in the stack (this does not mean that it has to be invoked last, see [middleware](/5.x/middleware) for more on this), it just means that it will only be concerned with creating and returning a response object.
 
 An example of a controller building a response might look like this.
 
@@ -82,7 +82,7 @@ An example of a controller building a response might look like this.
 
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
-use Zend\Diactoros\Response;
+use Laminas\Diactoros\Response;
 
 function controller(ServerRequestInterface $request): ResponseInterface {
     $response = new Response;

docs/unstable/middleware.md

@@ -32,7 +32,7 @@ use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
 use Psr\Http\Server\MiddlewareInterface;
 use Psr\Http\Server\RequestHandlerInterface;
-use Zend\Diactoros\Response\RedirectResponse;
+use Laminas\Diactoros\Response\RedirectResponse;
 
 class AuthMiddleware implements MiddlewareInterface
 {

docs/unstable/routes.md

@@ -111,6 +111,25 @@ GET /admin/acme/route2
 GET /admin/acme/route3
 ~~~
 
+### Named Routes
+
+Named routes helps when you want to retrieve a Route by a human friendly label. 
+
+~~~php
+<?php declare(strict_types=1);
+
+$router = new League\Route\Router;
+$request = new Request; // Psr/Http/Message/ServerRequestInterface
+
+$router->group('/admin', function (\League\Route\RouteGroup $route) {
+    $route->map('GET', '/acme/route1', 'AcmeController::actionOne')->setName('actionOne');
+    $route->map('GET', '/acme/route2', 'AcmeController::actionTwo')->setName('actionTwo');
+});
+
+$route = $router->getNamedRoute('actionOne');
+$route->getPath(); // "/admin/acme/route1"
+~~~
+
 ### Conditions
 
 As mentioned above, route conditions can be applied to a group and will be matched across all routes contained in that group, specific routes within the group can override this functionality as displayed below.

docs/unstable/strategies.md

@@ -93,7 +93,7 @@ $router
 
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
-use Zend\Diactoros\Response;
+use Laminas\Diactoros\Response;
 
 function controller(ServerRequestInterface $request, array $args): ResponseInterface {
     // ...
@@ -111,7 +111,7 @@ The application strategy simply allows any `Throwable` to bubble out, you can ca
 
 `League\Route\Strategy\JsonStrategy` aims to make building JSON APIs a little easier. It provides a PSR-7 `Psr\Http\Message\ServerRequestInterface` implementation and any route arguments to the controller as with the application strategy, the difference being that you can either build and return a response yourself or return an array or object, and a JSON response will be built for you.
 
-To make use of the JSON strategy, you will need to provide it with a [PSR-17](https://www.php-fig.org/psr/psr-17/) response factory implementation. Some examples of HTTP Factory packages can be found [here](https://github.com/http-interop?utf8=%E2%9C%93&q=http-factory&type=&language=). We will use the `zend-diactoros` factory as an example.
+To make use of the JSON strategy, you will need to provide it with a [PSR-17](https://www.php-fig.org/psr/psr-17/) response factory implementation. Some examples of HTTP Factory packages can be found [here](https://github.com/http-interop?utf8=%E2%9C%93&q=http-factory&type=&language=). We will use the `laminas-diactoros` factory as an example.
 
 ~~~php
 <?php declare(strict_types=1);
@@ -129,7 +129,7 @@ $router = (new League\Route\Router)->setStrategy($strategy);
 
 use Psr\Http\Message\ResponseInterface;
 use Psr\Http\Message\ServerRequestInterface;
-use Zend\Diactoros\Response;
+use Laminas\Diactoros\Response;
 
 function responseController(ServerRequestInterface $request, array $args): ResponseInterface {
     // ...