Skip to content

chore(reflection): mark every raw-CData accessor @internal - #308

Merged
lisachenko merged 2 commits into
8.4from
feature/modest-cerf-1277hn
Nov 7, 2026
Merged

lisachenko merged 2 commits into
8.4from
feature/modest-cerf-1277hn

Conversation

@lisachenko

@lisachenko lisachenko commented Nov 7, 2026 •

Copy link
Copy Markdown
Owner

What this changes

Fixes #194. Applies one rule across src/Type and src/Reflection: a public method that returns a raw FFI\CData/FFI\CType, or a generated struct stub view, carries @internal. A class marked @internal as a whole (StructArray, FunctionLikeInterface) covers its methods. Docblock and tooling changes only, no runtime change.

  • Marked @internal (they had no marker): StringEntry/ObjectEntry/ReflectionValue/ReflectionClassConstant::getRawValue(), ReflectionValue::getRaw{Class,Function,String,Array,Object,Resource,Reference,Pointer}(), ClosureEntry::getRawFunction(), ResourceEntry::getRawData(), OpLine::getHandler(), ReflectionClass::newInstanceRaw(), PersistentObjectFactory::persistentClone().
  • Fixed stacked docblocks. Several methods had two docblocks in a row. PHP and PHPStan read only the last one, so the @internal in the first block was silently lost. This hit ReflectionClass::getRawValue(), which the issue counted as marked, plus FunctionLikeTrait::getEntryPointer(), ReflectionMethod::fromRawEntry()/fromClosureEntry() and ObjectEntry::setDynamicPropertiesPointer(). I merged them, and moved the docblocks that had slid up onto the wrong member back to their owners (fromClosureEntry(), dereferenceMapPointerSlot(), STORAGE_CE_FLAGS).
  • Enforced in CI: a new tools/phpstan/RawEngineAccessorRule.php (registered in phpstan.dist.neon) reports any public raw-CData accessor in ZEngine\Type/ZEngine\Reflection that isn't @internal. Because it reads the same docblock PHPStan does, it also catches the stacked-docblock case.
  • AGENTS.md: documents the rule and the naming convention: getRawValue() returns the owned struct, getRaw<Thing>() a struct reached through it, and get<Field>Pointer() a view into one field. Existing names (e.g. getEntryPointer()) stay as they are, so callers don't break.

Not changed (#192): ReflectionExtension::getGlobals() and AbstractModule::getGlobals() stay public and unmarked for now; both files are identical to the base branch. The rule exempts ReflectionExtension::getGlobals() with a TODO(#192) (AbstractModule is outside the namespaces the rule checks).

Left alone: one more stacked docblock in ClassSpecializer (above assertReturnTypeIsEnforceable(), a private method). Its original owner is unclear and it has nothing to do with @internal.

Environment it was verified on

  • PHP version: the sandbox only has PHP 8.5.12 (NTS). This branch targets 8.4, so per AGENTS.md no z-engine code or tests were run.
  • Thread safety: NTS
  • OS / architecture: Linux x64
  • Debug build: no

Checks run locally: php -l on every changed file, plus a token scanner confirming that no public raw-CData accessor in src/Type/src/Reflection is left unmarked (the exempt ReflectionExtension::getGlobals() aside) and no stacked docblocks remain there apart from the ClassSpecializer one above. The sandbox's network policy blocked Composer's GitHub downloads, so composer phpstan and composer cs:check were not run locally. CI is the first real run of the new PHPStan rule.

Checklist

  • Targets the minimum affected version branch (8.4). It cascades to 8.5/master through merge-up
  • composer test passes on the matching PHP minor (not run, see above; docblock-only change)
  • composer phpstan (level max) and composer cs:check are green (left to CI)
  • Tests added or updated (the rule is checked by PHPStan running over src; no PHPUnit test, same as the existing TypedEntryPointReturnExtension)
  • tools/generator/symbols.php unchanged; nothing generated was hand-edited
  • Conventional Commits used for the commit messages

🤖 Generated with Claude Code

https://claude.ai/code/session_01FxhC1ER6GtpZr8k2beJQqx

Apply one rule across src/Type and src/Reflection: a public method that
returns a raw FFI\CData/CType or a generated struct stub view carries
@internal (issue #194).

- Add @internal to the unmarked escape hatches: StringEntry/ObjectEntry/
  ReflectionValue/ReflectionClassConstant::getRawValue(), the
  ReflectionValue::getRaw*() getters, ClosureEntry::getRawFunction(),
  ResourceEntry::getRawData(), OpLine::getHandler(),
  ReflectionExtension::getGlobals(), ReflectionClass::newInstanceRaw()
  and PersistentObjectFactory::persistentClone().
- Merge stacked docblocks. PHP and PHPStan read only the last one, so
  the @internal on ReflectionClass::getRawValue(),
  FunctionLikeTrait::getEntryPointer(), ReflectionMethod::fromRawEntry()
  and ObjectEntry::setDynamicPropertiesPointer() was silently lost. Move
  the displaced docblocks of ReflectionMethod::fromClosureEntry(),
  dereferenceMapPointerSlot() and STORAGE_CE_FLAGS back to their owners.
- Add RawEngineAccessorRule (tools/phpstan) so PHPStan enforces the rule.
- Document the rule and the accessor naming convention in AGENTS.md.

AbstractModule::getGlobals() is left as is: whether that consumer-facing
override may return CData is decided in #192.

Closes #194

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxhC1ER6GtpZr8k2beJQqx
…#192

AbstractModule::getGlobals() exposes the module globals through this
method, and that API contract is decided in #192. Drop its @internal
marker again and exempt it in RawEngineAccessorRule with a TODO(#192).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FxhC1ER6GtpZr8k2beJQqx
@lisachenko
lisachenko marked this pull request as ready for review November 7, 2026 12:00
@lisachenko
lisachenko merged commit 0dae3a6 into 8.4 Nov 7, 2026
21 checks passed
@lisachenko
lisachenko deleted the feature/modest-cerf-1277hn branch November 7, 2026 12:00
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.

chore: @internal marking on CData escape hatches is inconsistent across the core layer

2 participants