diff --git a/AGENTS.md b/AGENTS.md index 3e5143b4..73a79d8b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -271,6 +271,25 @@ line, the fix is a named public method here, not a reach-through there: class-ta eviction became `ClassSpecializer::evict()` and `sizeof(type(...))` became `Core::sizeOfType()` for exactly that reason. +**Every raw accessor carries `@internal`.** A public method that returns a raw +`FFI\CData`/`FFI\CType`, or a generated stub view (a CData handle at run time), is marked +`@internal` in the docblock right above it. Keep one docblock per method: PHP and PHPStan +read only the last one, so an `@internal` in an earlier, stacked block is lost. A class +marked `@internal` as a whole (`StructArray`, `FunctionLikeInterface`) covers its methods. +`tools/phpstan/RawEngineAccessorRule.php` enforces this for `ZEngine\Type` and +`ZEngine\Reflection`. Name a new accessor by what it hands out: + +- `getRawValue()`: the struct the wrapper owns (`StringEntry`, `ObjectEntry`, `HashTable`, + `ReflectionClass`, `ReflectionValue`, ...). +- `getRaw()`: a struct reached through the owned one + (`ReflectionValue::getRawString()`, `ClosureEntry::getRawFunction()`, + `ResourceEntry::getRawData()`). +- `getPointer()`: a view into one field or embedded part of the owned struct + (`ObjectEntry::getPropertyTablePointer()`, `getOpArrayPointer()`). + +`FunctionLikeInterface::getEntryPointer()` is older than this convention (by it, the name +would be `getRawValue()`); existing names stay as they are, so callers do not break. + ## Engine structs are owned by their reflection/type class, never poked from call sites This applies to EVERY class: if a class is responsible for a structure, then all external diff --git a/phpstan.dist.neon b/phpstan.dist.neon index 78ac922a..317f8102 100644 --- a/phpstan.dist.neon +++ b/phpstan.dist.neon @@ -85,3 +85,8 @@ services: - class: ZEngine\PHPStan\TypedEntryPointReturnExtension tags: [phpstan.broker.dynamicStaticMethodReturnTypeExtension] + +# Every public method of ZEngine\Type / ZEngine\Reflection that returns a raw CData/CType or a +# generated struct stub view must carry @internal (AGENTS.md, issue #194) +rules: + - ZEngine\PHPStan\RawEngineAccessorRule diff --git a/src/Reflection/ClassSpecializer.php b/src/Reflection/ClassSpecializer.php index 2724cb5f..5a022491 100644 --- a/src/Reflection/ClassSpecializer.php +++ b/src/Reflection/ClassSpecializer.php @@ -79,11 +79,6 @@ class ClassSpecializer '__unserialize', ]; - /** - * ce_flags that describe the storage location of the source class (shared memory, - * opcache file cache, preload region) and must never travel onto a runtime copy - * that lives in plain request memory - */ /** * The three operand slots of a zend_op, paired with the field naming their node type * @@ -95,6 +90,11 @@ class ClassSpecializer 'result_type' => 'result', ]; + /** + * ce_flags that describe the storage location of the source class (shared memory, + * opcache file cache, preload region) and must never travel onto a runtime copy + * that lives in plain request memory + */ private const STORAGE_CE_FLAGS = ['ZEND_ACC_IMMUTABLE', 'ZEND_ACC_CACHED', 'ZEND_ACC_FILE_CACHED', 'ZEND_ACC_PRELOADED']; /** diff --git a/src/Reflection/FunctionLikeTrait.php b/src/Reflection/FunctionLikeTrait.php index e39af40f..d218e682 100644 --- a/src/Reflection/FunctionLikeTrait.php +++ b/src/Reflection/FunctionLikeTrait.php @@ -751,19 +751,6 @@ public function getStaticVariables(): ?HashTable return HashTable::fromCData($defaultTable); } - /** - * Dereferences the offset form of a ZEND_MAP_PTR field into the per-process map-ptr area - * - * The slot address is CG(map_ptr_base) + offset: the engine pre-biases the base, so no - * -1 adjustment is applied (see zend_map_ptr.h:ZEND_MAP_PTR_OFFSET2PTR and the identical - * arithmetic in StringEntry::setCachedClassEntry()). The bound check mirrors - * ZSTR_VALID_CE_CACHE: a slot beyond CG(map_ptr_last) was never handed out. - * - * @param int $slotOffset Raw field value with the low bit set (ZEND_MAP_PTR_IS_OFFSET) - * - * @return CData|null HashTable* stored in the slot, or null while the slot is not yet - * materialized (or the map-ptr area cannot vouch for it) - */ /** * Returns the materialized live static-variables table of this user function as the raw * `HashTable *`, or null while no call has bound the statics yet (both slot forms, see @@ -792,6 +779,19 @@ public function getLiveStaticsPointer(): ?object return Core::cast(HashTableStruct::class, $materialized); } + /** + * Dereferences the offset form of a ZEND_MAP_PTR field into the per-process map-ptr area + * + * The slot address is CG(map_ptr_base) + offset: the engine pre-biases the base, so no + * -1 adjustment is applied (see zend_map_ptr.h:ZEND_MAP_PTR_OFFSET2PTR and the identical + * arithmetic in StringEntry::setCachedClassEntry()). The bound check mirrors + * ZSTR_VALID_CE_CACHE: a slot beyond CG(map_ptr_last) was never handed out. + * + * @param int $slotOffset Raw field value with the low bit set (ZEND_MAP_PTR_IS_OFFSET) + * + * @return CData|null HashTable* stored in the slot, or null while the slot is not yet + * materialized (or the map-ptr area cannot vouch for it) + */ private function dereferenceMapPointerSlot(int $slotOffset): ?CData { $mapPointerBase = Core::$compiler->getMapPointerBaseAddress(); @@ -1044,8 +1044,7 @@ public function getAddress(): int * * @internal shared with the body-swap machinery (FunctionBodySwap), which performs * the low-level engine surgery on the entry - */ - /** + * * @return zend_function|zend_internal_function */ public function getEntryPointer(): object diff --git a/src/Reflection/ReflectionClass.php b/src/Reflection/ReflectionClass.php index 522690cb..e4cb9617 100644 --- a/src/Reflection/ReflectionClass.php +++ b/src/Reflection/ReflectionClass.php @@ -819,8 +819,7 @@ public function bindClassNameCache(?ReflectionClass $namesake = null): void * this class over poking fields on the result. * * @internal shared with the hot-swap machinery (ClassDelta/HotSwap) - */ - /** + * * @return zend_class_entry */ public function getRawValue(): object @@ -2175,8 +2174,7 @@ private function compactStaticMembersTables(array $ownStaticInfos, int $zvalSize * table (zend_class_init_statics) and every further access goes through it. Map-ptr * offsets (low bit set, opcache-shared classes) and the legacy case where the map ptr * aliases default_static_members_table are reported as null - nothing extra to fix then. - */ - /** + * * @return zval|null Pointer to the first zval slot of the materialized table */ private function getMaterializedStaticMembersTable(): ?object @@ -2932,6 +2930,9 @@ private function keepLazyLinkingCopyProcessLocal(string $handlerName): void * * This method is useful within create_object handler * + * @internal hands out a raw zend_object pointer - consumers create objects through + * CreateObjectHook::proceed() instead + * * @param CData|zend_class_entry $classType zend_class_entry type to create * @param bool $persistent Whether object should be allocated persistent or not. Low-level feature! * @@ -2990,9 +2991,6 @@ private function hasParentClass(): bool /** * Performs low-level initialization of fields * - * @param CData $classEntry - */ - /** * @param CData|zend_class_entry $classEntry */ private function initLowLevelStructures(object $classEntry): void diff --git a/src/Reflection/ReflectionClassConstant.php b/src/Reflection/ReflectionClassConstant.php index f7caa900..60c05cf2 100644 --- a/src/Reflection/ReflectionClassConstant.php +++ b/src/Reflection/ReflectionClassConstant.php @@ -117,6 +117,8 @@ public static function fromRawEntry(object $constantEntry): ReflectionClassConst * The pointer is a live view into engine memory; prefer the typed accessors * (getReflectionValue(), equals(), getDeclaringClass()) over poking fields. * + * @internal raw-CData escape hatch for the core layer (see AGENTS.md) + * * @return zend_class_constant */ public function getRawValue(): object diff --git a/src/Reflection/ReflectionMethod.php b/src/Reflection/ReflectionMethod.php index 413adcc0..4488fc77 100644 --- a/src/Reflection/ReflectionMethod.php +++ b/src/Reflection/ReflectionMethod.php @@ -194,21 +194,6 @@ private static function publicationBoard(): object return self::$publicationBoard; } - /** - * Binds the zend_function embedded into a closure to the given class as a method - * - * All function surgery goes through the wrapper API: the entry is renamed, attached to - * the class scope and stripped of its ZEND_ACC_CLOSURE flag. The caller stays responsible - * for the closure lifetime (the embedded zend_function lives inside the closure object) - * and for publishing the function in the class method table. - * - * Note: the native reflection state of the returned wrapper is not initialized (the - * method is not registered in the class yet), so only the low-level API is usable on it. - * Re-wrap the function after publishing to get a fully functional reflection, like - * ReflectionClass::addMethod() does. - * - * @internal - */ /** * Creates a low-level reflection over a raw zend_function structure without * initializing the native reflection state @@ -221,8 +206,7 @@ private static function publicationBoard(): object * isUserDefined()/isRemovable()) is usable, native introspection is not. * * @internal used by the hot-swap machinery (ClassDelta) - */ - /** + * * @param CData|zend_function|zend_internal_function $functionEntry */ public static function fromRawEntry(object $functionEntry): ReflectionMethod @@ -235,6 +219,21 @@ public static function fromRawEntry(object $functionEntry): ReflectionMethod return $reflectionMethod; } + /** + * Binds the zend_function embedded into a closure to the given class as a method + * + * All function surgery goes through the wrapper API: the entry is renamed, attached to + * the class scope and stripped of its ZEND_ACC_CLOSURE flag. The caller stays responsible + * for the closure lifetime (the embedded zend_function lives inside the closure object) + * and for publishing the function in the class method table. + * + * Note: the native reflection state of the returned wrapper is not initialized (the + * method is not registered in the class yet), so only the low-level API is usable on it. + * Re-wrap the function after publishing to get a fully functional reflection, like + * ReflectionClass::addMethod() does. + * + * @internal + */ public static function fromClosureEntry( ClosureEntry $closureEntry, string $className, diff --git a/src/Reflection/ReflectionValue.php b/src/Reflection/ReflectionValue.php index 2d6a1bd8..d9ce03f4 100644 --- a/src/Reflection/ReflectionValue.php +++ b/src/Reflection/ReflectionValue.php @@ -386,6 +386,8 @@ public function getIndirectValue(): self /** * Type-friendly getter to return zend_class_entry directly * + * @internal raw-CData escape hatch for the core layer (see AGENTS.md) + * * @return zend_class_entry */ public function getRawClass(): object @@ -402,6 +404,8 @@ public function getRawClass(): object /** * Type-friendly getter to return zend_function/zend_internal_function directly * + * @internal raw-CData escape hatch for the core layer (see AGENTS.md) + * * @return zend_function|zend_internal_function */ public function getRawFunction(): object @@ -423,6 +427,8 @@ public function getRawFunction(): object /** * Type-friendly getter to return zend_string directly * + * @internal raw-CData escape hatch for the core layer (see AGENTS.md) + * * @return zend_string */ public function getRawString(): object @@ -439,6 +445,8 @@ public function getRawString(): object /** * Type-friendly getter to return zend_array directly * + * @internal raw-CData escape hatch for the core layer (see AGENTS.md) + * * @return zend_array */ public function getRawArray(): object @@ -455,6 +463,8 @@ public function getRawArray(): object /** * Type-friendly getter to return zend_object directly * + * @internal raw-CData escape hatch for the core layer (see AGENTS.md) + * * @return zend_object */ public function getRawObject(): object @@ -471,6 +481,8 @@ public function getRawObject(): object /** * Type-friendly getter to return zend_resource directly * + * @internal raw-CData escape hatch for the core layer (see AGENTS.md) + * * @return zend_resource */ public function getRawResource(): object @@ -485,7 +497,9 @@ public function getRawResource(): object } /** - * Type-friendly getter to return zend_resource directly + * Type-friendly getter to return zend_reference directly + * + * @internal raw-CData escape hatch for the core layer (see AGENTS.md) * * @return zend_reference */ @@ -528,6 +542,8 @@ public function dereference(): self /** * Type-friendly getter to return pointer * + * @internal raw-CData escape hatch for the core layer (see AGENTS.md) + * * @return \FFI\CData */ public function getRawPointer(): object @@ -548,6 +564,8 @@ public function getRawPointer(): object * state and writes go straight to the engine. Prefer the typed accessors * (getType(), getNativeValue(), equals()) over poking fields on the result. * + * @internal raw-CData escape hatch for the core layer (see AGENTS.md) + * * @return zval */ public function getRawValue(): object diff --git a/src/Type/ClosureEntry.php b/src/Type/ClosureEntry.php index 697055c2..1350e36e 100644 --- a/src/Type/ClosureEntry.php +++ b/src/Type/ClosureEntry.php @@ -160,6 +160,8 @@ public function setThis(object $object): void /** * Returns raw zend_function data for this closure * + * @internal raw-CData escape hatch for the core layer (see AGENTS.md) + * * @return zend_function */ public function getRawFunction(): object diff --git a/src/Type/ObjectEntry.php b/src/Type/ObjectEntry.php index 86588260..226a70aa 100644 --- a/src/Type/ObjectEntry.php +++ b/src/Type/ObjectEntry.php @@ -343,9 +343,9 @@ public function getDynamicPropertiesPointer(): ?object * * No refcounting is performed on either the previous or the new table - the caller * keeps ownership of both, exactly like setClass() does for class entries. + * * @internal - */ - /** + * * @param CData|HashTableStruct|null $hashTable */ public function setDynamicPropertiesPointer(?object $hashTable): void @@ -372,6 +372,8 @@ public function setHandlers(object $handlers): void /** * Returns raw C value entry * + * @internal raw-CData escape hatch for the core layer (see AGENTS.md) + * * @return zend_object */ public function getRawValue(): object @@ -439,8 +441,7 @@ protected function doRelease(bool $ownsReference, bool $ownsContainer): void /** * Performs low-level initialization of object - */ - /** + * * @param CData|zend_object $pointer */ private function initLowLevelStructures(object $pointer): void diff --git a/src/Type/OpLine.php b/src/Type/OpLine.php index 124e2633..1086bd84 100644 --- a/src/Type/OpLine.php +++ b/src/Type/OpLine.php @@ -106,6 +106,8 @@ public function __construct(object $opline, ?ExecutionData $context = null) /** * Returns a raw pointer to the opcode handler * + * @internal raw-CData escape hatch for the core layer (see AGENTS.md) + * * @return \FFI\CData */ public function getHandler(): object diff --git a/src/Type/PersistentObjectFactory.php b/src/Type/PersistentObjectFactory.php index c78b16bd..c844da81 100644 --- a/src/Type/PersistentObjectFactory.php +++ b/src/Type/PersistentObjectFactory.php @@ -73,6 +73,8 @@ final class PersistentObjectFactory * the caller releases it the same way it does the * rest of that region. * + * @internal raw-CData escape hatch for the core layer (see AGENTS.md) + * * @return zend_object zend_object* in persistent memory, not yet registered in the store */ public static function persistentClone(object $sourceObject, ?Allocator $allocator = null): object diff --git a/src/Type/ResourceEntry.php b/src/Type/ResourceEntry.php index f6524141..81aeb433 100644 --- a/src/Type/ResourceEntry.php +++ b/src/Type/ResourceEntry.php @@ -117,6 +117,8 @@ public function getHandle(): int /** * Returns the low-level raw data, associated with this resource * + * @internal raw-CData escape hatch for the core layer (see AGENTS.md) + * * @return \FFI\CData */ public function getRawData(): object diff --git a/src/Type/StringEntry.php b/src/Type/StringEntry.php index a662ae20..a04a3efd 100644 --- a/src/Type/StringEntry.php +++ b/src/Type/StringEntry.php @@ -198,6 +198,8 @@ public static function persistentInterned(string $value, ?Allocator $allocator = /** * Returns raw C value entry * + * @internal raw-CData escape hatch for the core layer (see AGENTS.md) + * * @return zend_string */ public function getRawValue(): object diff --git a/tools/phpstan/RawEngineAccessorRule.php b/tools/phpstan/RawEngineAccessorRule.php new file mode 100644 index 00000000..0daedc4a --- /dev/null +++ b/tools/phpstan/RawEngineAccessorRule.php @@ -0,0 +1,124 @@ + + * + * This source file is subject to the license that is bundled + * with this source code in the file LICENSE. + * + */ +declare(strict_types=1); + +namespace ZEngine\PHPStan; + +use FFI\CData; +use FFI\CType; +use PhpParser\Node; +use PHPStan\Analyser\Scope; +use PHPStan\Node\InClassMethodNode; +use PHPStan\Rules\IdentifierRuleError; +use PHPStan\Rules\Rule; +use PHPStan\Rules\RuleErrorBuilder; + +/** + * Requires every public raw-CData accessor of the core layer to be marked `@internal` + * + * AGENTS.md puts every `@internal` method off-limits to packages built on z-engine. A + * public method in `ZEngine\Type` or `ZEngine\Reflection` that returns a raw `FFI\CData` / + * `FFI\CType`, or a generated struct stub view (`ZEngine\Generated\*`, a CData handle at + * run time), is one of those escape hatches, so it must say so (issue #194). The marker + * on a whole class (StructArray, FunctionLikeInterface) covers its methods. + * + * PHPStan reads only the docblock right above a method: an `@internal` in an earlier, + * stacked docblock is lost, and this rule reports it like a missing one. + * + * @implements Rule + */ +final class RawEngineAccessorRule implements Rule +{ + private const array GUARDED_NAMESPACES = ['ZEngine\\Type\\', 'ZEngine\\Reflection\\']; + + private const array RAW_CLASSES = [CData::class, CType::class]; + + private const string STUB_NAMESPACE = 'ZEngine\\Generated\\'; + + /** + * Raw accessors that stay public until their API contract is decided, keyed + * `Class::method` => tracking issue + */ + private const array EXEMPT_METHODS = [ + // TODO(#192): AbstractModule exposes the globals through this method + 'ZEngine\\Reflection\\ReflectionExtension::getGlobals' => '#192', + ]; + + public function getNodeType(): string + { + return InClassMethodNode::class; + } + + /** + * @return list + */ + public function processNode(Node $node, Scope $scope): array + { + $method = $node->getMethodReflection(); + $class = $node->getClassReflection(); + if (!$method->isPublic() || $class->isInternal() || $method->isInternal()->yes()) { + return []; + } + if (!$this->isGuarded($class->getName())) { + return []; + } + if (isset(self::EXEMPT_METHODS[$method->getDeclaringClass()->getName() . '::' . $method->getName()])) { + return []; + } + + $rawClass = $this->findRawReturnClass($node); + if ($rawClass === null) { + return []; + } + + $message = sprintf( + 'Public method %s::%s() returns raw %s but is not marked @internal (see AGENTS.md, "Public APIs never leak CData").', + $class->getDisplayName(), + $method->getName(), + $rawClass, + ); + + return [ + RuleErrorBuilder::message($message) + ->identifier('zengine.rawAccessorNotInternal') + ->tip('Add an @internal tag to the method docblock, in the same block as its @return.') + ->build(), + ]; + } + + private function isGuarded(string $className): bool + { + foreach (self::GUARDED_NAMESPACES as $namespace) { + if (str_starts_with($className, $namespace)) { + return true; + } + } + + return false; + } + + /** + * Returns the first raw engine class the method's return type refers to, or null + */ + private function findRawReturnClass(InClassMethodNode $node): ?string + { + foreach ($node->getMethodReflection()->getVariants() as $variant) { + foreach ($variant->getReturnType()->getReferencedClasses() as $referencedClass) { + if (in_array($referencedClass, self::RAW_CLASSES, true) || str_starts_with($referencedClass, self::STUB_NAMESPACE)) { + return $referencedClass; + } + } + } + + return null; + } +}