Skip to content

Clear the non-BC Mago findings in Container, Adapter and ResultSet - #253

Open
simon-mundy wants to merge 2 commits into
php-db:0.6.xfrom
simon-mundy:qa/mago-src-types
Open

simon-mundy wants to merge 2 commits into
php-db:0.6.xfrom
simon-mundy:qa/mago-src-types

Conversation

@simon-mundy

Copy link
Copy Markdown
Member

Problem

About 55 Mago findings in src/Container, src/ConfigProvider.php, src/Adapter and src/ResultSet sit in the baselines. They cover:

  • missing or imprecise types;
  • mixed values;
  • nullable array access;
  • container exceptions that aren't declared with @throws;
  • redundant docblocks;
  • isset() / empty() use.

Fix

  • Types: precise docblock types for the container config arrays, the factory options, __set_state()'s state and the ConfigProvider arrays.
  • Exceptions: @throws for the container exceptions each factory and canCreate() can raise.
  • Docblocks: redundant @var docblocks are removed from built services and result-set rows. One of them was wrong (ResultSetInterface|null).
  • canCreate() uses an equivalent is_array() / [] !== check instead of isset() / empty().
  • The abstract factory reads the named adapter config once, null-safe.
  • RowPrototypeResultSet::toArray() iterates through its nullable current(). The analyzer flagged the old instanceof check as redundant, but null rows really do occur, so the null-row passthrough is now typed instead.
  • AdapterInterfaceFactory reports a missing driver with ContainerException::forMissingDriver(), as the abstract factory already does, instead of a TypeError from ServiceManager::build().
  • Baselines: the analyzer baseline goes from 284 to 244 issues, and the lint baseline from 153 to 151.

What stays the same

  • No public or protected signature changes.
  • No native types added to non-final classes or interfaces.
  • Findings that need a BC change stay baselined, for a separate decision:
    • native property and return types on @api classes and interfaces;
    • AbstractPdo::getResultPrototype()'s nullability.
  • Class-design and complexity findings also stay baselined.
  • Behaviour is unchanged apart from the missing-driver exception.

Verification

  • mago format --check, lint, analyze and guard exit 0 on PHP 8.3, 8.4 and 8.5.
  • The full PHPUnit suite passes.
  • Every changed src line is covered.
  • Infection finds no escaped mutants on changed lines.
  • New tests cover:
    • the configs canCreate() rejects;
    • which config key the adapter is read from first;
    • the missing driver;
    • null rows in toArray().

Give the config arrays and factory options precise docblock types,
document the container exceptions each factory can raise, drop the
redundant @var casts on built services, replace isset/empty in
canCreate() with an equivalent is_array check, and mark the unused
delegator $options parameter as expected.

AdapterInterfaceFactory now throws ContainerException::forMissingDriver()
when the adapter configuration has no driver, matching the abstract
factory, instead of passing null to ServiceManager::build() and failing
with a TypeError.

Remove the baseline entries these changes clear.
Mark the rows read for field counting as mixed, drop the @var object
casts the analyzer already infers in toArray(), and have
RowPrototypeResultSet::toArray() iterate through current(), whose
nullable return type makes the null-row passthrough explicit rather
than a redundant instanceof check. Document the exceptions that
iteration can raise.

Remove the baseline entries these changes clear.
@codecov

codecov Bot commented Nov 17, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review findings block the adapter configuration and result-set updates.

No open issues 🎉

What changed in this PR

This PR reduces Mago findings in adapter container wiring and result sets without changing public or protected signatures. It improves type annotations and exception documentation, while introducing a specific exception for missing driver configuration.

Changes:

  • Refines configuration types and exception declarations, and removes redundant docblocks.
  • Simplifies adapter configuration checks and preserves null rows during result-set conversion.
  • Adds regression tests and removes resolved analyzer and lint baseline entries.
File Description
test/​unit/​ResultSet/​RowPrototypeResultSetTest.php Tests null-row preservation in toArray().
test/​unit/​Container/​AdapterInterfaceFactoryTest.php Tests configuration-key precedence and missing drivers.
test/​unit/​Adapter/​Container/​AbstractAdapterInterfaceFactoryTest.php Tests accepted and rejected named-adapter configurations.
src/​ResultSet/​RowPrototypeResultSet.php Uses nullable current() for row conversion and documents exceptions.
src/​ResultSet/​ObjectResultSet.php Removes a redundant row annotation.
src/​ResultSet/​HydratingResultSet.php Removes a redundant row annotation.
src/​ResultSet/​AbstractResultSet.php Explicitly annotates mixed source values.
src/​Container/​AdapterInterfaceFactory.php Refines annotations and throws a specific missing-driver exception.
src/​Container/​AdapterInterfaceDelegator.php Documents option and state types and annotates mixed values.
src/​Container/​AbstractAdapterInterfaceFactory.php Simplifies configuration access and improves type and exception documentation.
src/​ConfigProvider.php Documents dependency-array shapes.
lint-baseline.toml Removes resolved isset() and empty() findings.
analyzer-baseline.toml Removes resolved analysis findings.

Review effort: Balanced

@simon-mundy simon-mundy added qa Improvements in quality assurance of the project Lang Feature Refactor Refactoring to new language features labels Nov 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Lang Feature Refactor Refactoring to new language features qa Improvements in quality assurance of the project

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants