Skip to content

Mago compliance: settle the API decisions behind remaining src analyzer issues - #255

Open
simon-mundy wants to merge 9 commits into
php-db:0.6.xfrom
simon-mundy:qa/mago-api-decisions
Open

simon-mundy wants to merge 9 commits into
php-db:0.6.xfrom
simon-mundy:qa/mago-api-decisions

Conversation

@simon-mundy

Copy link
Copy Markdown
Member

Mago compliance, part 3 of 12: the analyzer issues that needed an API decision rather than a mechanical fix. Each commit settles one decision. The analyzer baseline goes from 197 entries to 170 and the lint baseline is unchanged.

Changes

  • Native return types. getHelpers(): array and getResource(): mixed.
  • Pdo\Result. Its properties are typed and next() returns void. Pdo\Result::initialize is registered as a class initializer in mago.toml.
  • Profiler. The $profiles and $currentIndex properties are typed.
  • AbstractPdo::getResultPrototype(): ResultInterface. This is no longer nullable. With no prototype set, it throws RuntimeException::forMissingResultPrototype() instead of returning null.
  • ParameterContainer. Its ArrayAccess parameters are renamed to $offset, matching the interface.
  • @api. Classes meant for extension are tagged @api rather than made final.
  • AbstractAdapterInterfaceFactory::__invoke(ContainerInterface $container). This now accepts the container type that FactoryInterface declares. A container that cannot build services throws ContainerException::forNonBuildingContainer().
  • AbstractConnection::$resource. Now protected mixed $resource = null, and AbstractPdoConnection no longer redeclares it.
  • AbstractResultSet::getFieldCount(). The (array) cast of a mixed row is gone. Each kind of row is counted explicitly, and every result is the same as the cast gave:
    • a Countable row: its count();
    • an array: its length;
    • an object: all of its properties, including non-public ones;
    • null: 0;
    • a scalar: 1.

Backward compatibility

  • Subclasses that override getHelpers(), getResource() or Pdo\Result::next() must declare the matching return type.
  • Subclasses that redeclare $resource must declare it as mixed or drop the redeclaration. Otherwise PHP raises a fatal error, because property types are invariant.
  • Callers of ParameterContainer's offset*() methods that use named arguments need the new $offset name.
  • Code that relied on getResultPrototype() returning null now gets an exception.

Not in this PR

Driver follow-ups (after merge)

  • phpdb-mysql and phpdb-pgsql. Both redeclare $resource without a type in src/Connection.php:39. Change it to mixed or remove it.
  • All three drivers. Narrow $this->resource with instanceof PDO in Pdo\Connection so that Mago passes.

Verification

AdapterInterface::getHelpers() now returns array, and ConnectionInterface::getResource()
and StatementInterface::getResource() return mixed, which every implementer must now
declare.

AbstractConnection::$resource is typed mixed with a null default: a native extension may
still hand back a resource, which has no declarable type. Property types are invariant, so
AbstractPdoConnection no longer redeclares the property to narrow it to PDO; it already
narrows the handle where it reads it.
The seven untyped properties are now natively typed, and initialize() declares
string|int|false|null for the generated value. $resource is a non-nullable PDOStatement
set by initialize(), which mago now treats as the class initializer.

next() matches Iterator::next() and no longer returns the fetched row; read it with
current(). No caller in the package used the returned row.
The prototype is set by the concrete driver, normally in its constructor. A driver that
never sets it now gets RuntimeException::forMissingResultPrototype() instead of an
uninitialised-property Error.
offsetExists(), offsetGet(), offsetSet() and offsetUnset() now name their first parameter
$offset, as ArrayAccess does, so a named argument works whether the container is typed as
ParameterContainer or as ArrayAccess. A caller passing name: must pass offset: instead.
ResultSet\Exception\RuntimeException, ResultSet\Exception\InvalidArgumentException,
Container\AdapterInterfaceDelegator and Sql\Platform\Platform stay open for extension and
are marked as public API, as the Adapter classes were in php-db#248.
AbstractAdapterInterfaceFactory::__invoke() now declares ContainerInterface, as
FactoryInterface does, in place of ContainerInterface|ServiceManager and a docblock
intersection with ServiceManager. It builds the adapter's dependencies with
ServiceManager::build(), so any other container is refused with
ContainerException::forNonBuildingContainer() instead of failing on an undefined method.
getFieldCount() cast the first row with (array), which the analyzer
reports as an invalid cast from mixed. It now counts each kind of row
explicitly, with the same results the cast gave: a Countable row by
count(), an array by its length, an object through
get_mangled_object_vars() (non-public properties included, as the cast
counted them), null as 0 and any scalar as 1.
@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.

