Skip to content

Partial reflection of classes whose ancestors can not be located - #252

Merged
lisachenko merged 2 commits into
4.xfrom
feature/friendly-cori-zyci9y
Nov 2, 2026
Merged

lisachenko merged 2 commits into
4.xfrom
feature/friendly-cori-zyci9y

Conversation

@lisachenko

@lisachenko lisachenko commented Nov 2, 2026 •

Copy link
Copy Markdown
Member

Closes #251.

Problem

Reflecting a class needs its parent class, interfaces and traits. When the locator can't find one of them (generated at runtime, declared by class_alias(), outside the Composer autoloader), every method that touches the hierarchy throws, so the class can't be reflected at all, even for its own methods.

Change

A policy on the engine decides what happens to a missing ancestor:

ReflectionEngine::setMissingAncestorPolicy(MissingAncestorPolicy::Partial);
// or ReflectionEngine::init($locator, null, MissingAncestorPolicy::Partial);

$class = new ReflectionClass(SomeClass::class);
if ($class->isPartial()) {
    $class->getMissingClassNames(); // e.g. ['GeneratedCode\Admin\BaseReportController']
}
$class->getMethods(); // own methods + the ones of the available ancestors
  • MissingAncestorPolicy::Strict (default): same behaviour as before. The exception is now a ClassNotFoundException, which extends InvalidArgumentException and keeps the same message, so existing catch blocks still work.
  • MissingAncestorPolicy::Partial: missing ancestors are left out. getParentClass() returns false for a missing parent. Missing interfaces and traits are left out of getInterfaces()/getInterfaceNames()/getTraits()/getTraitNames(), along with the members inherited from them. A prototype that would come from a missing ancestor is not reported. isSubclassOf() still recognises ancestors the class declares directly, because those are in its source. The names as written stay available on getNode().
  • isPartial() / getMissingClassNames() on ReflectionClass and ReflectionEnum: they include ancestors missing further up the hierarchy (e.g. a missing grandparent) and never throw, under either policy. A strict-mode user can call them to check a class before reflecting it.
  • A class that can't be located itself still throws under both policies. The policy only covers its ancestors.

Implementation notes

  • All ancestor reflections go through a new ReflectionClass::reflectAncestor(). It is used by collectInterfacesFromClassNode(), collectTraitsFromClassNode() and getParentClass(). It reflects an ancestor that is already declared (class, interface or trait) natively and parses the others. The duplicated createReflectionForClass() was removed from the trait and from ReflectionClass; both classes are final.
  • Partial mode only catches ClassNotFoundException, i.e. the locator returned nothing. Other failures, such as a located file that doesn't declare the class, still throw.

Tests

  • New tests/PartialReflectionTest.php with the stub tests/Stub/FileWithMissingAncestors.php. The stub is only parsed, never included. The tests cover: the default policy, the init() argument and the setter, strict-mode throwing, own members, attributes and constants in partial mode, omitted ancestors, prototypes, __toString(), a missing grandparent reported through the parent, an interface extending a missing interface, a class with no missing ancestors under both policies, the ReflectionFile route, and a class that is itself missing.
  • Targets 4.x so the feature is available in both major versions. CI is green on PHP 8.4 and 8.5 with lowest and highest dependencies, and on the experimental PHP 8.6 jobs. PHPStan (level 10) passes.

Docs

The README has a new "Classes whose ancestors can not be located" section, and docs/reflection_class.md and CLAUDE.md are updated.

Follow-up

goaop/framework can opt in with ReflectionEngine::setMissingAncestorPolicy(MissingAncestorPolicy::Partial) once this is released, and then decide what to do with isPartial() classes (weave their own methods, or skip them with a clear message).

🤖 Generated with Claude Code

https://claude.ai/code/session_01FxhC1CBg4rnTu9UjAMcCpL

@lisachenko
lisachenko marked this pull request as ready for review November 2, 2026 21:33
@lisachenko
lisachenko changed the base branch from master to 4.x November 2, 2026 21:34
@lisachenko

Copy link
Copy Markdown
Member Author

@claude could you please rebase, so PR will be for 4.x branch by default - I want to have this feature for both major versions

Reflecting a class requires its parent class, interfaces and traits. When the
locator could not find one of them, every method that needs it threw, so the
class could not be reflected at all, even for its own methods.

ReflectionEngine now takes a MissingAncestorPolicy (via init() or
setMissingAncestorPolicy()):
- Strict (default): the current behaviour, a ClassNotFoundException (which
  extends InvalidArgumentException) is thrown;
- Partial: missing ancestors are left out, and the reflection covers what the
  class and its available ancestors declare.

ReflectionClass and ReflectionEnum gain isPartial() and getMissingClassNames(),
which report missing ancestors transitively and never throw, whatever the
policy. All ancestor reflections now go through ReflectionClass::reflectAncestor().

Closes #251

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxhC1CBg4rnTu9UjAMcCpL
Passing the result of class_exists() and alike as a bool lost the narrowing of
the ancestor name to a class-string, so PHPStan rejected the native
reflection of a declared ancestor. The helper now checks it itself, as
ReflectionEngine::locateClassFile() does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxhC1CBg4rnTu9UjAMcCpL
@lisachenko
lisachenko force-pushed the feature/friendly-cori-zyci9y branch from 96c4a0c to 702e4bf Compare November 2, 2026 21:36

Copy link
Copy Markdown
Member Author

Done: the branch is rebased onto 4.x and the PR now targets 4.x. Both commits applied cleanly, because 4.x is fully contained in master. Nothing in the change needs a PHP version newer than 8.3. All 13,763 tests pass on 4.x locally, and CI will run them on PHP 8.4 and 8.5. Once this is merged, the usual 4.x → master merge will bring the feature to master.


Generated by Claude Code

@lisachenko
lisachenko merged commit e25ae95 into 4.x Nov 2, 2026
14 checks passed
@lisachenko
lisachenko deleted the feature/friendly-cori-zyci9y branch November 2, 2026 21:45
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

Partial reflection: reflect a class whose ancestors are not available instead of throwing

2 participants