Update pages

docs/book/v7/upgrading/UPGRADE-7.0.md

@@ -1,24 +1,125 @@
-# Upgrading from 6.x to 7.0
+# Upgrading from 6.0 to 7.0
 
 ## Summary
 
-This page lists the notable pull requests that make up the 6.x to 7.0 upgrade of Dotkernel Admin.
+This page lists the pull requests that make up the 6.0 to 7.0 upgrade of Dotkernel Admin.
+They come from the 6.1.0, 6.2.0 and 7.0.0 releases and are split into important and optional updates, grouped by release.
+Apply them in release order.
 
 ## Details
 
 > You can find a complete list in [Changelog](https://github.com/dotkernel/admin/blob/7.0/CHANGELOG.md)
 
-* Bumped dependencies https://github.com/dotkernel/admin/pull/401
-* Core Sync and update codebase https://github.com/dotkernel/admin/pull/403
+### Important updates
+
+Important updates affect a project that has copied the Dotkernel Admin skeleton.
+
+#### 6.1.0
+
+* Updated auth guards, first change of the login route rules. Read it together with the next pull request and with the 6.2.0 pull request that sets the final rules https://github.com/dotkernel/admin/pull/371
+* Updated auth guards, sets the login route rules to an empty list. The final rules are set in 6.2.0 https://github.com/dotkernel/admin/pull/372
+* Changed route names to be in line with API naming scheme, from `noun-verb` to `verb-noun`, for example `admin::admin-list` becomes `admin::list-admin`.
+  URLs do not change, but the keys in `config/autoload/authorization-guards.global.php`, the `route_name` entries in `config/autoload/navigation.global.php`, the Twig template names and every `generateUri()` call must follow https://github.com/dotkernel/admin/pull/375
+* Updated all handler names to match route names, for example `GetAdminListHandler` becomes `GetListAdminHandler`.
+  Custom handlers, tests and `ConfigProvider` or `RoutesDelegator` entries that reference the old classes must be updated https://github.com/dotkernel/admin/pull/377
+* Implemented `dotkernel/dot-maker` in dev mode, adds `dotkernel/dot-maker` to `require-dev`, the `make` Composer script and `process-timeout` set to `0` https://github.com/dotkernel/admin/pull/380
+* Core sync, `OAuthAccessToken::$userId` gets a default value, only needed when your project has its own copy of the Core entity https://github.com/dotkernel/admin/pull/381
+
+#### 6.2.0
+
+* Removed the initial migration file from `src/Core/src/App/src/Migration`.
+  If your database already ran it, keep your copy or remove it everywhere, otherwise it is reported as an unavailable migration https://github.com/dotkernel/admin/pull/383
+* Added a comment with a new possible RBAC guard config.
+  It also sets the login routes back to `unauthenticated`, which is the final state of the rules from the 6.1.0 pull requests.
+  The commented wildcard config is optional and needs `dotkernel/dot-rbac-guard` `^3.6.1` or `^4.1.1` https://github.com/dotkernel/admin/pull/386
+* Form updates, and the edit services no longer change the password when the submitted password is empty.
+  The rest of the changes are cleanups https://github.com/dotkernel/admin/pull/388
+* Removed the `mezzio/mezzio-tooling` dependency from `composer.json` and from `config/config.php` https://github.com/dotkernel/admin/pull/390
+* Implemented Doctrine table prefixes through the new `table_prefix` key of the database configuration.
+  The default is an empty prefix, so nothing changes unless you set one.
+  Setting a prefix on an existing database requires renaming the tables yourself https://github.com/dotkernel/admin/pull/392
+* Bump to PHP 8.4, the PHP constraint also accepts 8.4, `roave/psr-container-doctrine` also accepts `^6.0.0` and the CLI commands use `$defaultName` https://github.com/dotkernel/admin/pull/393
+
+#### 7.0.0
+
+* Core Sync and update codebase.
+  This is the breaking pull request of the upgrade.
+  The `uuid` identifier is renamed to `id` in entities, columns, route parameters, handlers and services, and `getUuid()` becomes `getId()`.
+  The column type changes from `uuid_binary` to the native `uuid` type, so a migration is required and existing binary UUID data is not converted.
+  `config/autoload/app.global.php` and `config/migrations.php` are deleted, and `local.php.dist`, `templates.global.php` and `cli-config.php` change.
+  Read the FAQ before applying it https://github.com/dotkernel/admin/pull/403
+* Core sync, `OAuthRefreshToken::setIdentifier()` no longer sets the id and `Message::restrictionDeprecation()` is removed.
+  It only matters when you use the OAuth2 refresh token flow or call the removed method.
+  Read it together with the previous pull request, which also changes `OAuthRefreshToken` https://github.com/dotkernel/admin/pull/398
+* Bumped dependencies, raises the constraints of the `dotkernel/*`, `mezzio/*`, `laminas/*` and `ramsey/uuid` packages and adds `symfony/var-exporter` to `require` https://github.com/dotkernel/admin/pull/401
+
+### Optional updates
+
+Skipping an optional update does not change how the application runs.
+
+#### 6.1.0
+
+* Replaced `.laminas-ci/pre-run.sh` script with `.laminas-ci.json` config file https://github.com/dotkernel/admin/pull/378
+
+#### 6.2.0
+
+* Update badge for Packagist dependency version https://github.com/dotkernel/admin/pull/387
+
+#### 7.0.0
+
 * Updated readme, oss https://github.com/dotkernel/admin/pull/397
-* Core sync https://github.com/dotkernel/admin/pull/398
 
 ## FAQ
 
 **Q: Where can I find the complete list of changes for the 7.0 upgrade?**
 
 A: In the [Changelog](https://github.com/dotkernel/admin/blob/7.0/CHANGELOG.md).
 
-**Q: What kind of changes were included in the 6.x to 7.0 upgrade?**
+**Q: Which PHP versions does 7.0 support, and do I have to move to PHP 8.4?**
+
+A: The PHP constraint is `~8.2.0 || ~8.3.0 || ~8.4.0`, so 8.2 and 8.3 keep working and 8.4 is now supported.
+
+**Q: Do I need a database migration?**
+
+A: Yes, because of the `uuid` to `id` rename.
+The `uuid_binary` column type becomes the native `uuid` type, and join columns are renamed, for example `userUuid` and `roleUuid` become `user_id` and `role_id`.
+Write the migration by hand, because existing binary UUID data is not converted automatically and foreign keys must be recreated.
+The `uuid` type declares a native `UUID` column, so check that your database supports it.
+
+**Q: Which configuration files moved or changed?**
+
+A: `config/autoload/app.global.php` and `config/migrations.php` are deleted.
+In `config/autoload/local.php.dist` the database key `default` becomes `mariadb`, a `postgresql` entry is added and `charset` and `collate` become a single `collation` key.
+`appName` moves into `local.php`, and without it the Twig titles render empty.
+`config/autoload/templates.global.php` now sets the timezone to `UTC`.
+The optional `table_prefix` key is added to the database configuration.
+
+**Q: What must I rename after the route and handler renames?**
+
+A: The authorization keys, the navigation `route_name` entries, the Twig templates, the handler classes and every test or custom code that references the old names.
+Route URLs do not change.
+
+**Q: Which login route rules should I end up with?**
+
+A: The login form and login routes use `unauthenticated`, which is the final state after the 6.1.0 and 6.2.0 pull requests.
+
+**Q: What happens to admins that are already logged in?**
+
+A: `AdminIdentity` renames its constructor parameter and property from `uuid` to `id`, so existing sessions may break and admins may have to log in again.
+
+**Q: Which behaviour changes should I look for in my own code?**
+
+A: `UserStatusEnum::values()` now returns all cases, and the old result is available as `validValues()`.
+Unknown settings now return 404 instead of 400.
+Routes use `{id}` instead of `{uuid}`.
+`UserResetPasswordService` and its interface are removed.
+
+**Q: Are the optional updates required?**
+
+A: No, they are CI, README and badge changes and do not change how the application runs.
+
+**Q: How do I upgrade a project that is on 6.0?**
 
-A: Dependency bumps, Core sync and codebase updates, and readme/OSS updates, tracked via their respective pull requests.
+A: Apply the pull requests in release order: 6.1.0, then 6.2.0, then 7.0.0.
+Read pull requests 371, 372 and 386 together, because the final login route rules are set by the last one.
+Read pull requests 375 and 377 together, and pull requests 398 and 403 together.

docs/book/v7/upgrading/UPGRADE-7.2.md

@@ -0,0 +1,91 @@
+# Upgrading from 7.0 to 7.2
+
+## Summary
+
+This page lists the pull requests that make up the 7.0 to 7.2 upgrade of Dotkernel Admin.
+They come from the 7.1.0 and 7.2.0 releases and are split into important and optional updates, grouped by release.
+Apply them in release order.
+
+## Details
+
+> You can find a complete list in [Changelog](https://github.com/dotkernel/admin/blob/7.0/CHANGELOG.md)
+
+### Important updates
+
+Important updates affect a project that has copied the Dotkernel Admin skeleton.
+
+#### 7.1.0
+
+* Bump `dotkernel/dot-maker` to version `2.x`, adds a `conflict` entry that blocks versions below 2.0.
+  It is dev-only and matters when you use `composer make` https://github.com/dotkernel/admin/pull/406
+* Add PHP `8.5` support, the PHP constraint also accepts 8.5 and `IpService::getUserIp()` falls back to `null` when `REMOTE_ADDR` is not set.
+  Read it together with the 7.2.0 pull request that removes PHP 8.2 https://github.com/dotkernel/admin/pull/414
+
+#### 7.2.0
+
+* Update robots.txt, the file changes from the invalid text `deny all` to `User-agent: *` and `Disallow: /`, which blocks every crawler.
+  A project that serves its own `robots.txt` can keep it https://github.com/dotkernel/admin/pull/416
+* Browscap mapping, this pull request changes the `admin_login` table.
+  The columns `deviceBrand`, `deviceModel`, `osPlatform`, `clientEngine` and `clientVersion` are removed and the column `isCrawler` is added.
+  `AdminLoginService` fills the device and client fields with `get_browser()`, and only when the PHP `browscap` ini setting is set.
+  The `AdminLogin` entity loses the getters and setters of the removed columns and gains `getIsCrawler()` and `setIsCrawler()`.
+  The login list template drops five columns and gains an `Is Crawler` column.
+  The pull request contains no migration, read the FAQ before applying it https://github.com/dotkernel/admin/pull/418
+* Bump phpunit to v12.5.23, which also removes PHP 8.2 support, so the PHP constraint is now `~8.3.0 || ~8.4.0 || ~8.5.0`.
+  `phpunit.xml` gains three `displayDetailsOn...` attributes and the unit tests use stubs where no expectations are configured.
+  Read it together with the 7.1.0 pull request that adds PHP 8.5 https://github.com/dotkernel/admin/pull/420
+
+### Optional updates
+
+Skipping an optional update does not change how the application runs.
+
+#### 7.1.0
+
+* Update Qodana action version to v2025.3 https://github.com/dotkernel/admin/pull/411
+
+#### 7.2.0
+
+* No optional updates in this release.
+
+## FAQ
+
+**Q: Where can I find the complete list of changes for the 7.2 upgrade?**
+
+A: In the [Changelog](https://github.com/dotkernel/admin/blob/7.0/CHANGELOG.md).
+
+**Q: Which PHP versions does 7.2 support?**
+
+A: The PHP constraint is `~8.3.0 || ~8.4.0 || ~8.5.0`.
+PHP 8.5 was added in 7.1.0 and PHP 8.2 was removed in 7.2.0, so a project on PHP 8.2 must upgrade PHP before applying the 7.2.0 updates.
+
+**Q: Do I need a database migration?**
+
+A: Yes, because of the `admin_login` changes.
+The pull request does not include a migration, so generate one with `vendor/bin/doctrine-migrations diff` and review it before running it.
+It drops the columns `deviceBrand`, `deviceModel`, `osPlatform`, `clientEngine` and `clientVersion` and adds the column `isCrawler`.
+Dropping the columns discards the device and client data stored in them, so back up the `admin_login` table first.
+
+**Q: What is the `browscap` ini setting for?**
+
+A: `AdminLoginService` reads the browser and device information of a login from `get_browser()`, which needs the `browscap` ini setting in your PHP configuration.
+Without it, the device and client fields are saved empty, and `isMobile` and `isCrawler` are saved as `no`.
+
+**Q: Do I need to update my tests for PHPUnit 12?**
+
+A: Only if your project copied the Dotkernel Admin tests.
+Mock objects without configured expectations become stubs, and `with()` is no longer used on stubs.
+Check the changes of the pull request on the test files you copied.
+
+**Q: Do I need to apply the `robots.txt` change?**
+
+A: Only if you deploy the `public/robots.txt` file of the skeleton.
+It now blocks all crawlers with valid directives.
+
+**Q: Are the optional updates required?**
+
+A: No, they are CI changes and do not change how the application runs.
+
+**Q: In what order do I apply the pull requests?**
+
+A: In release order: 7.1.0 first, then 7.2.0.
+Read pull requests 414 and 420 together, because the first adds PHP 8.5 and the second removes PHP 8.2.

docs/book/v7/upgrading/upgrading.md

@@ -22,7 +22,8 @@ This allows you to track your Admin's version and keep your project up to date w
 
 ## Version to version upgrading
 
-Starting from [version 6.2](UPGRADE-7.0.md) the upgrading procedure is detailed version to version.
+Starting from [version 6.0](UPGRADE-7.0.md) the upgrading procedure is detailed version to version.
+The upgrade from [version 7.0 to 7.2](UPGRADE-7.2.md) is detailed on its own page.
 
 ## FAQ
 
@@ -36,4 +37,5 @@ A: Use the `CHANGELOG.md` file created when you clone the project, and keep it u
 
 **Q: Where can I find version-to-version upgrade details?**
 
-A: Starting from [version 6.2](UPGRADE-7.0.md), the upgrading procedure is documented version to version.
+A: Starting from [version 6.0](UPGRADE-7.0.md), the upgrading procedure is documented version to version.
+The upgrade from [version 7.0 to 7.2](UPGRADE-7.2.md) has its own page.

mkdocs.yml

@@ -25,7 +25,8 @@ nav:
       - "Test the Installation": v7/installation/test-the-installation.md
     - Upgrading:
         - "Upgrade procedure": v7/upgrading/upgrading.md
-        - "Upgrading 6.x to 7.0": v7/upgrading/UPGRADE-7.0.md
+        - "Upgrading 7.0 to 7.2": v7/upgrading/UPGRADE-7.2.md
+        - "Upgrading 6.0 to 7.0": v7/upgrading/UPGRADE-7.0.md
     - How to:
       - "Create Database Migrations": v7/how-to/creating-migrations.md
       - "Create Database Fixtures": v7/how-to/creating-fixtures.md