[tyrsson]

Symptom

Renovate PR #25 (lock file maintenance) moves the dev dependency php-db/phpdb from ed4a407c2f51b951e0261da0bf93baacb23d2e98 to 1570a6122cde75699394a6a38cf17335c3b1d622 on 0.6.x. Both Mago (PHP 8.4) and Mago (PHP 8.5) then fail mago analyze with:

error[incompatible-property-type]: Property `PhpDb\Session\Sql\Insert::$specifications` has an incompatible type declaration from docblock.

Root cause

At 1570a612, php-db/phpdb src/Sql/Insert.php declares the property as @var array<string, Specification>, where Specification = string|array<string, list<ParameterSpecification>> is a psalm type alias defined on php-db/phpdb src/Sql/AbstractSql.php.

webware-phpdb src/Session/Sql/Insert.php overrode the same property with the looser @var array[]|string[]. PHP requires property types to be invariant, so the two declarations cannot coexist.

Fix

The @var override is removed, so the property inherits the parent declaration. The values assigned here are plain strings, which satisfy the parent type, so nothing about runtime behaviour changes.

Why this form: the override documented nothing the parent does not already say. The two more explicit alternatives were tested against both lock states:

Form	With ed4a407 (this branch's lock)	With 1570a612 (PR #25)
@var array<string, Specification> plus @import-type Specification from AbstractSql	fails, invalid-import-type: the alias does not exist at ed4a407	passes
expanded literal array<string, string|array<string, list<array<int|string, string>|null>>>	fails: the parent at ed4a407 is string[]|array[]	passes
no @var (this PR)	passes	passes

Removing the override is the only form that is green before and after the lock bump.

Gates

Run locally with mago 1.59.0 on PHP 8.5.12, against the committed lock (ed4a407):

• mago format --check: pass
• mago lint: pass
• mago analyze: pass, 0 errors (4 warnings and 4 help messages, all pre-existing)
• mago guard: pass
• unit suite: OK (70 tests, 141 assertions)
• integration suite: 29 of 30 pass. SchemaFactoryIntegrationTest::itCreatesPrefixedTableOnPgsql errors with could not find driver, because pdo_pgsql is not installed in this environment. Unrelated to this change.

With vendor/php-db/phpdb swapped to 1570a612, the incompatible-property-type findings for this class are gone.

Out of scope

The same analyze run at 1570a612 reports 11 further errors that this change does not touch:

• unhandled-thrown-type (PhpDb\Sql\Exception\RuntimeException) in InitDbCommand::executeDdl, DbSessionHandler::{destroy,gc,read,write} and PhpDbSessionPersistence::{initializeSessionFromRequest,persistSession,destroy}
• possible-method-access-on-null in DbSessionHandler lines 98 and 121, and PhpDbSessionPersistence line 134

Those appear only because the newer phpdb declares that exception and narrows the affected return types. They are a separate defect exposed by the same lock refresh, and PR #25 will stay red on mago analyze until they are fixed.

Also at 1570a612, the single analysis-baseline.toml entry (a vendor uninitialized-property in PhpDb\TableGateway\Feature\AbstractFeature) no longer matches, so mago reports it as outdated. That baseline is left untouched here.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!