updated sunset references

docs/book/v7/core-features/error-reporting.md

@@ -63,6 +63,10 @@ Below are the requirements for an application to be able to send error messages
     - `ErrorReportServiceInterface::class` . `tokens` must contain at least one token.
     - At least one of `ErrorReportServiceInterface::class` . `domain_whitelist`/`ip_whitelist` must have at least one value.
 
+> When `enabled` is not `true`, Dotkernel API 7.2 answers `403 Forbidden` (`ForbiddenException`).
+> Versions 7.0 and 7.1 answer `400 Bad Request` (`RuntimeException`).
+> Update to the latest Dotkernel API 7.x release to get the current behavior, see [Upgrading from 7.1 to 7.2](../upgrading/UPGRADE-7.2.md).
+
 > In `src/App/src/Service/ErrorReportService.php`, the method `checkRequest()` tries to validate the request by checking matches for `domain_whitelist` with `isMatchingDomain()` and for `ip_whitelist` with `isMatchingIpAddress()`.
 > If both return `false`, a `ForbiddenException` is thrown and the error message does not get stored.
 

docs/book/v7/core-features/exceptions.md

@@ -83,12 +83,27 @@ throw BadRequestException::create(
 | `ForbiddenException` | `403 Forbidden` | `ErrorReportPermissionMiddleware`, `ErrorReportService` (including when error reporting is disabled) |
 | `NotFoundException` | `404 Not Found` | handlers and services, for a missing resource |
 | `NotAcceptableException` | `406 Not Acceptable` | `ContentNegotiationMiddleware` |
-| `ConflictException` | `409 Conflict` | `UserService`, `AdminService`, `DeprecationMiddleware`, `ResourceProviderMiddleware` |
-| `ExpiredException` | `410 Gone` | the password reset handlers |
+| `ConflictException` | `409 Conflict` | `UserService`, `AdminService`, `ResourceProviderMiddleware` |
+| `ExpiredException` | `410 Gone` | the password reset handlers, `DeprecationMiddleware` once a `sunset` date is reached |
 | `UnsupportedMediaTypeException` | `415 Unsupported Media Type` | `ContentNegotiationMiddleware` |
 | `RuntimeException` | `500 Internal Server Error` | `Renderer`, `HandlerService`, `ErrorReportService`, `HandlerDelegatorFactory`, `ProblemDetailsDelegatorFactory` |
 | `SunsetException` | `500 Internal Server Error` | `BaseDeprecation`, on an invalid `sunset` date |
 
+### Version differences
+
+The table above and the sections below describe Dotkernel API 7.2.
+Earlier 7.x versions behave differently in these places:
+
+| Behavior | 7.0 | 7.1 | 7.2 |
+| --- | --- | --- | --- |
+| `RuntimeException` status | `400 Bad Request` | `400 Bad Request` | `500 Internal Server Error` |
+| `SunsetException` status | `401 Unauthorized` | `401 Unauthorized` | `500 Internal Server Error` |
+| Error reporting disabled | `RuntimeException`, `400 Bad Request` | `RuntimeException`, `400 Bad Request` | `ForbiddenException`, `403 Forbidden` |
+| Malformed JSON request body | no dedicated handling: the problem details middleware answers with the exception's `400` only when exception details are exposed, otherwise with `500` | `MalformedRequestBodyMiddleware` throws `BadRequestException`, `400 Bad Request` | `MalformedRequestBodyMiddleware` throws `BadRequestException`, `400 Bad Request` |
+
+> Update to the latest Dotkernel API 7.x release to get the current behavior.
+> See [Upgrading from 7.0 to 7.1](../upgrading/UPGRADE-7.1.md) and [Upgrading from 7.1 to 7.2](../upgrading/UPGRADE-7.2.md).
+
 ### `BadRequestException` thrown when
 
 - The client tries to **create/update a resource**, but the **request data is invalid/incomplete** (example: client tries to create an account, but does not send the required `identity` field)
@@ -139,6 +154,7 @@ Note that this is not what a failed RBAC check produces — see [How it works](#
 - The **resource cannot be accessed**
     - because it has **expired** (example: account activation link)
     - because it has been **consumed** (example: one-time password)
+    - because it has **reached its sunset date** (example: an endpoint marked with `ResourceDeprecation`), see [API Evolution pattern](../tutorials/api-evolution.md)
 
 ### `UnsupportedMediaTypeException` thrown when
 
@@ -296,7 +312,7 @@ It returns `409 Conflict`.
 
 **Q: What does `ExpiredException` cover?**
 
-A: Resources that can no longer be used because they expired, such as an activation link, or because they were already consumed, such as a one-time password.
+A: Resources that can no longer be used because they expired, such as an activation link, because they were already consumed, such as a one-time password, or because they reached their sunset date, such as a deprecated endpoint.
 It returns `410 Gone`.
 
 **Q: Why can I not pass a message to the constructor?**

docs/book/v7/core-features/rendering-and-sending-emails.md

@@ -81,5 +81,5 @@ Within Dotkernel API the custom renderer is the default.
 
 **Q: Where is the mail transport configured?**
 
-A: In `config/autoload/mail.local.php`, under the `mail` key.
+A: In `config/autoload/mail.local.php`, under the `mail` key (in Dotkernel API 7.0 the file is `config/autoload/mail.global.php`).
 See [Configuration files](../installation/configuration-files.md).

docs/book/v7/flow/middleware-flow.md

@@ -10,6 +10,10 @@ The graph below demonstrates a default flow between Dotkernel's middlewares.
 
 ![Dotkernel API Middleware Flow!](https://docs.dotkernel.org/img/api/v7/dotkernel-middleware-flow.png)
 
+> Dotkernel API 7.1 and 7.2 pipe `MalformedRequestBodyMiddleware` right after `ProblemDetailsMiddleware`, so a malformed request body produces a `400 Bad Request` response.
+> The diagram does not show it, and version 7.0 does not have it.
+> Update to the latest Dotkernel API 7.x release to get it, see [Upgrading from 7.0 to 7.1](../upgrading/UPGRADE-7.1.md).
+
 ## FAQ
 
 **Q: Why does middleware order matter?**

docs/book/v7/installation/composer.md

@@ -34,13 +34,16 @@ The automatic setup script performs these tasks:
 - Creates the `composer.lock` file that locks all dependencies to exact versions (you can still run `composer update` to replace them with newer versions, if available and installable without conflicts).
 - Configures PHP CodeSniffer, a utility to detect code style errors in PHP code.
 - Generate and save the OAuth2 keys in the `data/oauth` folder.
-    - Performed by this script `./bin/generate-oauth2-keys.php`.
+    - Performed by this script `./bin/generate-oauth2-keys.php`, which keeps existing keys.
+    - In Dotkernel API 7.0 it is `./vendor/bin/generate-oauth2-keys`, which regenerates them; see [OAuth2 Security](../security/oauth2-security.md#autogeneration-of-cryptographic-keys).
 - Creates the initial `config/autoload` configuration files.
     - Performed by this script `./bin/composer-post-install-script.php`.
     - These files are created:
         - config/autoload/local.php
         - config/autoload/local.test.php
-        - config/autoload/mail.global.php
+        - config/autoload/mail.local.php (and `config/autoload/mail.local.php.dist`)
+
+> In Dotkernel API 7.0 the mail configuration file is `config/autoload/mail.global.php`; see [Upgrading from 7.0 to 7.1](../upgrading/UPGRADE-7.1.md).
 
 > The post install commands are run automatically on every `composer install` and `composer update`.
 > The scripts check if the files exist to prevent overwriting them.

docs/book/v7/installation/configuration-files.md

@@ -33,6 +33,10 @@ The installation script will duplicate the following files:
 > Most often, you will be using either `Sendmail` or `SMTP` to send emails.
 > If you opt for `SMTP`, ake sure to configure the SMTP connection parameters under the `smtp_options` key.
 
+> Dotkernel API 7.0 creates this file as `config/autoload/mail.global.php` instead.
+> From 7.1 it is `mail.local.php`, plus a `mail.local.php.dist` copy.
+> Update to the latest Dotkernel API 7.x release and move your settings, see [Upgrading from 7.0 to 7.1](../upgrading/UPGRADE-7.1.md).
+
 * `config/autoload/local.test.php.dist` as `config/autoload/local.test.php` to run and create tests.
 
 > This creates a new in-memory database that your tests will run on.
@@ -62,6 +66,7 @@ See the [CORS tutorial](https://docs.dotkernel.org/api-documentation/v7/tutorial
 **Q: Where does `mail.local.php` come from?**
 
 A: It is copied from the `dot-mail` package in `vendor`.
+In Dotkernel API 7.0 the copy is named `mail.global.php`.
 Configure the `mail` key, and the `smtp_options` sub-key if you send through SMTP.
 See [Rendering and sending emails](../core-features/rendering-and-sending-emails.md).
 

docs/book/v7/installation/doctrine-orm.md

@@ -37,7 +37,7 @@ $databases = [
         'table_prefix' => '',
     ],
     'postgresql' => [
-        'host'         => 'localhost',
+        'host'         => '127.0.0.1',
         'dbname'       => 'dotkernel',
         'user'         => '',
         'password'     => '',
@@ -49,6 +49,9 @@ $databases = [
 ];
 ```
 
+> Dotkernel API 7.0 ships the PostgreSQL `host` as `localhost`; 7.1 and 7.2 ship `127.0.0.1`, because `localhost` only works for socket connections.
+> See [Upgrading from 7.0 to 7.1](../upgrading/UPGRADE-7.1.md).
+
 > The database `dotkernel` is provided as an example, but you can use any name you like.
 > Make sure to use the same database name when you create the database in the next step.
 

docs/book/v7/installation/test-the-installation.md

@@ -32,6 +32,10 @@ From this point on, you are ready to add custom code to your application.
 [Bruno](https://www.usebruno.com/) is a Git-native API client we recommend using for working with the API.
 
 The endpoint collection is found in `documentation/Dotkernel_API_Bruno.zip`.
+
+> The Bruno collection was added in Dotkernel API 7.1; version 7.0 ships only the Postman collection and environment files, see the alternative below.
+> Update to the latest Dotkernel API 7.x release to get it, see [Upgrading from 7.0 to 7.1](../upgrading/UPGRADE-7.1.md).
+
 Import it in Bruno by following these steps:
 
 - Open the `My Workspace` dropdown and select `Import workspace`.

docs/book/v7/introduction/file-structure.md

@@ -27,8 +27,8 @@ This folder contains:
 * `cli.php` - Used to build console applications based on [laminas-cli](https://github.com/laminas/laminas-cli)
 * `composer-post-install-script.php` - Runs after `composer install` and copies the shipped distributable config files into place; it asks nothing and needs no input
 * `doctrine` - Doctrine ORM console, used by the fixtures commands to populate the database tables
-* `generate-oauth2-keys.php` - Generates the OAuth2 key pair and encryption key into `data/oauth`
-* `generate-openapi.php` - Generates the OpenAPI document; run through `composer openapi`
+* `generate-oauth2-keys.php` - Generates the OAuth2 key pair and encryption key into `data/oauth`; keeps existing keys (added in 7.1)
+* `generate-openapi.php` - Generates the OpenAPI document; run through `composer openapi` (added in 7.2)
 
 ## `config` folder
 
@@ -59,11 +59,11 @@ This folder contains all service-related local and global config files:
 * `error-handling.global.php` - Configures and activates error logs
 * `local.php.dist` - Local configuration file: database credentials, application name and URL, OAuth2 key paths
 * `local.test.php.dist` - Local configuration for functional tests
-* `mail.local.php.dist` - Mail configuration; e.g. sendmail vs smtp, message configuration, mail logging. Not committed: the post-install script copies it out of `dotkernel/dot-mail` during installation
+* `mail.local.php.dist` - Mail configuration; e.g. sendmail vs smtp, message configuration, mail logging. Not committed: the post-install script copies it out of `dotkernel/dot-mail` during installation (in 7.0 this file is `mail.global.php`)
 * `mezzio.global.php` - Mezzio core config file
-* `openapi.global.php` - Configures the generated OpenAPI document: output file, version, info, servers, tags and security schemes
+* `openapi.global.php` - Configures the generated OpenAPI document: output file, version, info, servers, tags and security schemes (added in 7.2)
 * `problem-details.global.php` - Maps HTTP status codes to the `type` URI used in problem details responses
-* `response-header.global.php` - Defines headers per route
+* `response-header.global.php` - Defines headers, globally and per route
 * `templates.global.php` - Configures `Api\App\Template\RendererInterface`, including the `phtml` template extension
 
 ### Note

docs/book/v7/introduction/packages.md

@@ -45,7 +45,7 @@ Composer refuses to install the project unless all of these are satisfied:
 * `roave/psr-container-doctrine`:`^5.2.2 || ^6.0.0` - Doctrine Factories for PSR-11 Containers
 * `symfony/filesystem`:`^7.2.0` - Provides basic utilities for the filesystem
 * `symfony/var-exporter`:`^6.4 || ^7.4` - Exports serializable PHP data structures as plain PHP code; required to keep Doctrine LazyGhost proxy support
-* `zircote/swagger-php`:`^6.0.0` - Generate interactive documentation for your RESTful API using PHP attributes (preferred) or PHPDoc annotations
+* `zircote/swagger-php`:`^6.4.0` - Generate interactive documentation for your RESTful API using PHP attributes (preferred) or PHPDoc annotations
 
 ### Installed as dependencies
 
@@ -62,6 +62,7 @@ To see which versions you actually have, run `composer show doctrine/orm` (or `c
 
 Declared under `require-dev`, installed unless you pass `--no-dev`:
 
+* `boundwize/structarmed`:`^0.19.0` - Architecture and code quality checks, configured in `structarmed.php`
 * `dotkernel/dot-maker`:`^2.0.0` - Generates modules, handlers, services and input filters; see [Creating a book module using DotMaker](../tutorials/create-book-module-via-dot-maker.md)
 * `laminas/laminas-coding-standard`:`^3.0.1` - Coding standard ruleset used by `composer cs-check` and `composer cs-fix`
 * `laminas/laminas-development-mode`:`^3.13.0` - Toggles development mode; see [Composer](../installation/composer.md)
@@ -72,6 +73,22 @@ Declared under `require-dev`, installed unless you pass `--no-dev`:
 * `roave/security-advisories`:`dev-latest` - Blocks installation of packages with known vulnerabilities
 * `symfony/var-dumper`:`^7.2.3` - Debug output helper
 
+### Version differences
+
+The lists above show the constraints of Dotkernel API 7.2.
+These constraints differ in earlier 7.x versions:
+
+| Package | 7.0 | 7.1 | 7.2 |
+| --- | --- | --- | --- |
+| `mezzio/mezzio-authentication-oauth2` | `^2.11.0` | `^3.0.1` | `^3.0.1` |
+| `symfony/var-exporter` | not required | `^6.4 \|\| ^7.4` | `^6.4 \|\| ^7.4` |
+| `zircote/swagger-php` | `^5.0.7` | `^6.0.0` | `^6.4.0` |
+| `dotkernel/dot-maker` (dev) | `^1.0.2` | `^2.0.0` | `^2.0.0` |
+| `phpunit/phpunit` (dev) | `^10.5.45` | `^12.5.23` | `^12.5.23` |
+| `boundwize/structarmed` (dev) | not required | not required | `^0.19.0` |
+
+> Update to the latest Dotkernel API 7.x release to get these versions, see [Upgrading from 7.0 to 7.1](../upgrading/UPGRADE-7.1.md) and [Upgrading from 7.1 to 7.2](../upgrading/UPGRADE-7.2.md).
+
 ## FAQ
 
 **Q: Is this list authoritative?**

docs/book/v7/introduction/server-requirements.md

@@ -49,7 +49,14 @@ Dotkernel API v7 requires PHP 8.3, 8.4 or 8.5, as declared in `composer.json`:
 ```
 
 Earlier PHP versions are not supported.
-Support for PHP 8.2 was dropped in Dotkernel API 7.2.0.
+
+| Version | Supported PHP versions |
+| --- | --- |
+| 7.0 | 8.2, 8.3, 8.4 and 8.5 (`~8.2.0 \|\| ~8.3.0 \|\| ~8.4.0 \|\| ~8.5.0`) |
+| 7.1 and 7.2 | 8.3, 8.4 and 8.5 |
+
+Support for PHP 8.2 was dropped in Dotkernel API 7.1.
+Update to the latest Dotkernel API 7.x release and raise the `php` constraint in your `composer.json`, see [Upgrading from 7.0 to 7.1](../upgrading/UPGRADE-7.1.md).
 
 > The constraint uses `~` per minor version rather than `>=`, so each supported branch is listed explicitly and a newly released PHP version is not assumed to work until it has been tested.
 
@@ -61,13 +68,14 @@ Support for PHP 8.2 was dropped in Dotkernel API 7.2.0.
 
 ### Why PHP 8.3+?
 
-The floor is set by **typed class constants**, a PHP 8.3 feature used throughout the codebase — for example in `Api\App\Middleware\ContentNegotiationMiddleware`:
+In 7.1 the floor came from the PHPUnit 12 upgrade, which requires PHP 8.3.
+In 7.2 it is also enforced by **typed class constants**, a PHP 8.3 feature used throughout the codebase — for example in `Api\App\Middleware\ContentNegotiationMiddleware`:
 
 ```php
 public const string DEFAULT_HEADERS = 'default';
 ```
 
-The project will not even parse on PHP 8.2.
+The 7.2 code will not even parse on PHP 8.2.
 
 ## Required Settings and Modules & Extensions
 
@@ -182,8 +190,8 @@ A: `utf8mb4_general_ci` or `utf8mb4_unicode_ci` on MariaDB, and `C.UTF-8` or `en
 
 A: PHP 8.3.
 `composer.json` requires `~8.3.0 || ~8.4.0 || ~8.5.0`, so 8.3, 8.4 and 8.5 are supported and earlier versions are not.
-PHP 8.2 support was dropped in Dotkernel API 7.2.0.
-The hard blocker is typed class constants, a PHP 8.3 feature used throughout the codebase, so the project will not parse on 8.2.
+Dotkernel API 7.0 also supports PHP 8.2; that support was dropped in 7.1.
+Since 7.2 typed class constants, a PHP 8.3 feature used throughout the codebase, are a hard blocker, so the project will not parse on 8.2.
 
 **Q: Do I need the CLI SAPI as well as FPM?**
 

docs/book/v7/openapi/configuration.md

@@ -7,6 +7,9 @@ They live in `config/autoload/openapi.global.php` and `application.url`, and `bi
 
 ## Details
 
+> This configuration exists in Dotkernel API 7.2 only.
+> In 7.0 and 7.1 the document root is declared in attributes in `src/App/src/OpenAPI.php`, see [Generate documentation](generate-documentation.md#version-differences) and [Upgrading from 7.1 to 7.2](../upgrading/UPGRADE-7.2.md).
+
 PHP attribute arguments must be constant expressions, so an `OA\Server` attribute cannot read the base URL out of your local config.
 For that reason the document root is assembled by `bin/generate-openapi.php` from configuration after the scan of `src`, while paths and schemas stay in each module's `OpenAPI.php`.
 

docs/book/v7/openapi/generate-documentation.md

@@ -53,6 +53,22 @@ This scans the attributes only.
 The generated file will not contain the `info`, `servers`, tags or security schemes that `composer openapi` adds from configuration, so use it only when you need the raw output.
 Its defaults differ: OpenAPI version `3.0.0` (override with `--version 3.1.0`) and the format taken from the output extension (force it with `--format json` or `--format yaml`).
 
+## Version differences
+
+This page describes Dotkernel API 7.2.
+Earlier 7.x versions generate the file differently:
+
+| Behavior | 7.0 | 7.1 | 7.2 |
+| --- | --- | --- | --- |
+| Command | `./vendor/bin/openapi ./src --output <file>` | `./vendor/bin/openapi ./src --output <file>` | `composer openapi` (`bin/generate-openapi.php`) |
+| Document root (`info`, servers, security schemes, external docs) | attributes in `src/App/src/OpenAPI.php`, with the server `http://api.dotkernel.localhost` | same attributes | `config/autoload/openapi.global.php` and `application.url` |
+| Output file, servers, tags, `exclude_tags` | not configurable | not configurable | `openapi.*` config keys |
+| `operationId` | hash generated by `zircote/swagger-php` | hash generated by `zircote/swagger-php` | explicit, readable names, enforced by a test |
+| `zircote/swagger-php` | `^5.0.7` | `^6.0.0` | `^6.4.0` |
+
+> Update to the latest Dotkernel API 7.x release to use `composer openapi`.
+> See [Upgrading from 7.0 to 7.1](../upgrading/UPGRADE-7.1.md) and [Upgrading from 7.1 to 7.2](../upgrading/UPGRADE-7.2.md).
+
 ## FAQ
 
 **Q: What must I configure before generating?**

docs/book/v7/openapi/initialized-components.md

@@ -12,6 +12,7 @@ Below you will find details on some prepopulated OpenAPI components we added to
 > `OA\Info`, `OA\Server`, `OA\SecurityScheme` and `OA\ExternalDocumentation` are not declared as attributes.
 > `bin/generate-openapi.php` builds them from `config/autoload/openapi.global.php` and `application.url` when you run `composer openapi`, and adds them to the document after the scan of `src`.
 > See [OpenAPI configuration](configuration.md) for every key.
+> That is how Dotkernel API 7.2 works; in 7.0 and 7.1 these components are attributes at the top of `src/App/src/OpenAPI.php`, see [Upgrading from 7.1 to 7.2](../upgrading/UPGRADE-7.2.md).
 
 ## OA\Info
 

docs/book/v7/openapi/introduction.md

@@ -10,6 +10,10 @@ To provide an interactive documentation, Dotkernel API implemented [zircote/swag
 
 Developers can use this library to auto-generate documentation that outlines available endpoints, their request details, and their response formats.
 
+> The pages of this section describe Dotkernel API 7.2, where `composer openapi` generates the file from configuration.
+> Versions 7.0 and 7.1 have no `composer openapi` script or `openapi.global.php`; see the version differences in [Generate documentation](generate-documentation.md#version-differences).
+> Update to the latest Dotkernel API 7.x release, see [Upgrading from 7.1 to 7.2](../upgrading/UPGRADE-7.2.md).
+
 ## FAQ
 
 **Q: What is OpenAPI?**