Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 6 additions & 5 deletions .github/workflows/codecov.yml
Original file line number Diff line number Diff line change
Expand Up @@ -15,14 +15,14 @@ jobs:
- ubuntu-latest

php:
- "8.2"
- "8.3"
- "8.4"
- "8.5"
- "8.6"

steps:
- name: Checkout
uses: actions/checkout@v3
uses: actions/checkout@v7

- name: Install PHP
uses: shivammathur/setup-php@v2
Expand All @@ -36,20 +36,21 @@ jobs:
run: echo "COMPOSER_CACHE_DIR=$(composer config cache-dir)" >> $GITHUB_ENV

- name: Cache dependencies installed with composer
uses: actions/cache@v3
uses: actions/cache@v6
with:
path: ${{ env.COMPOSER_CACHE_DIR }}
key: php${{ matrix.php }}-composer-${{ hashFiles('**/composer.json') }}
restore-keys: |
php${{ matrix.php }}-composer-

- name: Install dependencies with composer
run: composer install --prefer-dist --no-interaction --no-progress --optimize-autoloader --ansi
# laminas/laminas-stratigility does not declare PHP 8.6 yet; drop the flag once it does.
run: composer install --prefer-dist --no-interaction --no-progress --optimize-autoloader --ansi ${{ matrix.php == '8.6' && '--ignore-platform-req=php+' || '' }}

- name: Collect code coverage with PHPUnit
run: vendor/bin/phpunit --colors=always --coverage-clover clover.xml

- name: Send code coverage report to Codecov.io
uses: codecov/codecov-action@v3
uses: codecov/codecov-action@v7
with:
token: ${{ secrets.CODECOV_TOKEN }}
13 changes: 7 additions & 6 deletions .github/workflows/static-analysis.yml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ on:
name: Run PHPStan checks

jobs:
mutation:
static-analysis:
name: PHPStan ${{ matrix.php }}-${{ matrix.os }}

runs-on: ${{ matrix.os }}
Expand All @@ -15,36 +15,37 @@ jobs:
- ubuntu-latest

php:
- "8.2"
- "8.3"
- "8.4"
- "8.5"
- "8.6"

steps:
- name: Checkout
uses: actions/checkout@v4
uses: actions/checkout@v7

- name: Install PHP
uses: shivammathur/setup-php@v2
with:
php-version: "${{ matrix.php }}"
coverage: pcov
coverage: none
ini-values: assert.exception=1, zend.assertions=1, error_reporting=-1, log_errors_max_len=0, display_errors=On
tools: composer:v2, cs2pr

- name: Determine composer cache directory
run: echo "COMPOSER_CACHE_DIR=$(composer config cache-dir)" >> $GITHUB_ENV

- name: Cache dependencies installed with composer
uses: actions/cache@v4
uses: actions/cache@v6
with:
path: ${{ env.COMPOSER_CACHE_DIR }}
key: php${{ matrix.php }}-composer-${{ hashFiles('**/composer.json') }}
restore-keys: |
php${{ matrix.php }}-composer-

- name: Install dependencies with composer
run: composer install --prefer-dist --no-interaction --no-progress --optimize-autoloader --ansi
# laminas/laminas-stratigility does not declare PHP 8.6 yet; drop the flag once it does.
run: composer install --prefer-dist --no-interaction --no-progress --optimize-autoloader --ansi ${{ matrix.php == '8.6' && '--ignore-platform-req=php+' || '' }}

- name: Run static analysis with PHPStan
run: vendor/bin/phpstan analyse
1 change: 1 addition & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ composer.phar
/vendor/
.phpcs-cache
.phpunit.result.cache
.phpunit.cache

# Commit your application's lock file http://getcomposer.org/doc/01-basic-usage.md#composer-lock-the-lock-file
# You may choose to ignore a library lock file http://getcomposer.org/doc/02-libraries.md#lock-file
Expand Down
3 changes: 3 additions & 0 deletions .laminas-ci.json
Original file line number Diff line number Diff line change
@@ -1,3 +1,6 @@
{
"ignore_php_platform_requirements": {
"8.6": true
},
"backwardCompatibilityCheck": true
}
76 changes: 76 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1 +1,77 @@
# Changelog

All notable changes to this project are documented in this file.

## 2.0.0 - TBD

