__rhandle = $rhandle; $this->__epoch = $epoch; } public function __destruct() { \ShirabeRustObjectRegistry::release($this->__rhandle); } public function __shirabeRustHandleDescriptor(): array { return [ '__rhandle' => $this->__rhandle, '__class' => static::class, '__epoch' => $this->__epoch, ]; } PHP; private Project $project; private NamePrinter $printer; /** @var list */ private array $errors = []; /** @var array */ private array $targetSet = []; /** * Emitted method records per stub class: fqcn => name => fingerprint. A subclass stub * omits overrides whose parameter list matches the record; the record therefore doubles * as the divergence detector for omitted overrides. * * @var array>> */ private array $surfaces = []; /** @param list $targets */ public function __construct( string $composerRoot, private readonly Report $report, private readonly array $targets, ) { $this->project = new Project($composerRoot); $this->printer = new NamePrinter(); foreach ($targets as $fqcn) { $this->targetSet[$fqcn] = true; } } /** @return array relative stub path => file content */ public function generate(): array { $files = []; foreach ($this->targets as $fqcn) { $files[str_replace('\\', '/', $fqcn) . '.php'] = $this->emitClass($fqcn); } if ($this->errors !== []) { throw new GenerationError($this->errors); } return $files; } private function emitClass(string $fqcn): string { $file = $this->project->sourceFor($fqcn); $class = $file->classLike; if (!$class instanceof Class_) { $this->errors[] = "$fqcn is not a class"; return ''; } $category = $this->report->category($fqcn); if (!in_array($category, ['rust-proxy', 'contract'], true)) { $this->errors[] = "$fqcn is classified as " . ($category ?? 'nothing') . '; only rust-proxy and contract classes can become proxy stubs'; } $parentFqcn = $class->extends === null ? null : $this->resolvedName($class->extends); $isRoot = $parentFqcn === null; if ($parentFqcn !== null && !isset($this->targetSet[$parentFqcn])) { $this->errors[] = "$fqcn extends $parentFqcn, which is not a stub target"; $isRoot = true; } if (!$isRoot && !isset($this->surfaces[$parentFqcn])) { $this->errors[] = "$fqcn must come after its base class $parentFqcn in targets.list"; $isRoot = true; } foreach ($class->getProperties() as $property) { if ($property->isPublic()) { $this->errors[] = "$fqcn declares a public property; a proxy stub cannot forward property access"; } } $constants = []; foreach ($class->getConstants() as $constant) { if (!$constant->isPublic()) { $this->errors[] = "$fqcn declares a non-public constant; materializing it is not supported"; continue; } $constants[] = $file->verbatim($constant->getStartLine(), $constant->getEndLine()); } $publicStatics = []; $nonPublicStatics = []; $ownInstanceMethods = []; foreach ($class->getMethods() as $method) { $name = $method->name->toString(); if ($name === '__construct') { continue; } if (str_starts_with($name, '__')) { if ($method->isPublic()) { $this->errors[] = "$fqcn::$name: magic methods cannot be proxied"; } continue; } if ($method->isStatic()) { if ($method->isPublic()) { $publicStatics[$name] = $method; } else { $nonPublicStatics[$name] = $method; } } elseif ($method->isPublic()) { $ownInstanceMethods[$name] = $method; } } $staticMethods = $this->materializeStatics($file, $publicStatics, $nonPublicStatics); $surface = []; $emitted = []; if ($isRoot) { foreach ($this->interfaceClosure($class) as $interface) { foreach ($interface->classLike->getMethods() as $method) { $name = $method->name->toString(); if ($method->isStatic()) { $this->errors[] = "$fqcn: static interface method $name is not supported"; continue; } $emitted[$name] ??= $method; } } // A concrete redeclaration wins over the interface signature (it may widen // defaults); it keeps the interface's position in the emission order. foreach ($ownInstanceMethods as $name => $method) { $emitted[$name] = $method; } } else { $surface = $this->surfaces[$parentFqcn]; if ($class->implements !== []) { $this->errors[] = "$fqcn adds interfaces to a stub base class; this is not supported yet"; } foreach ($ownInstanceMethods as $name => $method) { if (isset($surface[$name])) { $this->checkOmittedOverride($fqcn, $name, $method, $file, $surface[$name]); } else { $emitted[$name] = $method; } } } $methodTexts = []; foreach ($emitted as $name => $method) { $methodTexts[] = $this->renderProxyMethod($fqcn, $name, $method, $file); $surface[$name] = $this->fingerprint($method, $file); } $this->surfaces[$fqcn] = $surface; $decl = ($class->isAbstract() ? 'abstract ' : '') . 'class ' . $class->name?->toString(); if ($class->extends !== null) { $decl .= ' extends ' . $this->printer->renderName($class->extends, $file); } if ($isRoot) { $interfaces = array_map(fn (Name $n): string => $this->printer->renderName($n, $file), $class->implements); $interfaces[] = '\ShirabeRustStub'; $decl .= ' implements ' . implode(', ', $interfaces); } $members = []; if ($isRoot) { $members[] = self::BOILERPLATE; } if ($constants !== []) { $members[] = implode("\n", $constants); } $members = array_merge($members, $staticMethods, $methodTexts); $body = implode("\n\n", $members); $header = "// Generated by scripts/plugin-stub-generator; do not edit by hand.\n" . "// Proxy stub for $fqcn: the public surface forwards to the Rust-side entity over RPC."; $text = "namespace};\n\n"; $uses = $this->usedImports($file, $decl . "\n" . $body); if ($uses !== '') { $text .= $uses . "\n\n"; } return $text . $decl . "\n{\n" . ($body === '' ? '' : $body . "\n") . "}\n"; } /** * Static methods read no instance state; their real implementation is materialized * verbatim so they run locally in the worker. Non-public static helpers they call * (through `self::`, `static::` or the class name) are materialized along with them. * * @param array $publicStatics * @param array $nonPublicStatics * @return list */ private function materializeStatics(SourceFile $file, array $publicStatics, array $nonPublicStatics): array { $texts = []; foreach ($publicStatics as $name => $method) { $texts[$name] = $file->verbatim($method->getStartLine(), $method->getEndLine()); } $scan = array_values($texts); while ($scan !== []) { $text = array_shift($scan); foreach ($nonPublicStatics as $name => $method) { if (isset($texts[$name])) { continue; } $receiver = '(?:self|static|' . preg_quote($file->classLike->name?->toString() ?? '', '/') . ')'; if (preg_match('/(?verbatim($method->getStartLine(), $method->getEndLine()); } } } return array_values($texts); } /** Interfaces implemented by the class, each interface preceding the ones it extends. */ private function interfaceClosure(Class_ $class): array { $out = []; $seen = []; $visit = function (string $fqcn) use (&$visit, &$out, &$seen): void { if (isset($seen[$fqcn])) { return; } $seen[$fqcn] = true; $file = $this->project->sourceFor($fqcn); if (!$file->classLike instanceof Interface_) { $this->errors[] = "$fqcn is implemented as an interface but is not one"; return; } $out[] = $file; foreach ($file->classLike->extends as $parent) { $visit($this->resolvedName($parent)); } }; foreach ($class->implements as $interface) { $visit($this->resolvedName($interface)); } return $out; } private function renderProxyMethod(string $fqcn, string $name, ClassMethod $method, SourceFile $target): string { $params = []; $args = []; foreach ($method->params as $param) { $paramName = $param->var->name; if ($param->byRef) { $this->errors[] = "$fqcn::$name: by-ref parameter \$$paramName cannot be proxied yet"; } if ($param->variadic) { $this->errors[] = "$fqcn::$name: variadic parameter \$$paramName cannot be proxied yet"; } $rendered = ''; if ($param->type !== null) { $rendered = $this->printer->renderType($param->type, $target) . ' '; } $rendered .= '$' . $paramName; if ($param->default !== null) { $rendered .= ' = ' . $this->printer->renderExpr($param->default, $target); } $params[] = $rendered; $args[] = '$' . $paramName; } $returnType = $this->printer->renderType($method->returnType, $target); $signature = "public function $name(" . implode(', ', $params) . ')' . ($returnType === '' ? '' : ": $returnType"); $call = "\\ShirabeRpcRuntime::callRust(\$this->__rhandle, '$name', [" . implode(', ', $args) . '])'; // `self`/`static` returns are fluent interfaces; the local stub itself is returned to // preserve identity instead of round-tripping the handle. $body = match ($returnType) { 'void' => " $call;", 'self', 'static' => " $call;\n return \$this;", default => " return $call;", }; return " $signature\n {\n$body\n }"; } /** * An override that is omitted from a subclass stub must take exactly the parameters the * inherited stub method declares: same names, arity, defaults and passing modes. Type * declarations are allowed to differ (overrides may widen them; the forwarding body is * type-agnostic either way). */ private function checkOmittedOverride( string $fqcn, string $name, ClassMethod $method, SourceFile $file, array $inherited, ): void { if ($this->fingerprint($method, $file) !== $inherited) { $this->errors[] = "$fqcn::$name: override diverges from the inherited stub signature" . ' (names, arity, defaults or passing modes); it can no longer be omitted'; } } /** @return list */ private function fingerprint(ClassMethod $method, SourceFile $file): array { $fingerprint = []; foreach ($method->params as $param) { $fingerprint[] = [ $param->var->name, $param->default !== null, $param->default === null ? '' : $this->printer->renderExpr($param->default, $file), $param->byRef, $param->variadic, ]; } return $fingerprint; } /** The original file's imports, restricted to names the emitted stub actually uses. */ private function usedImports(SourceFile $file, string $emittedText): string { $kept = []; foreach ($file->aliases as $alias => $fqcn) { if (preg_match('/(?getAttribute('resolvedName'); return $resolved instanceof Name ? $resolved->toString() : $name->toString(); } }