🟡 Changes recommended

The public contract documentation misrepresents fallback counting behavior, claims a nonexistent exception, and implies consistency with ObjectResultSet::toArray() that is not guaranteed.

1 open issue
What changed in this PR

This PR settles API decisions needed for Mago compliance across adapters, PDO results, containers, and result sets. It introduces explicit types and failure behavior while keeping designated extension points open.

Changes:

  • Adds native return and property types, and aligns ParameterContainer argument names with ArrayAccess.
  • Adds exceptions for missing result prototypes and unsupported containers, and replaces mixed-row casts with explicit field counting.
  • Marks extensible classes with @api, adds regression coverage, and removes resolved baseline entries.
File Description
test/​unit/​ResultSet/​AbstractResultSetTest.php Tests field counts for object, scalar, and null rows.
test/​unit/​Exception/​ContainerExceptionTest.php Tests the unsupported-container exception message.
test/​unit/​Adapter/​ParameterContainerTest.php Tests named offset arguments.
test/​unit/​Adapter/​Exception/​RuntimeExceptionTest.php Covers the missing-result-prototype exception.
test/​unit/​Adapter/​Driver/​Pdo/​ResultTest.php Tests generated-value types and iterator advancement.
test/​unit/​Adapter/​Driver/​Pdo/​PdoTest.php Tests failure when no result prototype is set.
test/​unit/​Adapter/​Container/​AbstractAdapterInterfaceFactoryTest.php Tests rejection of containers without dependency-building support.
src/​Sql/​Platform/​Platform.php Adds an @api annotation.
src/​ResultSet/​Exception/​RuntimeException.php Adds an @api annotation.
src/​ResultSet/​Exception/​InvalidArgumentException.php Adds an @api annotation.
src/​ResultSet/​AbstractResultSet.php Replaces row casts with explicit field-count branches.
src/​Exception/​ContainerException.php Adds the unsupported-container exception constructor.
src/​Container/​AdapterInterfaceDelegator.php Adds an @api annotation.
src/​Container/​AbstractAdapterInterfaceFactory.php Accepts ContainerInterface and checks building capability.
src/​Adapter/​Profiler/​Profiler.php Types profile storage and the current index.
src/​Adapter/​ParameterContainer.php Renames ArrayAccess parameters to offset.
src/​Adapter/​Exception/​RuntimeException.php Adds the missing-result-prototype exception constructor.
src/​Adapter/​Driver/​StatementInterface.php Declares a mixed resource return type.
src/​Adapter/​Driver/​Pdo/​Result.php Types result state and initialization; makes next() void.
src/​Adapter/​Driver/​Pdo/​AbstractPdoConnection.php Removes the inherited resource property's redeclaration.
src/​Adapter/​Driver/​Pdo/​AbstractPdo.php Returns a non-null prototype or throws.
src/​Adapter/​Driver/​ConnectionInterface.php Declares a mixed resource return type.
src/​Adapter/​Driver/​AbstractConnection.php Types the shared resource property and accessor.
src/​Adapter/​AdapterInterface.php Types the helper-list return contract.
src/​Adapter/​Adapter.php Adds the matching helper return type.
mago.toml Registers PDO result initialization with Mago.
lint-baseline.toml Reduces the result-set complexity suppression count.
analyzer-baseline.toml Removes resolved analyzer entries.

Review effort: Balanced

Comment thread src/ResultSet/AbstractResultSet.php Resolved
The docblock still described an earlier version: it said objects were
counted by their public properties and that scalar or null rows threw
UnexpectedValueException. The method counts every property of an
object, null as 0 and any other scalar as 1, the same as the (array)
cast it replaced, and throws no UnexpectedValueException.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants