From c6fbc45a19536522d3de91cf0750b3d5ee96afda Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Karol=C3=ADna=20Vysko=C4=8Dilov=C3=A1?= Date: Thu, 4 Jun 2026 11:23:45 +0200 Subject: [PATCH 1/5] Bump minimum PHP requirement to 7.4.12 to avoid covariant return type fatal (#1) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PHP 7.4.0–7.4.11 have a known engine bug (https://bugs.php.net/bug.php?id=80126) that causes a fatal error when a class method returns a more specific type than its interface declares. The DTO inheritance pattern used throughout this project (e.g. GenerativeAiResult::fromArray returning GenerativeAiResult instead of WithArrayTransformationInterface) triggers this exact bug on affected patch releases. The bug was fixed in PHP 7.4.12. Updates composer.json require and platform config, CONTRIBUTING.md compatibility note, and AGENTS.md key constraints to reflect 7.4.12 as the true minimum. Fixes WordPress/php-ai-client#240 Co-authored-by: Claude --- AGENTS.md | 2 +- CONTRIBUTING.md | 2 +- README.md | 4 ++++ composer.json | 4 ++-- phpcs.xml.dist | 2 +- src/polyfills.php | 15 +++++++++++++++ 6 files changed, 24 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 0897e0a6..1fa7c1d7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -23,7 +23,7 @@ All code in this project MUST adhere to the coding standards, naming conventions Key constraints include: -* PHP 7.4 as the minimum required version. +* PHP 7.4.12 as the minimum required version (PHP 7.4.0–7.4.11 have a known covariant return type bug that causes fatal errors with this codebase). * PER Coding Style (extending PSR-12). * Strict type hinting for all parameters, return values, and properties. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7d1871f0..c0085a91 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -73,7 +73,7 @@ Note that `list` and `string[]` _are not_ the same. The latter is an ali ## PHP Compatibility -All code must be backward compatible with PHP 7.4, which is the minimum required PHP version for this project. +All code must be backward compatible with PHP 7.4.12, which is the minimum required PHP version for this project. PHP 7.4.0–7.4.11 have a known engine bug (https://bugs.php.net/bug.php?id=80126) that causes a fatal error with covariant return types in DTO inheritance; those patch releases are not supported. ## Running Tests diff --git a/README.md b/README.md index 4b55305f..d47b827b 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,10 @@ This project is a PHP SDK, which can be installed as a Composer package. In Word While this project is stewarded by [WordPress AI Team](https://make.wordpress.org/ai/) members and contributors, it is technically WordPress agnostic. The gap the project addresses is relevant for not only the WordPress ecosystem, but the overall PHP ecosystem, so any PHP project could benefit from it. There is also no technical reason to scope it to WordPress, as communicating with AI models and their providers is independent of WordPress's built-in APIs and paradigms. +## Requirements + +- PHP 7.4.12 or later (PHP 7.4.0–7.4.11 have a known covariant return type bug — see [PHP bug #80126](https://bugs.php.net/bug.php?id=80126)) + ## Installation ``` diff --git a/composer.json b/composer.json index 46e1280a..f2366088 100644 --- a/composer.json +++ b/composer.json @@ -20,7 +20,7 @@ "source": "https://github.com/WordPress/php-ai-client" }, "require": { - "php": ">=7.4", + "php": ">=7.4.12", "ext-json": "*", "nyholm/psr7": "^1.8", "php-http/discovery": "^1.0", @@ -71,7 +71,7 @@ }, "optimize-autoloader": true, "platform": { - "php": "7.4" + "php": "7.4.12" }, "sort-packages": true }, diff --git a/phpcs.xml.dist b/phpcs.xml.dist index 2e49db44..f946a657 100644 --- a/phpcs.xml.dist +++ b/phpcs.xml.dist @@ -21,7 +21,7 @@ - + diff --git a/src/polyfills.php b/src/polyfills.php index d5bbee6d..4787fc90 100644 --- a/src/polyfills.php +++ b/src/polyfills.php @@ -8,6 +8,21 @@ declare(strict_types=1); +// PHP 7.4.0–7.4.11 have a covariant return type bug (https://bugs.php.net/bug.php?id=80126) +// that causes a fatal error with the DTO inheritance pattern used throughout this library. +// Warn early so the problem surfaces as a clear message rather than a cryptic fatal. +if (PHP_VERSION_ID >= 70400 && PHP_VERSION_ID < 70412) { + trigger_error( + sprintf( + 'PHP AI Client requires PHP 7.4.12 or later. You are running PHP %s, which has a known' + . ' covariant return type bug (https://bugs.php.net/bug.php?id=80126) that will cause' + . ' fatal errors with this library. Please upgrade to PHP 7.4.12 or later.', + PHP_VERSION + ), + E_USER_WARNING + ); +} + if (!function_exists('array_is_list')) { /** * Checks whether a given array is a list. From c1ef746a86e058f37b87a0b618154a65ed5abd06 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 4 Jun 2026 09:33:02 +0000 Subject: [PATCH 2/5] Update composer.lock content-hash for PHP 7.4.12 platform requirement Regenerates the content-hash after bumping config.platform.php from 7.4 to 7.4.12 in composer.json, which caused the lock file to be flagged as out of date in CI. https://claude.ai/code/session_0196NorwZgGmwBVudD4Q3eQz --- composer.lock | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/composer.lock b/composer.lock index a010d40c..733294a9 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "ba8ef0c4a9742a79115e930f1f4a82f5", + "content-hash": "9fd31cb2e84fdb569d1d5965c4e20451", "packages": [ { "name": "nyholm/psr7", From 1b54e8c66dd1f99aacc6158bc712e91da2b426d1 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 4 Jun 2026 09:36:01 +0000 Subject: [PATCH 3/5] Fix composer.lock content-hash for PHP 7.4.12 platform requirement Corrects the content-hash after bumping config.platform.php from 7.4 to 7.4.12. The previous hash was computed with extra config fields; this one matches Composer's Locker::getContentHash() exactly (only config.platform is included). Passes `composer validate` locally. https://claude.ai/code/session_0196NorwZgGmwBVudD4Q3eQz --- composer.lock | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/composer.lock b/composer.lock index 733294a9..705043c0 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "9fd31cb2e84fdb569d1d5965c4e20451", + "content-hash": "5c3d97a86fe789062b68f24e1cea48f6", "packages": [ { "name": "nyholm/psr7", From e3f970b8bcb43336b3879889c510b9b22c210c72 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 4 Jun 2026 09:41:06 +0000 Subject: [PATCH 4/5] Fix composer.lock platform sections for PHP 7.4.12 minimum Updates the baked-in platform and platform-overrides values in composer.lock to match the new >=7.4.12 requirement in composer.json. The old lock file had platform-overrides.php: 7.4, causing `composer install` to fail because 7.4 < 7.4.12. https://claude.ai/code/session_0196NorwZgGmwBVudD4Q3eQz --- composer.lock | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/composer.lock b/composer.lock index 705043c0..5f949fd3 100644 --- a/composer.lock +++ b/composer.lock @@ -3902,12 +3902,12 @@ "prefer-stable": false, "prefer-lowest": false, "platform": { - "php": ">=7.4", + "php": ">=7.4.12", "ext-json": "*" }, "platform-dev": {}, "platform-overrides": { - "php": "7.4" + "php": "7.4.12" }, "plugin-api-version": "2.9.0" } From ec55a84ce04399b8617c2a8d4f2abe6e83b8b982 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 4 Jun 2026 09:42:59 +0000 Subject: [PATCH 5/5] Remove dead runtime PHP version guard from polyfills.php Since composer.json enforces >=7.4.12, PHP_VERSION_ID is always >=70412 at runtime, making the 7.4.0-7.4.11 trigger_error check unreachable. PHPStan correctly flags both comparisons as always-false/always-true. The composer.json minimum version requirement is sufficient protection. https://claude.ai/code/session_0196NorwZgGmwBVudD4Q3eQz --- src/polyfills.php | 15 --------------- 1 file changed, 15 deletions(-) diff --git a/src/polyfills.php b/src/polyfills.php index 4787fc90..d5bbee6d 100644 --- a/src/polyfills.php +++ b/src/polyfills.php @@ -8,21 +8,6 @@ declare(strict_types=1); -// PHP 7.4.0–7.4.11 have a covariant return type bug (https://bugs.php.net/bug.php?id=80126) -// that causes a fatal error with the DTO inheritance pattern used throughout this library. -// Warn early so the problem surfaces as a clear message rather than a cryptic fatal. -if (PHP_VERSION_ID >= 70400 && PHP_VERSION_ID < 70412) { - trigger_error( - sprintf( - 'PHP AI Client requires PHP 7.4.12 or later. You are running PHP %s, which has a known' - . ' covariant return type bug (https://bugs.php.net/bug.php?id=80126) that will cause' - . ' fatal errors with this library. Please upgrade to PHP 7.4.12 or later.', - PHP_VERSION - ), - E_USER_WARNING - ); -} - if (!function_exists('array_is_list')) { /** * Checks whether a given array is a list.