Repository navigation
chore(reflection): mark every raw-CData accessor @internal - #308
Merged
Merged
Conversation
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
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.
What this changes
Fixes #194. Applies one rule across
src/Typeandsrc/Reflection: a public method that returns a rawFFI\CData/FFI\CType, or a generated struct stub view, carries@internal. A class marked@internalas a whole (StructArray,FunctionLikeInterface) covers its methods. Docblock and tooling changes only, no runtime change.@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().@internalin the first block was silently lost. This hitReflectionClass::getRawValue(), which the issue counted as marked, plusFunctionLikeTrait::getEntryPointer(),ReflectionMethod::fromRawEntry()/fromClosureEntry()andObjectEntry::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).tools/phpstan/RawEngineAccessorRule.php(registered inphpstan.dist.neon) reports any public raw-CData accessor inZEngine\Type/ZEngine\Reflectionthat isn't@internal. Because it reads the same docblock PHPStan does, it also catches the stacked-docblock case.getRawValue()returns the owned struct,getRaw<Thing>()a struct reached through it, andget<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()andAbstractModule::getGlobals()stay public and unmarked for now; both files are identical to the base branch. The rule exemptsReflectionExtension::getGlobals()with aTODO(#192)(AbstractModuleis outside the namespaces the rule checks).Left alone: one more stacked docblock in
ClassSpecializer(aboveassertReturnTypeIsEnforceable(), a private method). Its original owner is unclear and it has nothing to do with@internal.Environment it was verified on
Checks run locally:
php -lon every changed file, plus a token scanner confirming that no public raw-CData accessor insrc/Type/src/Reflectionis left unmarked (the exemptReflectionExtension::getGlobals()aside) and no stacked docblocks remain there apart from theClassSpecializerone above. The sandbox's network policy blocked Composer's GitHub downloads, socomposer phpstanandcomposer cs:checkwere not run locally. CI is the first real run of the new PHPStan rule.Checklist
8.4). It cascades to 8.5/master through merge-upcomposer testpasses on the matching PHP minor (not run, see above; docblock-only change)composer phpstan(level max) andcomposer cs:checkare green (left to CI)src; no PHPUnit test, same as the existingTypedEntryPointReturnExtension)tools/generator/symbols.phpunchanged; nothing generated was hand-edited🤖 Generated with Claude Code
https://claude.ai/code/session_01FxhC1ER6GtpZr8k2beJQqx