EE-293: Declare the optional parameters as explicit nullable types

[vinayak-iyer-paysera]

Summary

On PHP 8.4, loading this library prints eight "Implicitly marking parameter … as nullable is deprecated" notices. This declares the eight parameters as explicit nullable types, which removes them. Nothing a caller passes or receives changes. I propose releasing it as 0.4.2.

Why

• PHP 8.4 deprecates a typed parameter that becomes nullable only because its default is null.
• The eight parameters are $default of getBool(), getFloat(), getInt() and getString(), and $message / $previous of the constructors of InvalidItemException, InvalidItemTypeException and MissingItemException.
• A deprecation is not an error. But an application whose tests fail on deprecations, or that logs them, sees eight notices from this library on every PHP 8.4 process.
• Update dependencies and fix deprecation notices #13 (2023) fixes four of these parameters too, but it cannot be merged as it is. It also raises the minimum to PHP 8.0 and adds return types such as getIterator(): ArrayIterator, which would break subclasses. This change does only the parameters and keeps PHP 7.1.

Changes

• src/: bool $default = null becomes ?bool $default = null, and the same for the other seven. The exception classes also import Exception instead of naming it \Exception. Nothing else in src/ changes.
• phpunit.xml.dist: convertDeprecationsToExceptions="true". PHPUnit 9 then fails a test that triggers a deprecation, and the tests load every class under src/, so the PHP 8.4 jobs fail if an implicitly nullable parameter comes back. PHPUnit 6, used on PHP 7.1 and 7.2, converts deprecations already.
• Tests for explicit null on all eight parameters, for a previous exception on each exception class, and for a custom message. The suite goes from 47 to 58 tests, and line coverage from 90 of 96 lines to 93 of 96.
• CHANGELOG.md: 0.4.2.

Backward compatibility

?bool $default = null and bool $default = null declare the same type. They accept the same values, and PHP treats them as identical for subclasses. A backward-compatibility check from 0.4.1 finds no change in the library's API. ?type needs PHP 7.1, which composer.json already requires. So this is a patch release.

Not in this change: on PHP 8.5, getIterator() passes the wrapped object itself to ArrayIterator, which 8.5 deprecates. The obvious fix changes numeric iteration keys from strings to integers, so it needs its own change.

Test plan

• The suite on PHP 7.1 to 8.4, with the lowest and the highest dependencies, through the workflow's own commands: 58 tests each.
• With the eight parameters put back as they were, both PHP 8.4 jobs fail: 54 of 58 tests error with "Implicitly marking parameter … as nullable is deprecated". The same code passes on PHP 8.3.
• Each new test fails when the code it covers is broken (single mutations of the parameters, of the previous exception each constructor passes on, and of the custom message).
• A Symfony 4.4 and a Symfony 7.4 application built for this check, on PHP 7.4, 8.3 and 8.4: every public method and exception, with the kernel in debug mode and Symfony's DebugClassLoader active. On PHP 8.4 it saw the eight notices before this change and none after.
• A Symfony 6.4 production application's full suite, with the eight parameters changed: the same result for every test before and after.
• CI on this pull request: 18 of 18 jobs pass with 58 tests each (https://github.com/paysera/lib-object-wrapper/actions/runs/36682896946).

🤖 Generated with Claude Code