diff --git a/docs/book/v7/upgrading/UPGRADE-6.0.md b/docs/book/v7/upgrading/UPGRADE-6.0.md index f6f0f453..0745f1a1 100644 --- a/docs/book/v7/upgrading/UPGRADE-6.0.md +++ b/docs/book/v7/upgrading/UPGRADE-6.0.md @@ -9,26 +9,26 @@ This release reorganised shared logic into the Core module, refactored handlers > You can find a complete list in [Changelog](https://github.com/dotkernel/api/blob/7.0/CHANGELOG.md) -* Move common logic to Core module [https://github.com/dotkernel/api/pull/358](https://github.com/dotkernel/api/pull/358) -* Refactored Handlers [https://github.com/dotkernel/api/pull/385](https://github.com/dotkernel/api/pull/385) -* Inject `InputFilters` in handlers [https://github.com/dotkernel/api/pull/389](https://github.com/dotkernel/api/pull/389) -* Implemented route grouping [https://github.com/dotkernel/api/pull/391](https://github.com/dotkernel/api/pull/391) -* Service refactoring [https://github.com/dotkernel/api/pull/396](https://github.com/dotkernel/api/pull/396) -* Autogenerate `OAuth2` keys when cloning the project [https://github.com/dotkernel/api/pull/398](https://github.com/dotkernel/api/pull/398) -* Refresh Postman documentation [https://github.com/dotkernel/api/pull/400](https://github.com/dotkernel/api/pull/400) -* Merge `Admin.Core` into `API.Core` [https://github.com/dotkernel/api/pull/401](https://github.com/dotkernel/api/pull/401) -* Implemented `mezzio/mezzio-problem-details` [https://github.com/dotkernel/api/pull/402](https://github.com/dotkernel/api/pull/402) -* Update pre-run.sh [https://github.com/dotkernel/api/pull/404](https://github.com/dotkernel/api/pull/404) -* Update `GetIndexResourceHandler.php` [https://github.com/dotkernel/api/pull/408](https://github.com/dotkernel/api/pull/408) -* Update `local.php.dist` [https://github.com/dotkernel/api/pull/409](https://github.com/dotkernel/api/pull/409) -* Fixed error handling [https://github.com/dotkernel/api/pull/412](https://github.com/dotkernel/api/pull/412) -* Implemented `ResourceProviderMiddleware` and added `ResourceGuardInterface` [https://github.com/dotkernel/api/pull/403](https://github.com/dotkernel/api/pull/403) -* Updated logic in `ContentNegotiationMiddleware` [https://github.com/dotkernel/api/pull/413](https://github.com/dotkernel/api/pull/413) -* `AuthenticationMiddleware` no longer extends `AuthenticationMiddleware` from `mezzio/mezzio-authentication` [https://github.com/dotkernel/api/pull/418](https://github.com/dotkernel/api/pull/418) -* Update `qodana_code_quality.yml` [https://github.com/dotkernel/api/pull/416](https://github.com/dotkernel/api/pull/416) -* Replaced `Twig` with custom templating solution [https://github.com/dotkernel/api/pull/419](https://github.com/dotkernel/api/pull/419) -* Increased `PHPStan` level to 8 [https://github.com/dotkernel/api/pull/421](https://github.com/dotkernel/api/pull/421) -* Split the `/security/token` endpoint into two separate endpoints [https://github.com/dotkernel/api/pull/423](https://github.com/dotkernel/api/pull/423) +* [#358](https://github.com/dotkernel/api/pull/358): Move common logic to Core module +* [#385](https://github.com/dotkernel/api/pull/385): Refactored Handlers +* [#389](https://github.com/dotkernel/api/pull/389): Inject `InputFilters` in handlers +* [#391](https://github.com/dotkernel/api/pull/391): Implemented route grouping +* [#396](https://github.com/dotkernel/api/pull/396): Service refactoring +* [#398](https://github.com/dotkernel/api/pull/398): Autogenerate `OAuth2` keys when cloning the project +* [#400](https://github.com/dotkernel/api/pull/400): Refresh Postman documentation +* [#401](https://github.com/dotkernel/api/pull/401): Merge `Admin.Core` into `API.Core` +* [#402](https://github.com/dotkernel/api/pull/402): Implemented `mezzio/mezzio-problem-details` +* [#404](https://github.com/dotkernel/api/pull/404): Update pre-run.sh +* [#408](https://github.com/dotkernel/api/pull/408): Update `GetIndexResourceHandler.php` +* [#409](https://github.com/dotkernel/api/pull/409): Update `local.php.dist` +* [#412](https://github.com/dotkernel/api/pull/412): Fixed error handling +* [#403](https://github.com/dotkernel/api/pull/403): Implemented `ResourceProviderMiddleware` and added `ResourceGuardInterface` +* [#413](https://github.com/dotkernel/api/pull/413): Updated logic in `ContentNegotiationMiddleware` +* [#418](https://github.com/dotkernel/api/pull/418): `AuthenticationMiddleware` no longer extends `AuthenticationMiddleware` from `mezzio/mezzio-authentication` +* [#416](https://github.com/dotkernel/api/pull/416): Update `qodana_code_quality.yml` +* [#419](https://github.com/dotkernel/api/pull/419): Replaced `Twig` with custom templating solution +* [#421](https://github.com/dotkernel/api/pull/421): Increased `PHPStan` level to 8 +* [#423](https://github.com/dotkernel/api/pull/423): Split the `/security/token` endpoint into two separate endpoints ## FAQ diff --git a/docs/book/v7/upgrading/UPGRADE-7.0.md b/docs/book/v7/upgrading/UPGRADE-7.0.md index d7bbe6e3..3ecf9337 100644 --- a/docs/book/v7/upgrading/UPGRADE-7.0.md +++ b/docs/book/v7/upgrading/UPGRADE-7.0.md @@ -14,17 +14,17 @@ Version 7.0 does not change the PHP version or any Composer dependency constrain These changes affect your database schema, configuration, entities or runtime behavior. -* Use native UUIDs in database via `ramsey/uuid`: entities get their identifier from the new `UuidIdentifierTrait` and a `UuidType` that declares the SQL type `UUID`. `getUuid()` becomes `getId()` and the `uuid` key becomes `id` in entities, repositories, services, input filters and OpenAPI. A schema migration is required [https://github.com/dotkernel/api/pull/456](https://github.com/dotkernel/api/pull/456) -* PostgreSQL implementation: in `config/autoload/local.php.dist` the `default` connection is renamed `mariadb`, a `postgresql` connection is added, and `charset` and `collate` are replaced by `collation`. `AbstractEnumType` is reworked, `MigrationsMigratedSubscriber` is added and `config/cli-config.php` is updated [https://github.com/dotkernel/api/pull/462](https://github.com/dotkernel/api/pull/462) -* Remove `MethodDeprecation` implementation: the attribute and its tests are deleted, and `DeprecationMiddleware` and the error-report handler no longer use it [https://github.com/dotkernel/api/pull/470](https://github.com/dotkernel/api/pull/470) +* [#456](https://github.com/dotkernel/api/pull/456): Use native UUIDs in database via `ramsey/uuid`: entities get their identifier from the new `UuidIdentifierTrait` and a `UuidType` that declares the SQL type `UUID`. `getUuid()` becomes `getId()` and the `uuid` key becomes `id` in entities, repositories, services, input filters and OpenAPI. A schema migration is required +* [#462](https://github.com/dotkernel/api/pull/462): PostgreSQL implementation: in `config/autoload/local.php.dist` the `default` connection is renamed `mariadb`, a `postgresql` connection is added, and `charset` and `collate` are replaced by `collation`. `AbstractEnumType` is reworked, `MigrationsMigratedSubscriber` is added and `config/cli-config.php` is updated +* [#470](https://github.com/dotkernel/api/pull/470): Remove `MethodDeprecation` implementation: the attribute and its tests are deleted, and `DeprecationMiddleware` and the error-report handler no longer use it ### Optional updates These changes cover documentation and comments. Skipping them does not affect how the API runs. -* Clarify instructions regarding multiple connections in `config/autoload/local.php.dist` [https://github.com/dotkernel/api/pull/472](https://github.com/dotkernel/api/pull/472) -* Update readme and security documents [https://github.com/dotkernel/api/pull/461](https://github.com/dotkernel/api/pull/461) +* [#472](https://github.com/dotkernel/api/pull/472): Clarify instructions regarding multiple connections in `config/autoload/local.php.dist` +* [#461](https://github.com/dotkernel/api/pull/461): Update readme and security documents ## FAQ diff --git a/docs/book/v7/upgrading/UPGRADE-7.1.md b/docs/book/v7/upgrading/UPGRADE-7.1.md index ef9dec10..2fe74512 100644 --- a/docs/book/v7/upgrading/UPGRADE-7.1.md +++ b/docs/book/v7/upgrading/UPGRADE-7.1.md @@ -13,37 +13,37 @@ The headline items are the new PHP 8.3 minimum, the upgrade to `mezzio-authentic These changes affect your PHP version, dependencies, configuration, database schema, entities or runtime behavior. -* Upgrade `mezzio/mezzio-authentication-oauth2` to `^3.0.1`: the OAuth entities and repositories are adapted, `Admin` and `NumericIdentifierTrait` types are tightened, and the post-install script now generates `config/autoload/mail.local.php` [https://github.com/dotkernel/api/pull/511](https://github.com/dotkernel/api/pull/511) -* Bump PHPUnit to `^12.5.23` and drop PHP 8.2 support: `composer.json` now requires PHP `~8.3.0 || ~8.4.0 || ~8.5.0` and tests use stubs instead of mocks [https://github.com/dotkernel/api/pull/510](https://github.com/dotkernel/api/pull/510) -* Implement browscap in `AdminLogin`: the columns `deviceBrand`, `deviceModel`, `osPlatform`, `clientEngine` and `clientVersion` are removed and `isCrawler` is added, so a schema migration is required [https://github.com/dotkernel/api/pull/513](https://github.com/dotkernel/api/pull/513) -* Remove `config/autoload/mail.global.php`: mail settings now live in `mail.local.php` [https://github.com/dotkernel/api/pull/499](https://github.com/dotkernel/api/pull/499) -* OAuth2 token invalidated on Composer install/update: adds `bin/generate-oauth2-keys.php`, which skips existing keys, and points `post-update-cmd` to it [https://github.com/dotkernel/api/pull/506](https://github.com/dotkernel/api/pull/506) -* Add security headers in `config/autoload/response-header.global.php`: `X-Content-Type-Options` and `Referrer-Policy` on all responses, `Cache-Control: no-store` and `Pragma: no-cache` on the token endpoints [https://github.com/dotkernel/api/pull/490](https://github.com/dotkernel/api/pull/490) -* Add `MalformedRequestBodyMiddleware`, piped in `config/pipeline.php`: a malformed request body now results in a `BadRequestException` [https://github.com/dotkernel/api/pull/476](https://github.com/dotkernel/api/pull/476) -* Require `symfony/var-exporter` to keep LazyGhost support [https://github.com/dotkernel/api/pull/485](https://github.com/dotkernel/api/pull/485) -* Core sync: `created` becomes nullable in `TimestampsTrait` and `EntityInterface`, and the Admin, User and role entities are updated [https://github.com/dotkernel/api/pull/486](https://github.com/dotkernel/api/pull/486) -* Bump `zircote/swagger-php` to `^6.0.0` [https://github.com/dotkernel/api/pull/522](https://github.com/dotkernel/api/pull/522) +* [#511](https://github.com/dotkernel/api/pull/511): Upgrade `mezzio/mezzio-authentication-oauth2` to `^3.0.1`: the OAuth entities and repositories are adapted, `Admin` and `NumericIdentifierTrait` types are tightened, and the post-install script now generates `config/autoload/mail.local.php` +* [#510](https://github.com/dotkernel/api/pull/510): Bump PHPUnit to `^12.5.23` and drop PHP 8.2 support: `composer.json` now requires PHP `~8.3.0 || ~8.4.0 || ~8.5.0` and tests use stubs instead of mocks +* [#513](https://github.com/dotkernel/api/pull/513): Implement browscap in `AdminLogin`: the columns `deviceBrand`, `deviceModel`, `osPlatform`, `clientEngine` and `clientVersion` are removed and `isCrawler` is added, so a schema migration is required +* [#499](https://github.com/dotkernel/api/pull/499): Remove `config/autoload/mail.global.php`: mail settings now live in `mail.local.php` +* [#506](https://github.com/dotkernel/api/pull/506): OAuth2 token invalidated on Composer install/update: adds `bin/generate-oauth2-keys.php`, which skips existing keys, and points `post-update-cmd` to it +* [#490](https://github.com/dotkernel/api/pull/490): Add security headers in `config/autoload/response-header.global.php`: `X-Content-Type-Options` and `Referrer-Policy` on all responses, `Cache-Control: no-store` and `Pragma: no-cache` on the token endpoints +* [#476](https://github.com/dotkernel/api/pull/476): Add `MalformedRequestBodyMiddleware`, piped in `config/pipeline.php`: a malformed request body now results in a `BadRequestException` +* [#485](https://github.com/dotkernel/api/pull/485): Require `symfony/var-exporter` to keep LazyGhost support +* [#486](https://github.com/dotkernel/api/pull/486): Core sync: `created` becomes nullable in `TimestampsTrait` and `EntityInterface`, and the Admin, User and role entities are updated +* [#522](https://github.com/dotkernel/api/pull/522): Bump `zircote/swagger-php` to `^6.0.0` ### Optional updates These changes cover development tooling, CI and documentation. Skipping them does not affect how the API runs. -* Bump `dotkernel/dot-maker` to `^2.0.0` and add a Composer `conflict` on versions below `2.0` [https://github.com/dotkernel/api/pull/494](https://github.com/dotkernel/api/pull/494) -* Update PostgreSQL host configuration in `config/autoload/local.php.dist` to `127.0.0.1` [https://github.com/dotkernel/api/pull/465](https://github.com/dotkernel/api/pull/465) -* Add Bruno collection, update readme [https://github.com/dotkernel/api/pull/516](https://github.com/dotkernel/api/pull/516) -* Update API version in README example [https://github.com/dotkernel/api/pull/473](https://github.com/dotkernel/api/pull/473) -* Configure Renovate [https://github.com/dotkernel/api/pull/515](https://github.com/dotkernel/api/pull/515) -* Update branch for Qodana workflow to 7.0 [https://github.com/dotkernel/api/pull/491](https://github.com/dotkernel/api/pull/491) -* Update Qodana action version to v2025.3 [https://github.com/dotkernel/api/pull/500](https://github.com/dotkernel/api/pull/500) -* Update `JetBrains/qodana-action` to v2026 [https://github.com/dotkernel/api/pull/523](https://github.com/dotkernel/api/pull/523) -* Update `JetBrains/qodana-action` to v2026.1.3 [https://github.com/dotkernel/api/pull/527](https://github.com/dotkernel/api/pull/527) -* Update `actions/checkout` to v6 [https://github.com/dotkernel/api/pull/518](https://github.com/dotkernel/api/pull/518) -* Update `actions/checkout` to v7 [https://github.com/dotkernel/api/pull/528](https://github.com/dotkernel/api/pull/528) -* Update `actions/cache` to v5 [https://github.com/dotkernel/api/pull/517](https://github.com/dotkernel/api/pull/517) -* Update `actions/cache` to v6 [https://github.com/dotkernel/api/pull/530](https://github.com/dotkernel/api/pull/530) -* Update `codecov/codecov-action` to v6 [https://github.com/dotkernel/api/pull/520](https://github.com/dotkernel/api/pull/520) -* Update `codecov/codecov-action` to v7 [https://github.com/dotkernel/api/pull/526](https://github.com/dotkernel/api/pull/526) +* [#494](https://github.com/dotkernel/api/pull/494): Bump `dotkernel/dot-maker` to `^2.0.0` and add a Composer `conflict` on versions below `2.0` +* [#465](https://github.com/dotkernel/api/pull/465): Update PostgreSQL host configuration in `config/autoload/local.php.dist` to `127.0.0.1` +* [#516](https://github.com/dotkernel/api/pull/516): Add Bruno collection, update readme +* [#473](https://github.com/dotkernel/api/pull/473): Update API version in README example +* [#515](https://github.com/dotkernel/api/pull/515): Configure Renovate +* [#491](https://github.com/dotkernel/api/pull/491): Update branch for Qodana workflow to 7.0 +* [#500](https://github.com/dotkernel/api/pull/500): Update Qodana action version to v2025.3 +* [#523](https://github.com/dotkernel/api/pull/523): Update `JetBrains/qodana-action` to v2026 +* [#527](https://github.com/dotkernel/api/pull/527): Update `JetBrains/qodana-action` to v2026.1.3 +* [#518](https://github.com/dotkernel/api/pull/518): Update `actions/checkout` to v6 +* [#528](https://github.com/dotkernel/api/pull/528): Update `actions/checkout` to v7 +* [#517](https://github.com/dotkernel/api/pull/517): Update `actions/cache` to v5 +* [#530](https://github.com/dotkernel/api/pull/530): Update `actions/cache` to v6 +* [#520](https://github.com/dotkernel/api/pull/520): Update `codecov/codecov-action` to v6 +* [#526](https://github.com/dotkernel/api/pull/526): Update `codecov/codecov-action` to v7 ## FAQ diff --git a/docs/book/v7/upgrading/UPGRADE-7.2.md b/docs/book/v7/upgrading/UPGRADE-7.2.md index d9a6c126..becf1ddd 100644 --- a/docs/book/v7/upgrading/UPGRADE-7.2.md +++ b/docs/book/v7/upgrading/UPGRADE-7.2.md @@ -7,36 +7,55 @@ The headline items are the new `composer openapi` generator with its configurati ## Details -> You can find the release notes in [7.1.1](https://github.com/dotkernel/api/releases/tag/7.1.1), the [7.1.0...7.1.1 compare view](https://github.com/dotkernel/api/compare/7.1.0...7.1.1), the [7.1.1...7.0 compare view](https://github.com/dotkernel/api/compare/7.1.1...7.0) for the later pull requests, and the commits on the [7.0 branch](https://github.com/dotkernel/api/commits/7.0). -> The project `CHANGELOG.md` does not list the 7.2 pull requests, and pull requests 565, 566, 567 and 570 are not in any release notes, so they are listed here from their code changes. +> Upgrading from 7.1 to 7.2 covers two releases: [7.1.1](https://github.com/dotkernel/api/releases/tag/7.1.1) and [7.2.0](https://github.com/dotkernel/api/releases/tag/7.2.0). +> You can find the changes in their release notes, in the compare views [7.1.0...7.1.1](https://github.com/dotkernel/api/compare/7.1.0...7.1.1) and [7.1.1...7.2.0](https://github.com/dotkernel/api/compare/7.1.1...7.2.0), and in the project `CHANGELOG.md`. ### Important updates These changes affect your Composer scripts and dependencies, configuration, the published OpenAPI document, response behavior or error behavior. -* Add `bin/generate-openapi.php`, the `src/App/src/Helper/OpenApiServers.php` helper it imports, the `openapi` Composer script (`php bin/generate-openapi.php`) and `config/autoload/openapi.global.php`: the OpenAPI document root (`info`, `servers`, security schemes, tags, external docs) now comes from configuration instead of attributes, and the first server URL is taken from `application.url`. Copy the script, the helper and the config file, add the script to your `composer.json`, require `zircote/swagger-php` `^6.4.0` as in pull request 566, add the `openapi` key with `server_description` to `config/autoload/local.php`, and add `public/openapi.yaml` to `.gitignore`. The script exits with `1` without `application.url` and `openapi.output_file`. `output_file` defaults to `public/openapi.yaml`, which the web server serves, so point it elsewhere if the document must stay private. The same file also configures `exclude_tags` (hide a module from the document), `servers` (additional servers), `generated_timezone` (the `info.x-generated` timestamp, or `null` to omit it) and `openapi_version`. In the `OpenAPI.php` files of the `Admin` and `User` modules, replace the `created`, `updated` and `expires` properties with a `$ref` to the new shared `DateTimeObject` schema, which is defined in `src/App/src/OpenAPI.php`, and update the `HomeMessage` example to `Dotkernel API version 7` [https://github.com/dotkernel/api/pull/560](https://github.com/dotkernel/api/pull/560) -* Move the OpenAPI root attributes (`Info`, `Server`, security schemes, external docs) out of `src/App/src/OpenAPI.php`: pull request 551 wraps them in `OA\OpenApi`, and pull request 560 then removes them in favor of the configuration file. Apply both together and remove the attributes from your copy of the file [https://github.com/dotkernel/api/pull/551](https://github.com/dotkernel/api/pull/551) -* Add an explicit `operationId` to every operation in the `OpenAPI.php` files, add a test that fails on a missing or duplicate id (`test/Unit/App/OpenApi/OperationIdTest.php`) and require `zircote/swagger-php` `^6.4.0` (apply this together with pull request 560, whose generator is written against the same version): the ids in the generated document change from hashes to readable names, for example `getAdminCollection` and `postUserResource`. Clients generated from the document must be regenerated [https://github.com/dotkernel/api/pull/566](https://github.com/dotkernel/api/pull/566) -* Change exception status codes: `RuntimeException` and `SunsetException` return `500 Internal Server Error` instead of `400` and `401`, and `ErrorReportService` throws `ForbiddenException` (`403`) instead of `RuntimeException` when error reporting is not enabled. `RuntimeException` is also thrown by the other `ErrorReportService` configuration checks, the template renderer, `HandlerService` and the handler factories, so those failures now return `500` as well, including `POST /error-report` when the endpoint is misconfigured. `SunsetException` is thrown for an invalid `sunset` value in `ResourceDeprecation`. Update API clients that match on the old status codes [https://github.com/dotkernel/api/pull/567](https://github.com/dotkernel/api/pull/567) -* Remove the `ResourceDeprecation` attribute from `GetIndexResourceHandler`, the only handler in the skeleton that used it: `GET /` no longer returns the `Sunset` and `Link` headers. Handlers you annotated yourself keep their attribute; see pull request 570 for what happens once their sunset date passes [https://github.com/dotkernel/api/pull/565](https://github.com/dotkernel/api/pull/565) -* Change `DeprecationMiddleware` so that a resource whose `ResourceDeprecation` sunset date has been reached is no longer executed: the request throws `ExpiredException` and returns `410 Gone` with the detail `This resource is no longer available (sunset on ).`, and the problem-details `type` is the attribute's `link`, or `application.versioning.documentation_url` when the attribute has none. Before, the handler still ran and only the `Sunset` header was added. Copy `src/App/src/Middleware/DeprecationMiddleware.php` and check every handler of yours that uses `#[ResourceDeprecation]` for a sunset date that is already in the past [https://github.com/dotkernel/api/pull/570](https://github.com/dotkernel/api/pull/570) +* [#560](https://github.com/dotkernel/api/pull/560): Add the `composer openapi` generator: the OpenAPI document root (`info`, `servers`, security schemes, tags, external docs) now comes from configuration instead of attributes, and the first server URL is taken from `application.url`. + * Copy `bin/generate-openapi.php`, the `src/App/src/Helper/OpenApiServers.php` helper it imports, and `config/autoload/openapi.global.php`. + * Add the `openapi` script (`php bin/generate-openapi.php`) to your `composer.json` and require `zircote/swagger-php` `^6.4.0`, the first version that provides the `OpenApi\Builder` class the script uses (see pull request 566). + * Add the `openapi` key with `server_description` to `config/autoload/local.php`, and add `public/openapi.yaml` to `.gitignore`. + * Make sure `application.url` and `openapi.output_file` are set: the script exits with `1` without them. + * Note that `output_file` defaults to `public/openapi.yaml`, which the web server serves, so point it elsewhere if the document must stay private. + * Optionally configure `exclude_tags` (hide a module from the document), `servers` (additional servers), `generated_timezone` (the `info.x-generated` timestamp, or `null` to omit it) and `openapi_version`. + * In the `OpenAPI.php` files of the `Admin` and `User` modules, replace the `created`, `updated` and `expires` properties with a `$ref` to the new shared `DateTimeObject` schema, which is defined in `src/App/src/OpenAPI.php`. + * Update the `HomeMessage` example to `Dotkernel API version 7`. +* [#551](https://github.com/dotkernel/api/pull/551): Move the OpenAPI root attributes (`Info`, `Server`, security schemes, external docs) out of `src/App/src/OpenAPI.php`: pull request 551 wraps them in `OA\OpenApi`, and pull request 560 then removes them in favor of the configuration file. Apply both together and remove the attributes from your copy of the file +* [#566](https://github.com/dotkernel/api/pull/566): Add an explicit `operationId` to every operation: the ids in the generated document change from hashes to readable names, for example `getAdminCollection` and `postUserResource`. + * Add an `operationId` to every operation in the `OpenAPI.php` files. + * Add the test `test/Unit/App/OpenApi/OperationIdTest.php`, which fails on a missing or duplicate id. + * Require `zircote/swagger-php` `^6.4.0`. Apply this together with pull request 560: its generator needs `OpenApi\Builder`, which first appears in `^6.4.0`, and the new test needs `OpenApi\Undefined`, which first appears in 6.3.1. + * Regenerate any client that was generated from the document. +* [#567](https://github.com/dotkernel/api/pull/567): Change exception status codes: `RuntimeException` and `SunsetException` return `500 Internal Server Error` instead of `400` and `401`, and `ErrorReportService` throws `ForbiddenException` (`403`) instead of `RuntimeException` when error reporting is not enabled. + * `RuntimeException` is also thrown by the other `ErrorReportService` configuration checks, the template renderer, `HandlerService` and the handler factories, so those failures now return `500` as well, including `POST /error-report` when the endpoint is misconfigured. + * `SunsetException` is thrown for an invalid `sunset` value in `ResourceDeprecation`. + * Update API clients that match on the old status codes. +* [#565](https://github.com/dotkernel/api/pull/565): Remove the `ResourceDeprecation` attribute from `GetIndexResourceHandler`, the only handler in the skeleton that used it: `GET /` no longer returns the `Sunset` and `Link` headers. Handlers you annotated yourself keep their attribute; see pull request 570 for what happens once their sunset date passes +* [#570](https://github.com/dotkernel/api/pull/570): Change `DeprecationMiddleware` so that a resource whose `ResourceDeprecation` sunset date has been reached is no longer executed. Before, the handler still ran and only the `Sunset` header was added. + * The request now throws `ExpiredException` and returns `410 Gone` with the detail `This resource is no longer available (sunset on ).`. + * The problem-details `type` is the attribute's `link`, or `application.versioning.documentation_url` when the attribute has none. + * Copy `src/App/src/Middleware/DeprecationMiddleware.php`. + * Check every handler of yours that uses `#[ResourceDeprecation]` for a sunset date that is already in the past. ### Optional updates These changes cover documentation fixes, type-only cleanups, development tooling and CI. Skipping them does not affect how the API runs. -* Document the recover-account endpoint at its registered path in `src/User/src/OpenAPI.php`: `/user/account/recover` instead of `/account/recover-identity`. The route itself is unchanged [https://github.com/dotkernel/api/pull/550](https://github.com/dotkernel/api/pull/550) -* Add class constant type declarations (for example in the input filters, the DBAL types, `Message`, `ConfigProvider`, `UserAvatarService`, `ContentNegotiationMiddleware` and `ErrorReportService`) and the `SlevomatCodingStandard.TypeHints.ClassConstantTypeHint` rule to `phpcs.xml`. It only matters if a subclass of the affected classes overrides one of those constants [https://github.com/dotkernel/api/pull/537](https://github.com/dotkernel/api/pull/537) -* Add `boundwize/structarmed` as a dev dependency with a `structarmed.php` architecture file, and make closures `static` [https://github.com/dotkernel/api/pull/553](https://github.com/dotkernel/api/pull/553) -* Update `boundwize/structarmed` to `^0.18.0` [https://github.com/dotkernel/api/pull/554](https://github.com/dotkernel/api/pull/554) -* Update `boundwize/structarmed` to `^0.19.0` [https://github.com/dotkernel/api/pull/562](https://github.com/dotkernel/api/pull/562) -* Clarify in `config/autoload/cors.local.php.dist` how to restrict the allowed origins [https://github.com/dotkernel/api/pull/536](https://github.com/dotkernel/api/pull/536) -* Update the README: password warning for the fixtures [https://github.com/dotkernel/api/pull/540](https://github.com/dotkernel/api/pull/540) -* Update the README to reflect the application purpose [https://github.com/dotkernel/api/pull/541](https://github.com/dotkernel/api/pull/541) -* Update `JetBrains/qodana-action` to v2026.2.0 [https://github.com/dotkernel/api/pull/532](https://github.com/dotkernel/api/pull/532) -* Update `JetBrains/qodana-action` to v2026.2.1 [https://github.com/dotkernel/api/pull/542](https://github.com/dotkernel/api/pull/542) -* Update `JetBrains/qodana-action` to v2026.2.2 [https://github.com/dotkernel/api/pull/557](https://github.com/dotkernel/api/pull/557) +* [#550](https://github.com/dotkernel/api/pull/550): Document the recover-account endpoint at its registered path in `src/User/src/OpenAPI.php`: `/user/account/recover` instead of `/account/recover-identity`. The route itself is unchanged +* [#537](https://github.com/dotkernel/api/pull/537): Add class constant type declarations (for example in the input filters, the DBAL types, `Message`, `ConfigProvider`, `UserAvatarService`, `ContentNegotiationMiddleware` and `ErrorReportService`) and the `SlevomatCodingStandard.TypeHints.ClassConstantTypeHint` rule to `phpcs.xml`. It only matters if a subclass of the affected classes overrides one of those constants +* [#553](https://github.com/dotkernel/api/pull/553): Add `boundwize/structarmed` as a dev dependency with a `structarmed.php` architecture file, and make closures `static` +* [#554](https://github.com/dotkernel/api/pull/554): Update `boundwize/structarmed` to `^0.18.0` +* [#562](https://github.com/dotkernel/api/pull/562): Update `boundwize/structarmed` to `^0.19.0` +* [#536](https://github.com/dotkernel/api/pull/536): Clarify in `config/autoload/cors.local.php.dist` how to restrict the allowed origins +* [#540](https://github.com/dotkernel/api/pull/540): Update the README: password warning for the fixtures +* [#541](https://github.com/dotkernel/api/pull/541): Update the README to reflect the application purpose +* [#532](https://github.com/dotkernel/api/pull/532): Update `JetBrains/qodana-action` to v2026.2.0 +* [#542](https://github.com/dotkernel/api/pull/542): Update `JetBrains/qodana-action` to v2026.2.1 +* [#557](https://github.com/dotkernel/api/pull/557): Update `JetBrains/qodana-action` to v2026.2.2 ## FAQ @@ -78,5 +97,4 @@ They only concern documentation, type declarations, development tooling and CI. **Q: Where do I find the complete list of changes?** -A: In the [7.1.1 release notes](https://github.com/dotkernel/api/releases/tag/7.1.1), the [7.1.1...7.0 compare view](https://github.com/dotkernel/api/compare/7.1.1...7.0) and the [commits on the 7.0 branch](https://github.com/dotkernel/api/commits/7.0). -The project `CHANGELOG.md` does not list these pull requests. +A: In the release notes of [7.1.1](https://github.com/dotkernel/api/releases/tag/7.1.1) and [7.2.0](https://github.com/dotkernel/api/releases/tag/7.2.0), the compare views [7.1.0...7.1.1](https://github.com/dotkernel/api/compare/7.1.0...7.1.1) and [7.1.1...7.2.0](https://github.com/dotkernel/api/compare/7.1.1...7.2.0), and the project `CHANGELOG.md`.