From 54bb248823cc505e2efea707524594125ad1696c Mon Sep 17 00:00:00 2001 From: bidi Date: Thu, 1 Oct 2026 15:22:55 +0300 Subject: [PATCH 1/2] regenerated page - upgrade from v6.0 to v7.0 Signed-off-by: bidi --- docs/book/v7/upgrading/UPGRADE-7.0.md | 115 ++++++++++++++++++++++++-- docs/book/v7/upgrading/upgrading.md | 4 +- mkdocs.yml | 2 +- 3 files changed, 111 insertions(+), 10 deletions(-) diff --git a/docs/book/v7/upgrading/UPGRADE-7.0.md b/docs/book/v7/upgrading/UPGRADE-7.0.md index efde743..c340df9 100644 --- a/docs/book/v7/upgrading/UPGRADE-7.0.md +++ b/docs/book/v7/upgrading/UPGRADE-7.0.md @@ -1,17 +1,73 @@ -# 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 @@ -19,6 +75,51 @@ This page lists the notable pull requests that make up the 6.x to 7.0 upgrade of 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. diff --git a/docs/book/v7/upgrading/upgrading.md b/docs/book/v7/upgrading/upgrading.md index d5726b1..54ffb4b 100644 --- a/docs/book/v7/upgrading/upgrading.md +++ b/docs/book/v7/upgrading/upgrading.md @@ -22,7 +22,7 @@ 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. ## FAQ @@ -36,4 +36,4 @@ 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. diff --git a/mkdocs.yml b/mkdocs.yml index dc57614..55c74ba 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -25,7 +25,7 @@ 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 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 From e80b391b1ed9b6133be6dc5ae6d4ef6680d53ced Mon Sep 17 00:00:00 2001 From: bidi Date: Thu, 1 Oct 2026 15:35:26 +0300 Subject: [PATCH 2/2] added page - upgrade from v7.0 to v7.2 Signed-off-by: bidi --- docs/book/v7/upgrading/UPGRADE-7.2.md | 91 +++++++++++++++++++++++++++ docs/book/v7/upgrading/upgrading.md | 2 + mkdocs.yml | 1 + 3 files changed, 94 insertions(+) create mode 100644 docs/book/v7/upgrading/UPGRADE-7.2.md diff --git a/docs/book/v7/upgrading/UPGRADE-7.2.md b/docs/book/v7/upgrading/UPGRADE-7.2.md new file mode 100644 index 0000000..e22ca26 --- /dev/null +++ b/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. diff --git a/docs/book/v7/upgrading/upgrading.md b/docs/book/v7/upgrading/upgrading.md index 54ffb4b..6a8a233 100644 --- a/docs/book/v7/upgrading/upgrading.md +++ b/docs/book/v7/upgrading/upgrading.md @@ -23,6 +23,7 @@ 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.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 @@ -37,3 +38,4 @@ 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.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. diff --git a/mkdocs.yml b/mkdocs.yml index 55c74ba..6f6c70b 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -25,6 +25,7 @@ nav: - "Test the Installation": v7/installation/test-the-installation.md - Upgrading: - "Upgrade procedure": v7/upgrading/upgrading.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