[simon-mundy]

Types of changes

• Documentation improvement
• New feature (non-breaking change which adds functionality)
• QA improvement (unit/integration tests, CS fixes, etc.) that does not change code behavior

Checklist:

• An issue has been created for this pull request.
• I have added tests for my changes.
• All new and existing tests passed.
• Documentation has been updated accordingly.
• This pull request targets the correct branch.

Description

PR 6 of 6 from #189, and the last: the throw sites outside the components #191 to #194 cover.

Stacked on #190. GitHub cannot base a cross-fork PR on a fork branch, so this targets 0.6.x and shows both commits. Only the second, 2f46c04e, belongs to this PR. Merge #190 first; I will rebase after. It does not depend on #191, #192, #193 or #194.

Message text is byte-identical, verified template by template against the original literals.

• ResultSet\Exception\RuntimeException::forUnbufferedIteration().
• ContainerException::forNonAdapterAwareDelegate(), plus factories for the three reasons that AdapterInterfaceFactory and AbstractAdapterInterfaceFactory were passing to forService() as inline strings: forMissingConfigService(), forMissingConfiguration() and forMissingDriver(). Each composes the reason into the SERVICE template, so the composed messages are verified as well as the templates.
• The delegator's non-AdapterAware guard is retyped from the root Exception\RuntimeException to ContainerException, which extends it. A container failure should carry PSR-11's ContainerExceptionInterface, and nothing catching the old type is affected.

One documented exception to the convention

The delegator's "not found in container" guard must throw the ServiceManager's own ServiceNotFoundException — the container contract decides the type. I first extended that class so the template could live on it, and mago analyze correctly refused: Laminas annotates it @final. It is not final in PHP today, so runtime reflection and the test suite both accepted the subclass, but the annotation is a clear statement of intent and extending it would break when Laminas enforces it.

So this package owns the wording without owning the class: the template is ContainerException::MISSING_SERVICE and that one throw site renders it itself. docs/book/exceptions.md records it as the single place the convention does not apply, and why. Everywhere the thrown type is ours, the rule holds without exception.

Motivation and Context

Refs #189. Depends on #190.

Scope is deliberately limited to what the other PRs do not touch, so this does not conflict with them: ResultSet, Container and Adapter/Container. One literal assertion is left in test/unit/Container/TableIdentifierFactoryFactoryTest.php because it asserts Sql\Exception\InvalidArgumentException::EMPTY_SEPARATOR, a constant #192 introduces — it can be migrated in a follow-up once that lands.

With #191 to #194, this completes the conversion: no throw new remains anywhere in src/.

How has this been tested?

mago format --check, mago lint and mago analyze all exit 0. Full unit suite passes: 1630 tests, 3529 assertions.

Patch coverage measured locally at 16/16 lines, computed the way codecov/patch does, before pushing. #194 failed that check on a method whose test class had never declared it in #[CoversMethod], so coverage was executed but not attributed; this PR was checked against that trap up front.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!