Repository navigation
Mago compliance: settle the API decisions behind remaining src analyzer issues - #255
Open
simon-mundy wants to merge 9 commits into
Open
simon-mundy wants to merge 9 commits into
simon-mundy wants to merge 9 commits into
Conversation
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 Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
This was referenced Nov 17, 2026
There was a problem hiding this comment.
🟡 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
ParameterContainerargument names withArrayAccess. - 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
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.

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
getHelpers(): arrayandgetResource(): mixed.Pdo\Result. Its properties are typed andnext()returnsvoid.Pdo\Result::initializeis registered as a class initializer inmago.toml.Profiler. The$profilesand$currentIndexproperties are typed.AbstractPdo::getResultPrototype(): ResultInterface. This is no longer nullable. With no prototype set, it throwsRuntimeException::forMissingResultPrototype()instead of returningnull.ParameterContainer. ItsArrayAccessparameters are renamed to$offset, matching the interface.@api. Classes meant for extension are tagged@apirather than madefinal.AbstractAdapterInterfaceFactory::__invoke(ContainerInterface $container). This now accepts the container type thatFactoryInterfacedeclares. A container that cannot build services throwsContainerException::forNonBuildingContainer().AbstractConnection::$resource. Nowprotected mixed $resource = null, andAbstractPdoConnectionno longer redeclares it.AbstractResultSet::getFieldCount(). The(array)cast of amixedrow is gone. Each kind of row is counted explicitly, and every result is the same as the cast gave:Countablerow: itscount();null: 0;Backward compatibility
getHelpers(),getResource()orPdo\Result::next()must declare the matching return type.$resourcemust declare it asmixedor drop the redeclaration. Otherwise PHP raises a fatal error, because property types are invariant.ParameterContainer'soffset*()methods that use named arguments need the new$offsetname.getResultPrototype()returningnullnow gets an exception.Not in this PR
Driver follow-ups (after merge)
$resourcewithout a type insrc/Connection.php:39. Change it tomixedor remove it.$this->resourcewithinstanceof PDOinPdo\Connectionso that Mago passes.Verification
srclines are covered. Infection finds no escaped mutants inAbstractResultSet.