Skip to content

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

Description

@lisachenko

Problem

AGENTS.md defines the off-limits surface for packages built on z-engine as "every method marked @internal and anything handing out a raw FFI\CData/FFI\CType". The marking is applied inconsistently:

Marked @internal: HashTable::getRawValue(), ReflectionClass::getRawValue(), ObjectEntry::getPropertyTablePointer() / getDynamicPropertiesPointer().

Not marked (but hand out raw CData/pointers):

  • StringEntry::getRawValue() (src/Type/StringEntry.php:185)
  • ObjectEntry::getRawValue() (src/Type/ObjectEntry.php:325)
  • ReflectionValue::getRawValue() (src/Reflection/ReflectionValue.php:562)
  • ReflectionClassConstant::getRawValue() (src/Reflection/ReflectionClassConstant.php:119)
  • ClosureEntry::getRawFunction() (src/Type/ClosureEntry.php:155)
  • ResourceEntry::getRawData() (src/Type/ResourceEntry.php:123)
  • OpLine::getHandler() (src/Type/OpLine.php:109)
  • ReflectionExtension::getGlobals() (src/Reflection/ReflectionExtension.php:117) — fully public, returns bare \FFI\CData, no marker at all

Related naming scatter for the same concept: getRawValue() / getRawData() / getRawFunction() / getEntryPointer() / getPropertyTablePointer().

Proposal

Pick one rule (suggest: every method returning raw CData/CType carries @internal), apply it across src/Type and src/Reflection, and note the naming convention for future accessors in AGENTS.md. Depends on the API-contract decision in the companion README/AGENTS issue only for ReflectionExtension::getGlobals().

Found during the 2026-08 modernization review.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions