Migrate to PHP 8.4 (Ouzo 4.0.0) (#334)

Author: bbankowski

.coveralls.yml

@@ -10,64 +10,62 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        php: [ '8.2.7' ]
+        php: [ '8.4' ]
         db: [ 'MySQL', 'PostgreSQL', 'SQLite' ]
         include:
           - db: MySQL
-            phpunitArgs: "--exclude-group postgres,sqlite3"
-            phpunitEnv: db=mysql # from config/test/config.php
+            phpunitArgs: "--exclude-group postgres --exclude-group sqlite3"
+            phpunitEnv: db=mysql
           - db: PostgreSQL
-            phpunitArgs: "--exclude-group mysql,sqlite3"
-            phpunitEnv: db=postgres # from config/test/config.php
+            phpunitArgs: "--exclude-group mysql --exclude-group sqlite3"
+            phpunitEnv: db=postgres
+            coverage: pcov
           - db: SQLite
-            phpunitArgs: "--exclude-group mysql,postgres,non-sqlite3"
-            phpunitEnv: db=sqlite3 # from config/test/config.php
+            phpunitArgs: "--exclude-group mysql --exclude-group postgres --exclude-group non-sqlite3"
+            phpunitEnv: db=sqlite3
     services:
       mysql:
         image: mysql:8
         env:
           MYSQL_DATABASE: ouzo_test
           MYSQL_ROOT_PASSWORD: password
-        # Set health checks to wait until mysql has started
         options: --health-cmd="mysqladmin ping" --health-interval 10s --health-timeout 5s --health-retries 5
         ports:
           - 3306:3306
       postgres:
-        image: postgres:10.0
+        image: postgres:18
         env:
           POSTGRES_DB: ouzo_test
           POSTGRES_USER: ouzo_user
           POSTGRES_PASSWORD: password
-        # Set health checks to wait until postgres has started
         options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5
         ports:
           - 5432:5432
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@v6
 
       - name: Use PHP ${{ matrix.php }}
         uses: shivammathur/setup-php@v2
         with:
           php-version: ${{ matrix.php }}
           tools: composer:v2
-          coverage: "${{ matrix.coverage }}"
+          coverage: ${{ matrix.coverage || 'none' }}
 
       - name: Seed database (PostgreSQL)
-        if: "${{ matrix.db == 'PostgreSQL' }}"
+        if: matrix.db == 'PostgreSQL'
         run: PGPASSWORD=password psql -h 127.0.0.1 -U ouzo_user -v ON_ERROR_STOP=1 -e -f test/test-db/recreate_schema.sql ouzo_test
 
       - name: Seed database (MySQL)
-        if: "${{ matrix.db == 'MySQL' }}"
+        if: matrix.db == 'MySQL'
         run: |
           mysql -h 127.0.0.1 -u root -ppassword -e "CREATE USER travis; GRANT ALL ON *.* TO travis;"
           cat test/test-db/recreate_schema_mysql.sql | mysql -h 127.0.0.1 -u root -ppassword ouzo_test
 
       - name: Seed database (SQLite)
-        if: "${{ matrix.db == 'SQLite' }}"
+        if: matrix.db == 'SQLite'
         run: echo | sqlite3 ouzo_test -init test/test-db/recreate_schema_sqlite3.sql
-        # I don't know how to run sqlite without it going into interactive mode, so I piped empty stream to it
 
       - name: Cache dependencies installed with Composer
         uses: actions/cache@v4
@@ -77,12 +75,32 @@ jobs:
           restore-keys: php${{ matrix.php }}-composer-
 
       - name: Install dependencies
-        run: composer install --no-progress;
+        run: composer install --no-progress
 
       - name: Run tests
-        run: ${{ matrix.phpunitEnv }} ./vendor/bin/phpunit ${{ matrix.phpunitArgs }} test
+        if: matrix.coverage == ''
+        run: ${{ matrix.phpunitEnv }} ./vendor/bin/phpunit ${{ matrix.phpunitArgs }}
 
-      - name: Upload coverage results to Coveralls
-        env:
-          COVERALLS_REPO_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: ./vendor/bin/php-coveralls --coverage_clover=build/logs/clover.xml -v
+      - name: Run tests with coverage
+        if: matrix.coverage != ''
+        run: ${{ matrix.phpunitEnv }} ./vendor/bin/phpunit ${{ matrix.phpunitArgs }} --coverage-clover build/logs/clover.xml --coverage-html build/coverage-html
+
+      - name: Coverage summary
+        if: matrix.coverage != ''
+        run: |
+          php -r '
+          $xml = simplexml_load_file("build/logs/clover.xml");
+          $metrics = $xml->project->metrics;
+          $stmts = (int)$metrics["statements"];
+          $covered = (int)$metrics["coveredstatements"];
+          $pct = $stmts > 0 ? round($covered / $stmts * 100, 2) : 0;
+          file_put_contents(getenv("GITHUB_STEP_SUMMARY"), "## Code Coverage\n\n**{$pct}%** ({$covered}/{$stmts} statements)\n");
+          '
+
+      - name: Upload coverage report
+        if: matrix.coverage != ''
+        uses: actions/upload-artifact@v7
+        with:
+          name: coverage-report
+          path: build/coverage-html
+          retention-days: 14

.github/workflows/build.yaml

@@ -1,7 +1,27 @@
 CHANGELOG
 =========
 
-IN PROGRESS
+Release 4.0.0
+--------
+Support for PHP versions older than 8.4 is dropped. Minimal PHP version required is 8.4.
+
+Breaking changes:
+* [Core] `Model::jsonSerialize()` now returns `mixed` (attributes array) instead of `string` (JSON). Use `json_encode($model)` to get JSON string.
+* [Core] Upgraded to Symfony Console 7 / Event Dispatcher 7. `Command::execute()` must return `int`.
+* [Core] Upgraded to PSR-3 v3. Logger methods require `string|Stringable $message` parameter.
+* [Core] Removed `doctrine/annotations` dependency.
+
+Enhancements:
+* [ORM] Added support for count query with `DISTINCT` in PostgreSQL dialect.
+* [Core] `Bootstrap::withErrorHandler(ErrorHandler $errorHandler)` set custom error handler which is registered on `Bootstrap::runApplication()`.
+* [Tests] Added new assertion `messageContains` to `CatchException`.
+* [Tests] Upgraded to PHPUnit 11.
+* [Utilities] `Arrays::find()`, `Arrays::any()`, `Arrays::all()` now use native PHP 8.4 `array_find`, `array_any`, `array_all`.
+* [Utilities] `Strings::EMPTY_STRING` is deprecated in favour of `Strings::EMPTY` (now using native `#[Deprecated]` attribute).
+* [Utilities] Deprecated global helper functions in ViewHelper and FormHelper now use native `#[Deprecated]` attribute instead of JetBrains annotations.
+* [Core] Adopted PHP 8.4 "new without parentheses" syntax.
+
+Release 3.0.0
 --------
 Support for PHP 8.0 is dropped. Minimal PHP version required is 8.2.
 

.travis.yml

@@ -0,0 +1,121 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Language
+
+All commit messages, PR titles, PR descriptions, code comments, and documentation must be written in English.
+
+## Code Style
+
+### Imports
+- Always import classes with `use` statements. Never use fully qualified class names (FQCN) inline.
+- Order: PHP built-in → Ouzo framework → third-party.
+
+### Types
+- Always declare parameter types and return types.
+- Fluent methods return `static` (not `self`).
+- Use `is_null()` instead of `=== null`.
+
+### Strings & Arrays
+- Single quotes by default: `'value'`.
+- Double quotes only for interpolation: `"prefix_{$var}"`.
+- Always `[]` for arrays, never `array()`.
+
+### Docblocks
+- Only when types cannot be expressed in code or behavior needs explanation.
+- Do not add `@param`/`@return` when method signatures are sufficient.
+
+### Copyright header (every file)
+```php
+<?php
+/*
+ * Copyright (c) Ouzo contributors, https://github.com/letsdrink/ouzo
+ * This file is made available under the MIT License (view the LICENSE file for more information).
+ */
+```
+
+### Classes
+- `final` only on classes with constants only (e.g. `HttpMethod`, `HttpStatus`).
+- `readonly class` for immutable value objects.
+- No leading underscore on private methods.
+- Keep methods short (3-20 lines), extract longer logic into private helpers.
+
+### Error Handling
+- Throw exceptions immediately with readable messages, no error codes.
+- Never suppress or silently handle errors.
+
+## What is Ouzo
+
+Ouzo is a PHP MVC framework with built-in ORM, dependency injection, and utility libraries. Requires PHP 8.4+.
+
+## Build & Test Commands
+
+```bash
+# Install dependencies
+composer install
+
+# Run all tests (defaults to PostgreSQL, excludes sqlite3 group)
+./vendor/bin/phpunit test
+
+# Run tests against a specific database
+db=mysql ./vendor/bin/phpunit --exclude-group postgres,sqlite3 test
+db=postgres ./vendor/bin/phpunit --exclude-group mysql,sqlite3 test
+db=sqlite3 ./vendor/bin/phpunit --exclude-group mysql,postgres,non-sqlite3 test
+
+# Run a single test file
+./vendor/bin/phpunit test/src/Ouzo/Core/Db/ModelQueryBuilderTest.php
+
+# Run a single test method
+./vendor/bin/phpunit --filter testMethodName test/src/Ouzo/Core/Db/ModelQueryBuilderTest.php
+```
+
+Test databases must be seeded before first run using SQL scripts in `test/test-db/`.
+
+## Architecture
+
+The `Ouzo\` namespace maps to four source modules via PSR-4:
+
+- **`src/Ouzo/Core`** — MVC framework: routing, controllers, views, ORM (Active Record), database layer, config, sessions, middleware, i18n
+- **`src/Ouzo/Goodies`** — Standalone utility library: `Arrays`, `Strings`, `Functions`, `Clock`, `FluentArray`, `Optional`, `Json`, `Objects`, validators, iterators. Also provides test helpers (`Assert`, `CatchException`, `Mock`)
+- **`src/Ouzo/Inject`** — Dependency injection container using PHP 8 attributes (`#[Inject]`, `#[Named]`)
+- **`src/Ouzo/Migrations`** — Database migration system
+
+Goodies and Inject are also published as standalone packages (`letsdrink/ouzo-goodies`, `letsdrink/ouzo-inject`).
+
+### Request lifecycle
+
+`Bootstrap` → `FrontController` → middleware chain (`SessionStarter` → `DefaultRequestId` → `LogRequest` → custom) → `RequestExecutor` resolves route → controller action → `View` renders response.
+
+### ORM
+
+`Model` extends `Validatable`, uses Active Record pattern. Relations: `belongsTo`, `hasOne`, `hasMany`. Query building via `ModelQueryBuilder` with fluent API. Database dialects: `MySqlDialect`, `PostgresDialect`, `Sqlite3Dialect`.
+
+### Routing
+
+Static API on `Route`: `get()`, `post()`, `put()`, `delete()`, `resource()`, `group()`. Annotation-based routing also supported.
+
+## Testing Conventions
+
+- `#[Test]` attribute, not `test` prefix in method names
+- Method names: `shouldDoSomething()` pattern
+- Test structure: `//given`, `//when`, `//then` comments
+- `#[DataProvider('name')]` attribute, not `@dataProvider` annotation
+- `#[Group('mysql')]`, `#[Group('postgres')]`, `#[Group('sqlite3')]`, `#[Group('non-sqlite3')]` for DB-specific tests
+- Base classes:
+  - `DbTransactionalTestCase` — wraps each test in a transaction that rolls back
+  - `ControllerTestCase` — HTTP testing with request/response mocking
+- Custom fluent assertions via `Ouzo\Tests\Assert`:
+  - `Assert::thatArray($arr)->hasSize(3)->contains('x')`
+  - `Assert::thatString($s)->startsWith('foo')`
+  - `Assert::thatModel($m)->hasSameAttributesAs($expected)`
+- `CatchException::when($obj)->method()` + `CatchException::assertThat()->isInstanceOf(...)` for exception testing
+- Custom mock framework in `Ouzo\Tests\Mock\Mock`
+
+## Key Directories
+
+- `bin/` — CLI commands (Symfony Console): model/controller/migration generators, route listing
+- `config/test/` — Test environment config (DB connection selected by `db` env var)
+- `test/Application/` — Fixture models and controllers used by tests
+- `test/test-db/` — SQL schema scripts for each database engine
+- `console` — CLI entry point script

CHANGELOG.md

@@ -1,4 +1,4 @@
-FROM php:8.2.7
+FROM php:8.4
 
 WORKDIR /var/www
 

CLAUDE.md

@@ -1,3 +1,3 @@
-FROM postgres:10
+FROM postgres:18
 
 ADD ./test/test-db/recreate_schema.sql /docker-entrypoint-initdb.d/

Dockerfile-dev

@@ -1,11 +1,9 @@
 ![Ouzo Framework](https://raw.githubusercontent.com/letsdrink/ouzo-website/master/img/logo.png)
 
-Ouzo is a PHP MVC framework with built-in ORM and util libraries. PHP 8.2 or later is required.
+Ouzo is a PHP MVC framework with built-in ORM and util libraries. PHP 8.4 or later is required.
 
-[![Build Status](https://travis-ci.org/letsdrink/ouzo.png?branch=master)](https://travis-ci.org/letsdrink/ouzo)
 [![Build Status](https://github.com/letsdrink/ouzo/workflows/build/badge.svg?branch=master)](https://github.com/letsdrink/ouzo/actions)
 [![Documentation Status](https://readthedocs.org/projects/ouzo/badge/?version=latest)](https://readthedocs.org/projects/ouzo/?badge=latest)
-[![Coverage Status](https://coveralls.io/repos/letsdrink/ouzo/badge.svg?branch=master)](https://coveralls.io/r/letsdrink/ouzo?branch=master)
 [![Latest Stable Version](https://poser.pugx.org/letsdrink/ouzo/v/stable.svg)](https://packagist.org/packages/letsdrink/ouzo)
 [![Total Downloads](https://poser.pugx.org/letsdrink/ouzo/downloads.svg)](https://packagist.org/packages/letsdrink/ouzo)
 [![License](https://poser.pugx.org/letsdrink/ouzo/license.svg)](https://packagist.org/packages/letsdrink/ouzo)
@@ -45,6 +43,9 @@ See the [release notes](https://github.com/letsdrink/ouzo/blob/master/CHANGELOG.
 * Don't forget to update the docs!
 * And the changelog as well.
 
-# Support for PHP versions older than 8.2
+# Support for older PHP versions
 
-Ouzo has dropped support for PHP versions older than 8.2 since Ouzo 3.x. If you want to use Ouzo with PHP 5.6 or 7.x, please try Ouzo 1.x branch, for PHP 8.0 use 2.x branch.
+Ouzo 4.x requires PHP 8.4 or later. For older PHP versions:
+* PHP 8.2 — use Ouzo 3.x branch
+* PHP 8.0 — use Ouzo 2.x branch
+* PHP 5.6 / 7.x — use Ouzo 1.x branch

Dockerfile-postgres

@@ -31,7 +31,7 @@ public function configure()
             ->addArgument('action', InputArgument::OPTIONAL, 'Action name');
     }
 
-    public function execute(InputInterface $input, OutputInterface $output)
+    public function execute(InputInterface $input, OutputInterface $output): int
     {
         $this->input = $input;
         $this->output = $output;

README.md

@@ -16,14 +16,14 @@
 
 class MigrationDumperCommand extends MigrationCommand
 {
-    public function configureCommand()
+    public function configureCommand(): void
     {
         $this->setName('migration:dump')
             ->addArgument('schema_file', InputArgument::REQUIRED, 'Schema output file')
             ->addArgument('data_file', InputArgument::REQUIRED, 'Data output file');
     }
 
-    public function executeCommand(InputInterface $input, OutputInterface $output)
+    public function executeCommand(InputInterface $input, OutputInterface $output): int
     {
         $dbConfig = new MigrationDbConfig($input);
         $schemaFile = $input->getArgument('schema_file');