From adc3074ddb8b9b3ba49407267d62f671e73474e5 Mon Sep 17 00:00:00 2001 From: bidi Date: Thu, 1 Oct 2026 16:05:43 +0300 Subject: [PATCH] created page - upgrade from v1.0 to v1.5 Signed-off-by: bidi --- docs/book/v1/upgrading/UPGRADE-1.5.md | 243 ++++++++++++++++++++++++++ mkdocs.yml | 2 + 2 files changed, 245 insertions(+) create mode 100644 docs/book/v1/upgrading/UPGRADE-1.5.md diff --git a/docs/book/v1/upgrading/UPGRADE-1.5.md b/docs/book/v1/upgrading/UPGRADE-1.5.md new file mode 100644 index 0000000..80d50c7 --- /dev/null +++ b/docs/book/v1/upgrading/UPGRADE-1.5.md @@ -0,0 +1,243 @@ +# Upgrading from 1.0 to 1.5 + +## Summary + +The changes made to the Dotkernel Light skeleton between releases 1.0.0 and 1.5.0, split into updates that affect a project created from the skeleton and updates you can safely skip. + +## Details + +This page covers every release from 1.0.0 to 1.5.0 (1.0.1, 1.1.0, 1.1.1, 1.2.0, 1.3.0, 1.4.0 and 1.5.0), all published from the `1.0` branch of [dotkernel/light](https://github.com/dotkernel/light). +Version numbers on this page are the ones in `composer.json` and `package.json` at tag `1.5.0`. + +Apply the changes to your own project by comparing it with the skeleton at tag `1.5.0`. + +### Important updates + +#### PHP versions + +The supported PHP versions changed from `~8.2.0 || ~8.3.0` to `~8.3.0 || ~8.4.0 || ~8.5.0`. + +- PHP 8.4 support was added in [#25](https://github.com/dotkernel/light/pull/25). +- PHP 8.5 support was added in [#68](https://github.com/dotkernel/light/pull/68). +- PHP 8.2 support was dropped in [#73](https://github.com/dotkernel/light/pull/73), which also upgrades PHPUnit from 10.5 to 12.5.23 and updates `phpunit.xml` and two tests. + +If you run PHP 8.2, upgrade PHP before upgrading the skeleton. +If you have your own tests, they must run on PHPUnit 12. + +#### Composer requirements + +Two pull requests raise the framework requirements: + +- [#29](https://github.com/dotkernel/light/pull/29) cleans up `composer.json`: it removes `friendsofphp/proxy-manager-lts` and raises the minimum version of most requirements. +- [#65](https://github.com/dotkernel/light/pull/65) raises `mezzio/mezzio` and `mezzio/mezzio-fastroute`. + +The `require` block at tag `1.5.0`, which also reflects the changes described in the sections below: + +```json +"require": { + "php": "~8.3.0 || ~8.4.0 || ~8.5.0", + "dotkernel/dot-errorhandler": "^5.0.0", + "laminas/laminas-component-installer": "^3.5.0", + "laminas/laminas-config-aggregator": "^1.17.0", + "mezzio/mezzio": "^3.24.0", + "mezzio/mezzio-fastroute": "^3.13.0", + "mezzio/mezzio-twigrenderer": "^2.17.0" +} +``` + +`dotkernel/dot-controller` and `dotkernel/dot-twigrenderer` are no longer required. +Both are covered below. + +#### Composer scripts + +- [#9](https://github.com/dotkernel/light/pull/9) replaces Psalm with PHPStan. + It removes `psalm.xml`, adds `phpstan.neon` and adds `phpstan/phpstan`, `phpstan/phpstan-phpunit` and `symfony/var-dumper` to `require-dev`. + The `static-analysis` script now runs PHPStan, at level 8 in `phpstan.neon`. +- [#20](https://github.com/dotkernel/light/pull/20) raises the PHPStan memory limit, so the script is now `phpstan analyse --memory-limit 1G`. +- [#37](https://github.com/dotkernel/light/pull/37) removes the `test-coverage` script. +- [#15](https://github.com/dotkernel/light/pull/15) adds `bin/composer-post-install-script.php` and a `post-update-cmd` script that runs it. + The script copies `config/autoload/local.php.dist` to `config/autoload/local.php` if the latter does not exist yet. + +```json +"post-update-cmd": [ + "php bin/composer-post-install-script.php" +], +"static-analysis": "phpstan analyse --memory-limit 1G" +``` + +#### Controllers replaced by handlers and the `routes` configuration + +`dotkernel/dot-controller` is removed and request controllers are replaced by PSR-15 request handlers. + +- [#33](https://github.com/dotkernel/light/pull/33) removes `dot-controller` and replaces the controllers with handlers. + It also adds the `routes` key to `config/autoload/local.php.dist` and removes `403.html.twig`. +- [#43](https://github.com/dotkernel/light/pull/43) refactors the page handler to follow the naming standard. + `Light\Page\Controller\PageController` is removed and `Light\Page\Handler\GetPageViewHandler` is added. + The same pull request renames the `dot_log` writer keys from `priority` to `level`, raises `dot-errorhandler` to 4.2.1 and removes the `mezzio` Composer script. +- [#47](https://github.com/dotkernel/light/pull/47) renames the factories to `GetPageViewHandlerFactory` and `GetIndexViewHandlerFactory`. + +The classes at tag `1.5.0` are: + +- `Light\App\Handler\GetIndexViewHandler`, with `Light\App\Factory\GetIndexViewHandlerFactory` +- `Light\Page\Handler\GetPageViewHandler`, with `Light\Page\Factory\GetPageViewHandlerFactory` + +Routing changed as well: + +- The home page is served by `Light\App\RoutesDelegator` under the route name `app::index`, which replaces the route name `home`. + The template is now `app::index` (`index.html.twig`), which replaces `app::home`. +- The `/page[/{action}]` route is removed. +- `Light\Page\RoutesDelegator` reads the `routes` key of the configuration and registers a `//` route for each entry, named `::