Widen ConnectionInterface::getResource() to resource|object|null

[tyrsson]

What

ConnectionInterface::getResource() declares @return resource, but no implementation can honour it. AbstractConnection::getResource() is annotated @return resource|null, and AbstractConnection::disconnect() assigns $this->resource = null, so null is a legitimate and reachable return value. The interface's @return resource was simply wrong about its own contract, and the mismatch was already live on 0.6.x.

Two changes:

1. ConnectionInterface::getResource() -> @return resource|object|null.
   Returns are covariant, so widening the interface legalises the narrower @return resource|null already declared by AbstractConnection and Pdo\AbstractPdoConnection. The object arm is required because mysqli has been an object since PHP 8.1 -- the mysqli driver's connection is not a resource.
2. AbstractConnection::$resource -- drop the @var mixed docblock.
   It was redundant (mixed is the implicit type) and actively harmful: it forced subclasses that declare their real type to be reported as incompatible-property-type. The prose "Extending classes must be covariant" is kept as a comment.

No native types are added, so runtime behaviour is unchanged.

Effect on the baseline

Baselines are generated by mago, never hand-edited -- these were pruned with mago analyze --remove-outdated-baseline-entries. analyzer-baseline.toml goes 716 -> 713 blocks; lint-baseline.toml is unchanged.

Three findings are un-suppressed because they no longer exist:

File	Code	Was
src/Adapter/Driver/AbstractConnection.php	incompatible-return-type	null|resource vs parent resource
src/Adapter/Driver/AbstractConnection.php	incompatible-return-type	same, for Pdo\AbstractPdoConnection::getresource()
src/Adapter/Driver/Pdo/AbstractPdoConnection.php	incompatible-property-type	$resource docblock incompatible with parent

Nothing else was dropped -- verified by diffing the baseline before and after.

missing-property-type and mixed-return-statement on AbstractConnection::$resource deliberately remain: the property is genuinely still untyped, and giving it a real shape is a separate decision.

Gates

mago format --check, mago lint and mago analyze are all clean (no guard config in this repo). vendor/bin/phpunit --testsuite "unit test" -- 2089 tests, 4038 assertions, OK.

Consumer verification

Verified against phpdb-mysql by temporarily aliasing this clone in as a Composer path repository (junction + mago path), then reverting the scaffolding. Measured A/B against the same phpdb commit so the delta could not confound the result:

• 0 new findings in phpdb-mysql.
• Exactly 3 of phpdb-mysql's baselined entries become outdated -- the inherited $resource contract findings this change clears.
• phpdb-mysql's 193 unit tests pass against this branch.

A fourth phpdb-mysql entry (SelectDecorator::$specifications) is also reported as outdated when resolved against the current 0.6.x tip, but it is unrelated to this change and is not pruned here.

Follow-up

phpdb-mysql's composer.lock still pins b57f549, which is 270 commits behind 0.6.x. Its CI mago job installs from that lock, so the phpdb-mysql side of this contract change will be pruned once that lock is synced.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!