### Added

- PHP 8.6 support.
- `Dot\Router\Exception\MissingMiddlewareException` (PSR-11 not-found), `InvalidMiddlewareException` (PSR-11 container exception) and `InvalidArgumentException`.
- Version 2 documentation and an upgrade guide.

### Changed

- Group middleware now also runs for callable route handlers (closures and callable arrays).
- `$excludeMiddleware` now removes group middleware only, never the route's own middleware or handler, and matches middleware objects by class.
- `MiddlewareContainer::get()` throws PSR-11 exceptions instead of `Exception` or `ArgumentCountError`.
- `MiddlewareFactory::pipeline()` and `prepare([])` throw `InvalidArgumentException` for an empty list.
- A group route whose prefix and path are both empty throws `InvalidArgumentException`.
- Minimum `mezzio/mezzio-fastroute` is `^3.15`; `mezzio/mezzio-router` and `psr/http-server-handler` are now declared requirements; minimum `psr/container` is `^1.1.2`.
- PHPDoc types narrowed for static analysis: `non-empty-string` paths and names, `list<string>` methods.
- PHPStan level 8, PHPUnit 12.

### Removed

- PHP 8.2 support.

### Fixed

- A `RouteGroupCollector` created by the container, or with `new`, no longer fails with an uninitialized `$middleware` property.
- Building a pipeline from an empty list no longer raises a PHP warning.

## 1.1.0 - 2025-10-30

### Added

