Repository navigation
Description
Context
Principle 3 promises optional interface collaborators with built-in defaults and no configuration for the default path. src/Infrastructure/Injector/SimpleInjector.php:387-420 instead autowires every non-builtin ReflectionNamedType through make_dependency(), including nullable interface parameters with a default. Only name-based resolution consults defaults. An unbound optional interface therefore fails in ensure_is_instantiable() rather than letting the constructor choose its default.
#27 exposed this for optional DebugMode in view factories; the root now binds it explicitly. That binding works around the issue but does not settle the injector policy. #145 originally depended on this issue for an optional injected ViewContext; its revised ruling passes presenters with each render instead (#173), so it no longer waits on this contract.
Current bounded reproduction
At main 1133d65a07f285dcf1a0fa2f9d0d7fc7d36385b4, a no-WordPress/no-vendor probe defines an unbound interface and a consumer taking ?OptionalProbeCollaborator $collaborator = null. Direct construction uses null. SimpleInjector::make(Consumer::class) instead throws FailedToMakeInstance for the unbound interface. Command: docker run --rm -v /tmp/scaffold-triage-pass9:/probe -w /probe s67-php83 php -n repro149.php (PHP 8.3.36). Expected under principle 3's default promise: direct and injected construction can both use the constructor default; actual injected construction fails. No project code changed.
Fresh bounded check on 15cac4c237fcf10841e5da65b9ae31ad983c0a99, host PHP 8.5.12: php -n /tmp/basic-scaffold-triage.E7l5Qh/repro149.php loads the archived commit through the bundled autoloader, with no vendor or WordPress. Expected default use in both paths; actual direct default: yes, followed by FailedToMakeInstance for OptionalProbeCollaborator on injection. This confirms the existing failure; supported-version regression coverage remains future implementation work.
Scope
Settle and implement/document the optional collaborator resolution contract. Cover when a declared default is used versus explicit binding, delegation or sharing, and distinguish absence of a resolution from a failure inside a configured collaborator. Do not catch every construction failure and silently substitute a default.
Out of scope
PHP 8-only reflection/syntax, unrelated injector rewrites, silently masking broken explicit configuration, or removing the scaffold's analysis gates.
Maintainer decision needed
Should an unbound optional interface use its declared default, with explicit resolution configuration still taking precedence, or should injector-built classes always require a binding and principle 3/documentation be revised accordingly? Specify the precedence/compatibility matrix for defaulted interface and concrete-class parameters, non-defaulted parameters, explicit make/bound arguments, bindings, delegations and shared instances. The code cannot select that policy by itself.
Recommendation, not approval: preserve the default promise for an unconfigured optional collaborator, while propagating failures from explicitly configured construction. Decide how that is identified without inventing a new mandatory inspection contract on custom Injector implementations.
Acceptance criteria once ruled
- The body states the precedence matrix and explicit compatibility ruling before implementation.
- Tests cover the reproduced unbound optional interface, required interfaces, optional concrete types and explicit binding/delegate/share cases under that matrix.
- A collaborator whose configured construction throws still reports the real failure; no blanket catch-and-fallback path.
- Direct construction and injector construction are documented consistently; explicit custom implementations remain configurable.
- Existing supported custom injector APIs and PHP 7.4 compatibility remain intact; any changed inherited signature needs its own ruling.
Verification
Regression tests fail before and pass after the selected behaviour change; run composer test and composer lint in the supported environments. The bounded probe above verifies the current bug, not the full future matrix.
Impact on generated plugins
Potentially breaking resolution/default/error behaviour, even if signatures stay unchanged. Record the migration once the policy is selected; a documentation-only alternative changes a published principle instead and also needs a ruling.
Priority p2: reproducible mismatch with an advertised construction default. Keep needs: decision and breaking; no implementation policy approved by triage.
Updated 2026-10-23: Confirmed direct default versus injected failure on current main/PHP 8.3; completed scope and precedence/compatibility questions. Added p2, breaking and needs: decision rather than choosing a fallback policy.
Updated 2026-10-24: Reconciled #145’s ViewContext naming and maintainer choice to wait for this contract/implementation, without a temporary default-workaround binding. The optional-resolution policy and precedence matrix below still need their own ruling.
Updated 2026-10-24: #145's revised ruling (presenters passed per render, #173) removed its dependency on this issue; dropped the #145 acceptance criterion.
Updated 2026-10-24: Reproduced direct-default success versus injected unresolved-interface failure at 15cac4c with php -n. The optional-resolution precedence/error matrix still needs a maintainer ruling; kept needs: decision and breaking. Reviewed origin/main 15cac4c2.
Activity
schlessera commentedon Oct 23, 2026
Triage (2026-10-23): Confirmed direct default versus injected failure on current main/PHP 8.3; completed scope and precedence/compatibility questions. Added p2, breaking and needs: decision rather than choosing a fallback policy.
schlessera commentedon Oct 23, 2026
Decision dependency update (2026-10-24): #145 now uses ViewContext/domain presentation contracts and is explicitly blocked here by maintainer choice. It must not need a temporary binding solely to work around optional defaults. Updated the reference/criteria; this does not itself approve the full precedence/error matrix on #149.
schlessera commentedon Oct 24, 2026
Triage (2026-10-24): Reproduced direct-default success versus injected unresolved-interface failure at 15cac4c with php -n. The optional-resolution precedence/error matrix still needs a maintainer ruling; kept needs: decision and breaking.