- PHP 8.4 and 8.5 support (#11).

### Removed

- PHP 8.1 support (#11).

## 1.0.5 - 2025-03-22

### Changed

- Clearer instructions for creating single routes and route groups (#9).

## 1.0.4 - 2025-03-20

### Changed

- Group middleware is merged with the route handlers (#7).

## 1.0.3 - 2025-03-20

### Changed

- The middleware argument of `RouteCollector::group()` is optional (#5).

## 1.0.2 - 2025-03-20

### Changed

- Allow `laminas/laminas-stratigility` 3.x and 4.x (#3).

## 1.0.1 - 2025-03-20

### Changed

- Documentation tweaks.

## 1.0.0 - 2025-03-20

### Added

- Initial release.
23 changes: 16 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,22 +11,31 @@ Documentation is available at: https://docs.dotkernel.org/dot-router/.
## Badges

![OSS Lifecycle](https://img.shields.io/osslifecycle/dotkernel/dot-router)
![PHP from Packagist (specify version)](https://img.shields.io/packagist/php-v/dotkernel/dot-router/1.1.0)
![PHP from Packagist (specify version)](https://img.shields.io/packagist/php-v/dotkernel/dot-router/2.0.0)

[![GitHub issues](https://img.shields.io/github/issues/dotkernel/dot-router)](https://github.com/dotkernel/dot-router/issues)
[![GitHub forks](https://img.shields.io/github/forks/dotkernel/dot-router)](https://github.com/dotkernel/dot-router/network)
[![GitHub stars](https://img.shields.io/github/stars/dotkernel/dot-router)](https://github.com/dotkernel/dot-router/stargazers)
[![GitHub license](https://img.shields.io/github/license/dotkernel/dot-router)](https://github.com/dotkernel/dot-router/blob/1.0/LICENSE)
[![GitHub license](https://img.shields.io/github/license/dotkernel/dot-router)](https://github.com/dotkernel/dot-router/blob/2.0/LICENSE)

[![Build Static](https://github.com/dotkernel/dot-router/actions/workflows/continuous-integration.yml/badge.svg?branch=1.0)](https://github.com/dotkernel/dot-router/actions/workflows/continuous-integration.yml)
[![Build Static](https://github.com/dotkernel/dot-router/actions/workflows/continuous-integration.yml/badge.svg?branch=2.0)](https://github.com/dotkernel/dot-router/actions/workflows/continuous-integration.yml)
[![codecov](https://codecov.io/gh/dotkernel/dot-router/graph/badge.svg?token=ubNnFctuDR)](https://codecov.io/gh/dotkernel/dot-router)
[![PHPStan](https://github.com/dotkernel/dot-router/actions/workflows/static-analysis.yml/badge.svg?branch=1.0)](https://github.com/dotkernel/dot-router/actions/workflows/static-analysis.yml)
[![PHPStan](https://github.com/dotkernel/dot-router/actions/workflows/static-analysis.yml/badge.svg?branch=2.0)](https://github.com/dotkernel/dot-router/actions/workflows/static-analysis.yml)

## Versions

| Version | Supported PHP versions | Documentation |
| --- | --- | --- |
| 2.x | 8.3, 8.4, 8.5, 8.6 | https://docs.dotkernel.org/dot-router/v2/overview/ |
| 1.x | 8.2, 8.3, 8.4, 8.5 | https://docs.dotkernel.org/dot-router/v1/overview/ |

Upgrading from 1.x? Read the [upgrade guide](https://docs.dotkernel.org/dot-router/v2/upgrading/).

## Requirements

- **PHP**: 8.2, 8.3, 8.4 or 8.5
- **PHP**: 8.3, 8.4, 8.5 or 8.6
- **laminas/laminas-stratigility**: ^3.0 || ^4.0
- **mezzio/mezzio-fastroute**: ^3.12
- **mezzio/mezzio-fastroute**: ^3.15

## Setup

Expand All @@ -36,7 +45,7 @@ Run the following command in your application's root directory:
composer require dotkernel/dot-router
```

Open your application's `config/config.php` and the following line:
Open your application's `config/config.php` and add the following line:

```php
Dot\Router\ConfigProvider::class,
Expand Down
8 changes: 4 additions & 4 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,10 @@

## Supported Versions

| Version | Supported | PHP Version |
|---------|--------------------|---------------------------------------------------------------------------------------------------------|
| 1.x | :white_check_mark: | ![PHP from Packagist (specify version)](https://img.shields.io/packagist/php-v/dotkernel/dot-cli/1.1.0) |
| Version | Supported | PHP Version |
|---------|------------------------------------|------------------------------------------------------------------------------------------------------------|
| 2.x | :white_check_mark: | ![PHP from Packagist (specify version)](https://img.shields.io/packagist/php-v/dotkernel/dot-router/2.0.0) |
| 1.x | :white_check_mark: (security only) | ![PHP from Packagist (specify version)](https://img.shields.io/packagist/php-v/dotkernel/dot-router/1.1.0) |

## Reporting Potential Security Issues

Expand All @@ -25,4 +26,3 @@ If we verify a reported security vulnerability, our policy is:

- We will patch the current release branch, as well as the immediate prior minor release branch.
- After patching the release branches, we will immediately issue new security fix releases for each patched release branch.

15 changes: 8 additions & 7 deletions composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -24,19 +24,20 @@
}
},
"require": {
"php": "~8.2.0 || ~8.3.0 || ~8.4.0 || ~8.5.0",
"php": "~8.3.0 || ~8.4.0 || ~8.5.0 || ~8.6.0",
"laminas/laminas-stratigility": "^3.0 || ^4.0",
"mezzio/mezzio-fastroute": "^3.12",
"psr/container": "^1.0 || ^2.0",
"mezzio/mezzio-fastroute": "^3.15",
"mezzio/mezzio-router": "^3.18 || ^4.0.1",
"psr/container": "^1.1.2 || ^2.0",
"psr/http-message": "^1.0 || ^2.0",
"psr/http-server-middleware": "^1.0"

"psr/http-server-handler": "^1.0.2",
"psr/http-server-middleware": "^1.0.2"
},
"require-dev": {
"laminas/laminas-coding-standard": "^3.0",
"laminas/laminas-coding-standard": "^3.1",
"phpstan/phpstan": "^2.1",
"phpstan/phpstan-phpunit": "^2.0",
"phpunit/phpunit": "^10.5"
"phpunit/phpunit": "^12.5"
},
"autoload": {
"psr-4": {
Expand Down
7 changes: 7 additions & 0 deletions docs/book/v2/configuration.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# Configuration

After installation, register `dot-router` in your project by adding the below line to your configuration aggregator (usually: `config/config.php`):

```php
Dot\Router\ConfigProvider::class,
```
106 changes: 106 additions & 0 deletions docs/book/v2/features.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,106 @@
# Features

## Route groups

During development, developers often need to create sets of visually similar routes.
The traditional way is creating each route, one by one, like in the below example:

```php
$app->post('/product/create', CreateProductHandler::class, 'product:create');
$app->delete('/product/delete/{id}', DeleteProductHandler::class, 'product:delete');
$app->patch('/product/update/{id}', UpdateProductHandler::class, 'product:update');
$app->get('/product/view/{id}', GetProductHandler::class, 'product:view');
```

Besides the features provided by `mezzio/mezzio-fastroute`, `dot-router` offers route groups, which are collections of routes that (partially) share the same path.

To use this feature, first get an instance of the `Dot\Router\RouteCollector` using the below code:

```php
/** @var \Dot\Router\RouteCollectorInterface $routeCollector */
$routeCollector = $container->get(\Dot\Router\RouteCollectorInterface::class);
```

Then rewrite the above routes using the below code:

```php
$routeCollector->group('/product')
->post('/create', CreateProductHandler::class, 'product:create')
->delete('/delete/{id}', DeleteProductHandler::class, 'product:delete')
->patch('/update/{id}', UpdateProductHandler::class, 'product:update')
->get('/view/{id}', GetProductHandler::class, 'product:view');
```

Note that **/product** becomes the group prefix and the routes only specify the part that is specific to them.
When `dot-router` registers the routes, it prepends the prefix to each route path.
The prefix and the path are joined as they are, so do not end the prefix with `/` (`/product/` plus `/create` gives `/product//create`).

### Advantages

- DRY: no need for repeating common route parts
- encapsulation: similar routes are grouped in a single block of code (vs. each route a separate statement)
- easy path refactoring: modify all routes at once by changing only the prefix
- easy copying/moving: copying/moving an entire group makes sure that you don't accidentally omit a route

## Group middleware

Besides sharing the same path, routes often share middleware too.
A good example is `CheckOwnerMiddleware` in the below example:

```php
$app->delete('/product/delete/{id}', [CheckOwnerMiddleware::class, DeleteProductHandler::class], 'product:delete');
$app->patch('/product/update/{id}', [CheckOwnerMiddleware::class, UpdateProductHandler::class], 'product:update');
$app->get('/product/view/{id}', [CheckOwnerMiddleware::class, GetProductHandler::class], 'product:view');
```

Pass the shared middleware as the second argument of `group()`, and `dot-router` runs it before the handler of every route in the group:

```php
$routeCollector->group('/product', CheckOwnerMiddleware::class)
->delete('/delete/{id}', DeleteProductHandler::class, 'product:delete')
->patch('/update/{id}', UpdateProductHandler::class, 'product:update')
->get('/view/{id}', GetProductHandler::class, 'product:view');
```

Group middleware runs first, in the order given, followed by the route's own middleware and handler.
This applies to every kind of route handler: class names, objects, closures and other callables.

## Exclude middleware

Sometimes one route in a group must not run a group middleware.
In the below example, creating a product has no owner to check yet:

```php
$app->post('/product/create', CreateProductHandler::class, 'product:create');
$app->delete('/product/delete/{id}', [CheckOwnerMiddleware::class, DeleteProductHandler::class], 'product:delete');
$app->patch('/product/update/{id}', [CheckOwnerMiddleware::class, UpdateProductHandler::class], 'product:update');
$app->get('/product/view/{id}', [CheckOwnerMiddleware::class, GetProductHandler::class], 'product:view');
```

For such cases, each group route accepts `$excludeMiddleware` as its last argument:

```php
$routeCollector->group('/product', CheckOwnerMiddleware::class)
->post('/create', CreateProductHandler::class, 'product:create', CheckOwnerMiddleware::class)
->delete('/delete/{id}', DeleteProductHandler::class, 'product:delete')
->patch('/update/{id}', UpdateProductHandler::class, 'product:update')
->get('/view/{id}', GetProductHandler::class, 'product:view');
```

The `product:create` route is now the equivalent of:

```php
$app->post('/product/create', CreateProductHandler::class, 'product:create');
```

How exclusion works:

- `$excludeMiddleware` is a class name or a list of class names.
- It removes **group** middleware only. The route's own middleware and handler always run.
- A group middleware given as a class name is excluded when that exact name is listed.
- A group middleware given as an object is excluded when it is an instance of a listed class or interface.

### Advantages

- extends the DRYness of route groups by allowing to specify common middlewares only once per group
- shorter and easier-to-read route definitions
Loading
Loading