gen_stub.php

#!/usr/bin/env php
<?php declare(strict_types=1);

use PhpParser\Comment\Doc as DocComment;
use PhpParser\ConstExprEvaluator;
use PhpParser\Modifiers;
use PhpParser\Node;
use PhpParser\Node\AttributeGroup;
use PhpParser\Node\Expr;
use PhpParser\Node\Name;
use PhpParser\Node\Stmt;
use PhpParser\Node\Stmt\Class_;
use PhpParser\Node\Stmt\Enum_;
use PhpParser\Node\Stmt\Interface_;
use PhpParser\Node\Stmt\Trait_;
use PhpParser\PrettyPrinter\Standard;
use PhpParser\PrettyPrinterAbstract;

error_reporting(E_ALL);
ini_set("precision", "-1");

const PHP_70_VERSION_ID = 70000;
const PHP_80_VERSION_ID = 80000;
const PHP_81_VERSION_ID = 80100;
const PHP_82_VERSION_ID = 80200;
const PHP_83_VERSION_ID = 80300;
const PHP_84_VERSION_ID = 80400;
const PHP_85_VERSION_ID = 80500;
const ALL_PHP_VERSION_IDS = [
    PHP_70_VERSION_ID,
    PHP_80_VERSION_ID,
    PHP_81_VERSION_ID,
    PHP_82_VERSION_ID,
    PHP_83_VERSION_ID,
    PHP_84_VERSION_ID,
    PHP_85_VERSION_ID,
];

// file_put_contents() but with a success message printed after saving
function reportFilePutContents(string $filename, string $content): void {
    if (file_put_contents($filename, $content)) {
        echo "Saved $filename\n";
    }
}

if (!function_exists('array_any')) {
    function array_any(array $array, callable $callback): bool {
        foreach ($array as $key => $value) {
            if ($callback($value, $key)) {
                return true;
            }
        }
        return false;
    }
}

if (function_exists('clone')) {
    // Replace (\clone)(...) with \clone(...) once the minimally
    // supported PHP version is 8.5.
    define('clone', \clone(...));
} else {
    define(
        'clone',
        /**
         * @template T
         * @param T $o
         * @return T
         */
        function (object $o): object {
            return clone $o;
        }
    );
}

/**
 * @return FileInfo[]
 */
function processDirectory(string $dir, Context $context): array {
    $pathNames = [];
    $it = new RecursiveIteratorIterator(
        new RecursiveDirectoryIterator($dir),
        RecursiveIteratorIterator::LEAVES_ONLY
    );
    foreach ($it as $file) {
        $pathName = $file->getPathName();
        if (str_ends_with($pathName, '.stub.php')) {
            $pathNames[] = $pathName;
        }
    }

    // Make sure stub files are processed in a predictable, system-independent order.
    sort($pathNames);

    $fileInfos = [];
    foreach ($pathNames as $pathName) {
        $fileInfo = processStubFile($pathName, $context);
        if ($fileInfo) {
            $fileInfos[] = $fileInfo;
        }
    }
    return $fileInfos;
}

function processStubFile(string $stubFile, Context $context, bool $includeOnly = false): ?FileInfo {
    try {
        if (!file_exists($stubFile)) {
            throw new Exception("File $stubFile does not exist");
        }

        if (!$includeOnly) {
            $stubFilenameWithoutExtension = str_replace(".stub.php", "", $stubFile);
            $arginfoFile = "{$stubFilenameWithoutExtension}_arginfo.h";
            $legacyFile = "{$stubFilenameWithoutExtension}_legacy_arginfo.h";
            $declFile = "{$stubFilenameWithoutExtension}_decl.h";

            /* Check if the stub file changed, by checking that the hash stored
             * in the generated arginfo.h matches.
             * Also check that the decl.h file has the same hash. At this point
             * we don't know if a decl.h file is supposed to exist, so extract
             * this information (whether a decl file should exist) from the
             * arginfo.h file. */
            $stubCode = file_get_contents($stubFile);
            $stubHash = sha1(str_replace("\r\n", "\n", $stubCode));
            $oldStubHash = extractStubHash($arginfoFile);
            $hasDeclHeader = extractHasDeclHeader($arginfoFile);
            $oldStubHashDecl = extractStubHash($declFile);
            $generatedFilesUpToDate = $stubHash === $oldStubHash
                    && ($hasDeclHeader ? $stubHash === $oldStubHashDecl : $oldStubHashDecl === null);
            if ($generatedFilesUpToDate && !$context->forceParse) {
                /* Stub file did not change, do not regenerate. */
                return null;
            }
        }

        if (!$fileInfo = $context->parsedFiles[$stubFile] ?? null) {
            initPhpParser();
            $stubContent = $stubCode ?? file_get_contents($stubFile);
            $fileInfo = FileInfo::parseStubFile($stubContent);
            $context->parsedFiles[$stubFile] = $fileInfo;

            foreach ($fileInfo->dependencies as $dependency) {
                // TODO add header search path for extensions?
                $prefixes = [dirname($stubFile) . "/", dirname(__DIR__) . "/"];
                foreach ($prefixes as $prefix) {
                    $depFile = $prefix . $dependency;
                    if (file_exists($depFile)) {
                        break;
                    }
                    $depFile = null;
                }
                if (!$depFile) {
                    throw new Exception("File $stubFile includes a file $dependency which does not exist");
                }
                processStubFile($depFile, $context, true);
            }

            $constInfos = $fileInfo->getAllConstInfos();
            $context->allConstInfos = array_merge($context->allConstInfos, $constInfos);
        }

        if ($includeOnly) {
            return $fileInfo;
        }

        [$arginfoCode, $declCode] = $fileInfo->generateArgInfoCode(
            basename($stubFilenameWithoutExtension),
            $context->allConstInfos,
            $stubHash
        );
        if ($context->forceRegeneration || !$generatedFilesUpToDate) {
            reportFilePutContents($arginfoFile, $arginfoCode);
            if ($declCode !== '') {
                reportFilePutContents($declFile, $declCode);
            } else if (file_exists($declFile)) {
                unlink($declFile);
            }
        }

        if ($fileInfo->shouldGenerateLegacyArginfo()) {
            $legacyFileInfo = $fileInfo->getLegacyVersion();

            [$arginfoCode] = $legacyFileInfo->generateArgInfoCode(
                basename($stubFilenameWithoutExtension),
                $context->allConstInfos,
                $stubHash
            );
            if ($context->forceRegeneration || !$generatedFilesUpToDate) {
                reportFilePutContents($legacyFile, $arginfoCode);
            }
        }

        return $fileInfo;
    } catch (Exception $e) {
        echo "In $stubFile:\n{$e->getMessage()}\n";
        exit(1);
    }
}

function extractStubHash(string $arginfoFile): ?string {
    if (!file_exists($arginfoFile)) {
        return null;
    }

    $arginfoCode = file_get_contents($arginfoFile);
    if (!preg_match('/\* Stub hash: ([0-9a-f]+)/', $arginfoCode, $matches)) {
        return null;
    }

    return $matches[1];
}

function extractHasDeclHeader(string $arginfoFile): bool {
    if (!file_exists($arginfoFile)) {
        return false;
    }

    $arginfoCode = file_get_contents($arginfoFile);
    return str_contains($arginfoCode, '* Has decl header: yes *');
}

class Context {
    public bool $forceParse = false;
    public bool $forceRegeneration = false;
    /** @var array<string, ConstInfo> */
    public array $allConstInfos = [];
    /** @var FileInfo[] */
    public array $parsedFiles = [];
}

class ArrayType extends SimpleType {

    public function __construct(
        private readonly Type $keyType,
        private readonly Type $valueType,
    ) {
        parent::__construct("array", true);
    }

    public static function createGenericArray(): self
    {
        return new ArrayType(Type::fromString("int|string"), Type::fromString("mixed|ref"));
    }

    public function toOptimizerTypeMask(): string {
        $typeMasks = [
            parent::toOptimizerTypeMask(),
            $this->keyType->toOptimizerTypeMaskForArrayKey(),
            $this->valueType->toOptimizerTypeMaskForArrayValue(),
        ];

        return implode("|", $typeMasks);
    }

    public function equals(SimpleType $other): bool {
        if (!parent::equals($other)) {
            return false;
        }

        assert(get_class($other) === self::class);

        return Type::equals($this->keyType, $other->keyType) &&
            Type::equals($this->valueType, $other->valueType);
    }
}

class SimpleType {

    protected function __construct(
        public readonly string $name,
        public readonly bool $isBuiltin,
    ) {}

    public static function fromNode(Node $node): SimpleType {
        if ($node instanceof Node\Name) {
            if ($node->toLowerString() === 'static') {
                // PHP internally considers "static" a builtin type.
                return new SimpleType($node->toLowerString(), true);
            }

            if ($node->toLowerString() === 'self') {
                throw new Exception('The exact class name must be used instead of "self"');
            }

            assert($node->isFullyQualified());
            return new SimpleType($node->toString(), false);
        }

        if ($node instanceof Node\Identifier) {
            if ($node->toLowerString() === 'array') {
                return ArrayType::createGenericArray();
            }

            return new SimpleType($node->toLowerString(), true);
        }

        throw new Exception("Unexpected node type");
    }

    public static function fromString(string $typeString): SimpleType
    {
        switch (strtolower($typeString)) {
            case "void":
            case "null":
            case "false":
            case "true":
            case "bool":
            case "int":
            case "float":
            case "string":
            case "callable":
            case "object":
            case "resource":
            case "mixed":
            case "static":
            case "never":
            case "ref":
                return new SimpleType(strtolower($typeString), true);
            case "array":
                return ArrayType::createGenericArray();
            case "self":
                throw new Exception('The exact class name must be used instead of "self"');
            case "iterable":
                throw new Exception('This should not happen');
        }

        $matches = [];
        $isArray = preg_match("/(.*)\s*\[\s*\]/", $typeString, $matches);
        if ($isArray) {
            return new ArrayType(Type::fromString("int"), Type::fromString($matches[1]));
        }

        $matches = [];
        $isArray = preg_match("/array\s*<\s*([A-Za-z0-9_|-]+)?(\s*,\s*)?([A-Za-z0-9_|-]+)?\s*>/i", $typeString, $matches);
        if ($isArray) {
            if (empty($matches[1]) || empty($matches[3])) {
                throw new Exception("array<> type hint must have both a key and a value");
            }

            return new ArrayType(Type::fromString($matches[1]), Type::fromString($matches[3]));
        }

        return new SimpleType($typeString, false);
    }

    /**
     * @param mixed $value
     */
    public static function fromValue($value): SimpleType
    {
        return match (gettype($value)) {
            "NULL" => SimpleType::null(),
            "boolean" => new SimpleType("bool", true),
            "integer" => new SimpleType("int", true),
            "double" => new SimpleType("float", true),
            "string" => new SimpleType("string", true),
            "array" => new SimpleType("array", true),
            "object" => new SimpleType("object", true),
            default => throw new Exception("Type \"" . gettype($value) . "\" cannot be inferred based on value"),
        };
    }

    public static function null(): SimpleType
    {
        return new SimpleType("null", true);
    }

    public function isScalar(): bool {
        return $this->isBuiltin && in_array($this->name, ["null", "false", "true", "bool", "int", "float"], true);
    }

    public function isNull(): bool {
        return $this->isBuiltin && $this->name === 'null';
    }

    public function isBool(): bool {
        return $this->isBuiltin && $this->name === 'bool';
    }

    public function isInt(): bool {
        return $this->isBuiltin && $this->name === 'int';
    }

    public function isFloat(): bool {
        return $this->isBuiltin && $this->name === 'float';
    }

    public function isString(): bool {
        return $this->isBuiltin && $this->name === 'string';
    }

    public function isArray(): bool {
        return $this->isBuiltin && $this->name === 'array';
    }

    public function isMixed(): bool {
        return $this->isBuiltin && $this->name === 'mixed';
    }

    private function toTypeInfo(): array {
        assert($this->isBuiltin);

        return match ($this->name) {
            "null" => ["IS_NULL", "MAY_BE_NULL"],
            "false" => ["IS_FALSE", "MAY_BE_FALSE"],
            "true" => ["IS_TRUE", "MAY_BE_TRUE"],
            "bool" => ["_IS_BOOL", "MAY_BE_BOOL"],
            "int" => ["IS_LONG", "MAY_BE_LONG"],
            "float" => ["IS_DOUBLE", "MAY_BE_DOUBLE"],
            "string" => ["IS_STRING", "MAY_BE_STRING"],
            "array" => ["IS_ARRAY", "MAY_BE_ARRAY"],
            "object" => ["IS_OBJECT", "MAY_BE_OBJECT"],
            "callable" => ["IS_CALLABLE", "MAY_BE_CALLABLE"],
            "mixed" => ["IS_MIXED", "MAY_BE_ANY"],
            "void" => ["IS_VOID", "MAY_BE_VOID"],
            "static" => ["IS_STATIC", "MAY_BE_STATIC"],
            "never" => ["IS_NEVER", "MAY_BE_NEVER"],
            default => throw new Exception("Not implemented: $this->name"),
        };
    }

    public function toTypeCode(): string {
        return $this->toTypeInfo()[0];
    }

    public function toTypeMask(): string {
        return $this->toTypeInfo()[1];
    }

    public function toOptimizerTypeMaskForArrayKey(): string {
        assert($this->isBuiltin);

        return match ($this->name) {
            "int" => "MAY_BE_ARRAY_KEY_LONG",
            "string" => "MAY_BE_ARRAY_KEY_STRING",
            default => throw new Exception("Type $this->name cannot be an array key"),
        };
    }

    public function toOptimizerTypeMaskForArrayValue(): string {
        if (!$this->isBuiltin) {
            return "MAY_BE_ARRAY_OF_OBJECT";
        }

        return match ($this->name) {
            "null" => "MAY_BE_ARRAY_OF_NULL",
            "false" => "MAY_BE_ARRAY_OF_FALSE",
            "true" => "MAY_BE_ARRAY_OF_TRUE",
            "bool" => "MAY_BE_ARRAY_OF_FALSE|MAY_BE_ARRAY_OF_TRUE",
            "int" => "MAY_BE_ARRAY_OF_LONG",
            "float" => "MAY_BE_ARRAY_OF_DOUBLE",
            "string" => "MAY_BE_ARRAY_OF_STRING",
            "array" => "MAY_BE_ARRAY_OF_ARRAY",
            "object" => "MAY_BE_ARRAY_OF_OBJECT",
            "resource" => "MAY_BE_ARRAY_OF_RESOURCE",
            "mixed" => "MAY_BE_ARRAY_OF_ANY",
            "ref" => "MAY_BE_ARRAY_OF_REF",
            default => throw new Exception("Type $this->name cannot be an array value"),
        };
    }

    public function toOptimizerTypeMask(): string {
        if (!$this->isBuiltin) {
            return "MAY_BE_OBJECT";
        }

        return match ($this->name) {
            "resource" => "MAY_BE_RESOURCE",
            "callable" => "MAY_BE_STRING|MAY_BE_ARRAY|MAY_BE_ARRAY_KEY_LONG|MAY_BE_ARRAY_OF_STRING|MAY_BE_ARRAY_OF_OBJECT|MAY_BE_OBJECT",
            "iterable" => "MAY_BE_ARRAY|MAY_BE_ARRAY_KEY_ANY|MAY_BE_ARRAY_OF_ANY|MAY_BE_OBJECT",
            "mixed" => "MAY_BE_ANY|MAY_BE_ARRAY_KEY_ANY|MAY_BE_ARRAY_OF_ANY",
            default => $this->toTypeMask(),
        };
    }

    public function toEscapedName(): string {
        // Escape backslashes, and also encode \u, \U, and \N to avoid compilation errors in generated macros
        return str_replace(
            ['\\', '\\u', '\\U', '\\N'],
            ['\\\\', '\\\\165', '\\\\125', '\\\\116'],
            $this->name
        );
    }

    public function toVarEscapedName(): string {
        return str_replace('\\', '_', $this->name);
    }

    public function equals(SimpleType $other): bool {
        return $this->name === $other->name && $this->isBuiltin === $other->isBuiltin;
    }
}

// Instances of Type are immutable and do not need to be cloned
// when held by an object that is cloned
class Type {

    /**
     * @param SimpleType[] $types
     */
    private function __construct(
        public readonly array $types,
        public readonly bool $isIntersection
    ) {}

    public static function fromNode(Node $node): Type {
        if ($node instanceof Node\UnionType || $node instanceof Node\IntersectionType) {
            $nestedTypeObjects = array_map(Type::fromNode(...), $node->types);
            $types = [];
            foreach ($nestedTypeObjects as $typeObject) {
                array_push($types, ...$typeObject->types);
            }
            return new Type($types, ($node instanceof Node\IntersectionType));
        }

        if ($node instanceof Node\NullableType) {
            return new Type(
                [
                    ...Type::fromNode($node->type)->types,
                    SimpleType::null(),
                ],
                false
            );
        }

        if ($node instanceof Node\Identifier && $node->toLowerString() === "iterable") {
            return new Type(
                [
                    SimpleType::fromString("Traversable"),
                    ArrayType::createGenericArray(),
                ],
                false
            );
        }

        return new Type([SimpleType::fromNode($node)], false);
    }

    public static function fromString(string $typeString): self {
        $typeString .= "|";
        $simpleTypes = [];
        $simpleTypeOffset = 0;
        $inArray = false;
        $isIntersection = false;

        $typeStringLength = strlen($typeString);
        for ($i = 0; $i < $typeStringLength; $i++) {
            $char = $typeString[$i];

            if ($char === "<") {
                $inArray = true;
                continue;
            }

            if ($char === ">") {
                $inArray = false;
                continue;
            }

            if ($inArray) {
                continue;
            }

            if ($char === "|" || $char === "&") {
                $isIntersection = ($char === "&");
                $simpleTypeName = trim(substr($typeString, $simpleTypeOffset, $i - $simpleTypeOffset));

                $simpleTypes[] = SimpleType::fromString($simpleTypeName);

                $simpleTypeOffset = $i + 1;
            }
        }

        return new Type($simpleTypes, $isIntersection);
    }

    public function isScalar(): bool {
        return !array_any($this->types, static fn (SimpleType $type): bool => !$type->isScalar());
    }

    public function isNullable(): bool {
        return array_any($this->types, static fn (SimpleType $type): bool => $type->isNull());
    }

    public function tryToSimpleType(): ?SimpleType {
        $nonNullTypes = array_filter(
            $this->types,
            function(SimpleType $type) {
                return !$type->isNull();
            }
        );
        /* type has only null */
        if (count($nonNullTypes) === 0) {
            return $this->types[0];
        }
        if (count($nonNullTypes) === 1) {
            return reset($nonNullTypes);
        }
        return null;
    }

    public function toArginfoType(): ArginfoType {
        $classTypes = [];
        $builtinTypes = [];
        foreach ($this->types as $type) {
            if ($type->isBuiltin) {
                $builtinTypes[] = $type;
            } else {
                $classTypes[] = $type;
            }
        }
        return new ArginfoType($classTypes, $builtinTypes);
    }

    public function toOptimizerTypeMask(): string {
        $optimizerTypes = [];

        foreach ($this->types as $type) {
            // TODO Support for toOptimizerMask for intersection
            $optimizerTypes[] = $type->toOptimizerTypeMask();
        }

        return implode("|", $optimizerTypes);
    }

    public function toOptimizerTypeMaskForArrayKey(): string {
        $typeMasks = [];

        foreach ($this->types as $type) {
            $typeMasks[] = $type->toOptimizerTypeMaskForArrayKey();
        }

        return implode("|", $typeMasks);
    }

    public function toOptimizerTypeMaskForArrayValue(): string {
        $typeMasks = [];

        foreach ($this->types as $type) {
            $typeMasks[] = $type->toOptimizerTypeMaskForArrayValue();
        }

        return implode("|", $typeMasks);
    }

    public function getTypeForDoc(DOMDocument $doc): DOMElement {
        if (count($this->types) > 1) {
            $typeSort = $this->isIntersection ? "intersection" : "union";
            $typeElement = $doc->createElement('type');
            $typeElement->setAttribute("class", $typeSort);

            foreach ($this->types as $type) {
                $unionTypeElement = $doc->createElement('type', $type->name);
                $typeElement->appendChild($unionTypeElement);
            }
        } else {
            $type = $this->types[0];
            $typeElement = $doc->createElement('type', $type->name);
        }

        return $typeElement;
    }

    public static function equals(?Type $a, ?Type $b): bool {
        if ($a === null || $b === null) {
            return $a === $b;
        }

        if (count($a->types) !== count($b->types)) {
            return false;
        }

        for ($i = 0; $i < count($a->types); $i++) {
            if (!$a->types[$i]->equals($b->types[$i])) {
                return false;
            }
        }

        return true;
    }

    public function __toString() {
        $char = $this->isIntersection ? '&' : '|';
        return implode($char, array_map(
            function ($type) { return $type->name; },
            $this->types)
        );
    }
}

class ArginfoType {

    /**
     * @param SimpleType[] $classTypes
     * @param SimpleType[] $builtinTypes
     */
    public function __construct(
        public readonly array $classTypes,
        private readonly array $builtinTypes,
    ) {}

    public function hasClassType(): bool {
        return !empty($this->classTypes);
    }

    public function toClassTypeString(): string {
        return implode('|', array_map(function(SimpleType $type) {
            return $type->toEscapedName();
        }, $this->classTypes));
    }

    public function toTypeMask(): string {
        if (empty($this->builtinTypes)) {
            return '0';
        }
        return implode('|', array_map(function(SimpleType $type) {
            return $type->toTypeMask();
        }, $this->builtinTypes));
    }
}

class ArgInfo {
    public const SEND_BY_VAL = "0";
    public const SEND_BY_REF = "1";
    public const SEND_PREFER_REF = "ZEND_SEND_PREFER_REF";

    /**
     * @param AttributeInfo[] $attributes
     */
    public function __construct(
        public readonly string $name,
        public readonly string $sendBy,
        public readonly bool $isVariadic,
        public ?Type $type,
        private readonly ?Type $phpDocType,
        public ?string $defaultValue,
        public array $attributes,
    ) {}

    public function equals(ArgInfo $other): bool {
        return $this->name === $other->name
            && $this->sendBy === $other->sendBy
            && $this->isVariadic === $other->isVariadic
            && Type::equals($this->type, $other->type)
            && $this->defaultValue === $other->defaultValue;
    }

    public function getMethodSynopsisType(): Type {
        if ($this->type) {
            return $this->type;
        }

        if ($this->phpDocType) {
            return $this->phpDocType;
        }

        throw new Exception("A parameter must have a type");
    }

    public function hasProperDefaultValue(): bool {
        return $this->defaultValue !== null && $this->defaultValue !== "UNKNOWN";
    }

    private function getDefaultValueAsArginfoString(): string {
        if ($this->hasProperDefaultValue()) {
            return '"' . addslashes($this->defaultValue) . '"';
        }

        return "NULL";
    }

    public function getDefaultValueAsMethodSynopsisString(): ?string {
        return match ($this->defaultValue) {
            'UNKNOWN' => null,
            'false' | 'true' | 'null' => "&{$this->defaultValue};",
            default => $this->defaultValue,
        };
    }

    public function toZendInfo(): string {
        $argKind = $this->isVariadic ? "ARG_VARIADIC" : "ARG";
        $argDefaultKind = $this->hasProperDefaultValue() ? "_WITH_DEFAULT_VALUE" : "";
        $argType = $this->type;
        if ($argType !== null) {
            if (null !== $simpleArgType = $argType->tryToSimpleType()) {
                if ($simpleArgType->isBuiltin) {
                    return sprintf(
                        "\tZEND_%s_TYPE_INFO%s(%s, %s, %s, %d%s)\n",
                        $argKind, $argDefaultKind, $this->sendBy, $this->name,
                        $simpleArgType->toTypeCode(), $argType->isNullable(),
                        $this->hasProperDefaultValue() ? ", " . $this->getDefaultValueAsArginfoString() : ""
                    );
                }
                return sprintf(
                    "\tZEND_%s_OBJ_INFO%s(%s, %s, %s, %d%s)\n",
                    $argKind, $argDefaultKind, $this->sendBy, $this->name,
                    $simpleArgType->toEscapedName(), $argType->isNullable(),
                    $this->hasProperDefaultValue() ? ", " . $this->getDefaultValueAsArginfoString() : ""
                );
            }
            $arginfoType = $argType->toArginfoType();
            if ($arginfoType->hasClassType()) {
                return sprintf(
                    "\tZEND_%s_OBJ_TYPE_MASK(%s, %s, %s, %s%s)\n",
                    $argKind, $this->sendBy, $this->name,
                    $arginfoType->toClassTypeString(), $arginfoType->toTypeMask(),
                    !$this->isVariadic ? ", " . $this->getDefaultValueAsArginfoString() : ""
                );
            }
            return sprintf(
                "\tZEND_%s_TYPE_MASK(%s, %s, %s, %s)\n",
                $argKind, $this->sendBy, $this->name,
                $arginfoType->toTypeMask(),
                $this->getDefaultValueAsArginfoString()
            );
        }
        return sprintf(
            "\tZEND_%s_INFO%s(%s, %s%s)\n",
            $argKind, $argDefaultKind, $this->sendBy, $this->name,
            $this->hasProperDefaultValue() ? ", " . $this->getDefaultValueAsArginfoString() : ""
        );
    }
}

interface VariableLikeName {
    public function __toString(): string;
    public function getDeclarationName(): string;
}

abstract class AbstractConstName implements VariableLikeName
{
    public function isUnknown(): bool
    {
        return strtolower($this->__toString()) === "unknown";
    }
}

class ConstName extends AbstractConstName {
    private readonly string $const;

    public function __construct(?Name $namespace, string $const)
    {
        if ($namespace && ($namespace = $namespace->slice(0, -1))) {
            $const = $namespace->toString() . '\\' . $const;
        }
        $this->const = $const;
    }

    public function isUnknown(): bool
    {
        $name = $this->__toString();
        if (($pos = strrpos($name, '\\')) !== false) {
            $name = substr($name, $pos + 1);
        }
        return strtolower($name) === "unknown";
    }

    public function __toString(): string
    {
        return $this->const;
    }

    public function getDeclarationName(): string
    {
        return $this->name->toString();
    }
}

class ClassConstName extends AbstractConstName {

    public function __construct(
        public readonly Name $class,
        private readonly string $const,
    ) {}

    public function __toString(): string
    {
        return $this->class->toString() . "::" . $this->const;
    }

    public function getDeclarationName(): string
    {
        return $this->const;
    }
}

class PropertyName implements VariableLikeName {

    public function __construct(
        public readonly Name $class,
        private readonly string $property
    ) {}

    public function __toString(): string
    {
        return $this->class->toString() . "::$" . $this->property;
    }

    public function getDeclarationName(): string
    {
        return $this->property;
    }
}

class EnumCaseName {
    public function __construct(
        public readonly Name $enum,
        public readonly string $case
    ) {
    }

    public function __toString(): string
    {
        return "$this->enum::$this->case";
    }
}

interface FunctionOrMethodName {
    public function getDeclaration(): string;
    public function getArgInfoName(): string;
    public function getMethodSynopsisFilename(): string;
    public function getNameForAttributes(): string;
    public function __toString(): string;
    public function isConstructor(): bool;
    public function isDestructor(): bool;
}

class FunctionName implements FunctionOrMethodName {

    public function __construct(
        private readonly Name $name,
    ) {}

    public function getNamespace(): ?string {
        if ($this->name->isQualified()) {
            return $this->name->slice(0, -1)->toString();
        }
        return null;
    }

    public function getNonNamespacedName(): string {
        if ($this->name->isQualified()) {
            throw new Exception("Namespaced name not supported here");
        }
        return $this->name->toString();
    }

    public function getDeclarationName(): string {
        return implode('_', $this->name->getParts());
    }

    public function getFunctionName(): string {
        return $this->name->getLast();
    }

    public function getDeclaration(): string {
        return "ZEND_FUNCTION({$this->getDeclarationName()});\n";
    }

    public function getArgInfoName(): string {
        $underscoreName = implode('_', $this->name->getParts());
        return "arginfo_$underscoreName";
    }

    public function getFramelessFunctionInfosName(): string {
        $underscoreName = implode('_', $this->name->getParts());
        return "frameless_function_infos_$underscoreName";
    }

    public function getMethodSynopsisFilename(): string {
        return 'functions/' . implode('/', str_replace('_', '-', $this->name->getParts()));
    }

    public function getNameForAttributes(): string {
        return strtolower($this->name->toString());
    }

    public function __toString(): string {
        return $this->name->toString();
    }

    public function isConstructor(): bool {
        return false;
    }

    public function isDestructor(): bool {
        return false;
    }
}

class MethodName implements FunctionOrMethodName {

    public function __construct(
        public readonly Name $className,
        public readonly string $methodName,
    ) {}

    public function getDeclarationClassName(): string {
        return implode('_', $this->className->getParts());
    }

    public function getDeclaration(): string {
        return "ZEND_METHOD({$this->getDeclarationClassName()}, $this->methodName);\n";
    }

    public function getArgInfoName(): string {
        return "arginfo_class_{$this->getDeclarationClassName()}_{$this->methodName}";
    }

    public function getMethodSynopsisFilename(): string
    {
        $parts = [...$this->className->getParts(), ltrim($this->methodName, '_')];
        /* File paths are in lowercase */
        return strtolower(implode('/', $parts));
    }

    public function getNameForAttributes(): string {
        return strtolower($this->methodName);
    }

    public function __toString(): string {
        return "$this->className::$this->methodName";
    }

    public function isConstructor(): bool {
        return $this->methodName === "__construct";
    }

    public function isDestructor(): bool {
        return $this->methodName === "__destruct";
    }
}

class ReturnInfo {
    public const REFCOUNT_0 = "0";
    public const REFCOUNT_1 = "1";
    public const REFCOUNT_N = "N";

    public const REFCOUNTS_NONSCALAR = [
        self::REFCOUNT_1,
        self::REFCOUNT_N,
    ];

    public readonly string $refcount;

    public function __construct(
        private readonly bool $byRef,
        // NOT readonly - gets removed when discarding info for older PHP versions
        public ?Type $type,
        public readonly ?Type $phpDocType,
        public readonly bool $tentativeReturnType,
        ?string $refcount
    ) {
        $this->setRefcount($refcount);
    }

    public function equalsApartFromPhpDocAndRefcount(ReturnInfo $other): bool {
        return $this->byRef === $other->byRef
            && Type::equals($this->type, $other->type)
            && $this->tentativeReturnType === $other->tentativeReturnType;
    }

    public function getMethodSynopsisType(): ?Type {
        return $this->type ?? $this->phpDocType;
    }

    private function setRefcount(?string $refcount): void
    {
        $type = $this->phpDocType ?? $this->type;
        $isScalarType = $type !== null && $type->isScalar();

        if ($refcount === null) {
            $this->refcount = $isScalarType ? self::REFCOUNT_0 : self::REFCOUNT_N;
            return;
        }

        if ($isScalarType) {
            throw new Exception(
                "@refcount on functions returning scalar values is redundant and not permitted"
            );
        }

        if (!in_array($refcount, ReturnInfo::REFCOUNTS_NONSCALAR, true)) {
            throw new Exception("@refcount must have one of the following values: \"1\", \"N\", $refcount given");
        }

        $this->refcount = $refcount;
    }

    public function beginArgInfo(string $funcInfoName, int $minArgs, bool $php81MinimumCompatibility): string {
        $code = $this->beginArgInfoCompatible($funcInfoName, $minArgs);
        if ($this->type !== null && $this->tentativeReturnType && !$php81MinimumCompatibility) {
            $realCode = "#if (PHP_VERSION_ID >= " . PHP_81_VERSION_ID . ")\n";
            $realCode .= $code;
            $realCode .= sprintf(
                "#else\nZEND_BEGIN_ARG_INFO_EX(%s, 0, %d, %d)\n#endif\n",
                $funcInfoName, $this->byRef, $minArgs
            );
            return $realCode;
        }
        return $code;
    }

    /**
     * Assumes PHP 8.1 compatibility, if that is not the case the caller is
     * responsible for making the use of a tentative return type conditional
     * based on the PHP version. Separate to allow using early returns
     */
    private function beginArgInfoCompatible(string $funcInfoName, int $minArgs): string {
        if ($this->type !== null) {
            if (null !== $simpleReturnType = $this->type->tryToSimpleType()) {
                if ($simpleReturnType->isBuiltin) {
                    return sprintf(
                        "%s(%s, %d, %d, %s, %d)\n",
                        $this->tentativeReturnType ? "ZEND_BEGIN_ARG_WITH_TENTATIVE_RETURN_TYPE_INFO_EX" : "ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX",
                        $funcInfoName, $this->byRef,
                        $minArgs,
                        $simpleReturnType->toTypeCode(), $this->type->isNullable()
                    );
                }
                return sprintf(
                    "%s(%s, %d, %d, %s, %d)\n",
                    $this->tentativeReturnType ? "ZEND_BEGIN_ARG_WITH_TENTATIVE_RETURN_OBJ_INFO_EX" : "ZEND_BEGIN_ARG_WITH_RETURN_OBJ_INFO_EX",
                    $funcInfoName, $this->byRef,
                    $minArgs,
                    $simpleReturnType->toEscapedName(), $this->type->isNullable()
                );
            }
            $arginfoType = $this->type->toArginfoType();
            if ($arginfoType->hasClassType()) {
                return sprintf(
                    "%s(%s, %d, %d, %s, %s)\n",
                    $this->tentativeReturnType ? "ZEND_BEGIN_ARG_WITH_TENTATIVE_RETURN_OBJ_TYPE_MASK_EX" : "ZEND_BEGIN_ARG_WITH_RETURN_OBJ_TYPE_MASK_EX",
                    $funcInfoName, $this->byRef,
                    $minArgs,
                    $arginfoType->toClassTypeString(), $arginfoType->toTypeMask()
                );
            }
            return sprintf(
                "%s(%s, %d, %d, %s)\n",
                $this->tentativeReturnType ? "ZEND_BEGIN_ARG_WITH_TENTATIVE_RETURN_TYPE_MASK_EX" : "ZEND_BEGIN_ARG_WITH_RETURN_TYPE_MASK_EX",
                $funcInfoName, $this->byRef,
                $minArgs,
                $arginfoType->toTypeMask()
            );
        }
        return sprintf(
            "ZEND_BEGIN_ARG_INFO_EX(%s, 0, %d, %d)\n",
            $funcInfoName, $this->byRef, $minArgs
        );
    }
}

class VersionFlags {

    /**
     * Keys are the PHP versions, values are arrays of flags
     */
    private array $flagsByVersion;

    public function __construct(array $baseFlags) {
        $this->flagsByVersion = [];
        foreach (ALL_PHP_VERSION_IDS as $version) {
            $this->flagsByVersion[$version] = $baseFlags;
        }
    }

    public function addForVersionsAbove(string $flag, int $minimumVersionId): void {
        $write = false;

        foreach (ALL_PHP_VERSION_IDS as $version) {
            if ($version === $minimumVersionId || $write === true) {
                $this->flagsByVersion[$version][] = $flag;
                $write = true;
            }
        }
    }

    public function isEmpty(): bool {
        return !array_any(
            ALL_PHP_VERSION_IDS,
            fn (int $version): bool => $this->flagsByVersion[$version] !== []
        );
    }

    public function generateVersionDependentFlagCode(
        string $codeTemplate,
        ?int $phpVersionIdMinimumCompatibility,
        ?int $phpVersionIdMaxCompatibility = null
    ): string {
        $flagsByPhpVersions = $this->flagsByVersion;
        $phpVersions = ALL_PHP_VERSION_IDS;
        sort($phpVersions);
        $currentPhpVersion = end($phpVersions);

        // No version compatibility is needed
        if ($phpVersionIdMinimumCompatibility === null) {
            if (empty($flagsByPhpVersions[$currentPhpVersion])) {
                return '';
            }
            return sprintf($codeTemplate, implode("|", $flagsByPhpVersions[$currentPhpVersion]));
        }

        ksort($flagsByPhpVersions);
        // Remove flags which depend on a PHP version below the minimally supported one
        $index = array_search($phpVersionIdMinimumCompatibility, array_keys($flagsByPhpVersions));
        if ($index === false) {
            throw new Exception("Missing version dependent flags for PHP version ID \"$phpVersionIdMinimumCompatibility\"");
        }
        $flagsByPhpVersions = array_slice($flagsByPhpVersions, $index, null, true);
        if ($phpVersionIdMaxCompatibility !== null) {
            // Remove flags which depend on a PHP version above the maximally supported one
            $index = array_search($phpVersionIdMaxCompatibility, array_keys($flagsByPhpVersions));
            if ($index === false) {
                throw new Exception("Missing version dependent flags for PHP version ID \"$phpVersionIdMaxCompatibility\"");
            }
            $flagsByPhpVersions = array_slice($flagsByPhpVersions, 0, $index, true);
        }

        // Remove version-specific flags which don't differ from the previous one
        // Also populate '0' values
        $previousVersionId = null;
        foreach ($flagsByPhpVersions as $versionId => $versionFlags) {
            if ($versionFlags === []) {
                $versionFlags = ['0'];
                $flagsByPhpVersions[$versionId] = ['0'];
            }
            if ($previousVersionId !== null && $flagsByPhpVersions[$previousVersionId] === $versionFlags) {
                unset($flagsByPhpVersions[$versionId]);
            } else {
                $previousVersionId = $versionId;
            }
        }

        $flagCount = count($flagsByPhpVersions);

        // Do not add a condition unnecessarily when the only version is the same as the minimally supported one
        if ($flagCount === 1) {
            reset($flagsByPhpVersions);
            $firstVersion = key($flagsByPhpVersions);
            if ($firstVersion === $phpVersionIdMinimumCompatibility) {
                return sprintf($codeTemplate, implode("|", reset($flagsByPhpVersions)));
            }
        }

        // Add the necessary conditions around the code using the version-specific flags
        $code = '';
        $i = 0;
        foreach (array_reverse($flagsByPhpVersions, true) as $version => $versionFlags) {
            $if = $i === 0 ? "#if" : "#elif";
            $endif = $i === $flagCount - 1 ? "#endif\n" : "";

            $code .= "$if (PHP_VERSION_ID >= $version)\n";

            $code .= sprintf($codeTemplate, implode("|", $versionFlags));
            $code .= $endif;

            $i++;
        }

        return $code;
    }
}

class FuncInfo {

    /**
     * @param ArgInfo[] $args
     * @param AttributeInfo[] $attributes
     * @param FramelessFunctionInfo[] $framelessFunctionInfos
     */
    public function __construct(
        public readonly FunctionOrMethodName $name,
        private readonly int $classFlags,
        public int $flags,
        public readonly ?string $aliasType,
        public ?FunctionOrMethodName $alias,
        private readonly bool $isDeprecated,
        private bool $supportsCompileTimeEval,
        public readonly bool $verify,
        public /* readonly */ array $args,
        public /* readonly */ ReturnInfo $return,
        private readonly int $numRequiredArgs,
        public readonly ?string $cond,
        public bool $isUndocumentable,
        private ?int $minimumPhpVersionIdCompatibility,
        public array $attributes,
        private array $framelessFunctionInfos,
        private ?ExposedDocComment $exposedDocComment,
    ) {
        if ($return->tentativeReturnType && $this->isFinalMethod()) {
            throw new Exception("Tentative return inapplicable for final method");
        }
    }

    public function isMethod(): bool
    {
        return $this->name instanceof MethodName;
    }

    private function isFinalMethod(): bool
    {
        return ($this->flags & Modifiers::FINAL) || ($this->classFlags & Modifiers::FINAL);
    }

    public function isInstanceMethod(): bool
    {
        return !($this->flags & Modifiers::STATIC) && $this->isMethod() && !$this->name->isConstructor();
    }

    /** @return string[] */
    private function getModifierNames(): array
    {
        if (!$this->isMethod()) {
            return [];
        }

        $result = [];

        if ($this->flags & Modifiers::FINAL) {
            $result[] = "final";
        } elseif ($this->flags & Modifiers::ABSTRACT && $this->classFlags & ~Modifiers::ABSTRACT) {
            $result[] = "abstract";
        }

        if ($this->flags & Modifiers::PROTECTED) {
            $result[] = "protected";
        } elseif ($this->flags & Modifiers::PRIVATE) {
            $result[] = "private";
        } else {
            $result[] = "public";
        }

        if ($this->flags & Modifiers::STATIC) {
            $result[] = "static";
        }

        return $result;
    }

    private function hasParamWithUnknownDefaultValue(): bool
    {
        return array_any(
            $this->args,
            static fn (ArgInfo $arg): bool => $arg->defaultValue && !$arg->hasProperDefaultValue()
        );
    }

    private function equalsApartFromNameAndRefcount(FuncInfo $other): bool {
        if (count($this->args) !== count($other->args)) {
            return false;
        }

        for ($i = 0; $i < count($this->args); $i++) {
            if (!$this->args[$i]->equals($other->args[$i])) {
                return false;
            }
        }

        return $this->return->equalsApartFromPhpDocAndRefcount($other->return)
            && $this->numRequiredArgs === $other->numRequiredArgs
            && $this->cond === $other->cond;
    }

    public function getArgInfoName(): string {
        return $this->name->getArgInfoName();
    }

    public function getDeclarationKey(): string
    {
        $name = $this->alias ?? $this->name;

        return "$name|$this->cond";
    }

    public function getDeclaration(): ?string
    {
        if ($this->flags & Modifiers::ABSTRACT) {
            return null;
        }

        $name = $this->alias ?? $this->name;

        return $name->getDeclaration();
    }

    public function getFramelessDeclaration(): ?string {
        if (empty($this->framelessFunctionInfos)) {
            return null;
        }

        $code = '';
        $infos = '';
        foreach ($this->framelessFunctionInfos as $framelessFunctionInfo) {
            $code .= "ZEND_FRAMELESS_FUNCTION({$this->name->getFunctionName()}, {$framelessFunctionInfo->arity});\n";
            $infos .= "\t{ ZEND_FRAMELESS_FUNCTION_NAME({$this->name->getFunctionName()}, {$framelessFunctionInfo->arity}), {$framelessFunctionInfo->arity} },\n";
        }

        $code .= 'static const zend_frameless_function_info ' . $this->getFramelessFunctionInfosName() . "[] = {\n";
        $code .= $infos;
        $code .= "\t{ 0 },\n";
        $code .= "};\n";

        $php84MinimumCompatibility = $this->minimumPhpVersionIdCompatibility === null || $this->minimumPhpVersionIdCompatibility >= PHP_84_VERSION_ID;
        if (!$php84MinimumCompatibility) {
            return "#if (PHP_VERSION_ID >= " . PHP_84_VERSION_ID . ")\n$code#endif\n";
        }

        return $code;
    }

    private function getFramelessFunctionInfosName(): string {
        return $this->name->getFramelessFunctionInfosName();
    }

    public function getFunctionEntry(): string {
        if (!empty($this->framelessFunctionInfos)) {
            if ($this->isMethod()) {
                throw new Exception('Frameless methods are not supported yet');
            }
            if ($this->name->getNamespace()) {
                throw new Exception('Namespaced direct calls to frameless functions are not supported yet');
            }
            if ($this->alias) {
                throw new Exception('Aliased direct calls to frameless functions are not supported yet');
            }
        }

        $isVanillaEntry = $this->alias === null && !$this->supportsCompileTimeEval && $this->exposedDocComment === null && empty($this->framelessFunctionInfos);
        $argInfoName = $this->getArgInfoName();
        $flagsByPhpVersions = $this->getArginfoFlagsByPhpVersions();

        if ($this->isMethod()) {
            $zendName = '"' . $this->name->methodName . '"';
            if ($this->alias) {
                if ($this->alias instanceof MethodName) {
                    $name = "zim_" . $this->alias->getDeclarationClassName() . "_" . $this->alias->methodName;
                } else if ($this->alias instanceof FunctionName) {
                    $name = "zif_" . $this->alias->getNonNamespacedName();
                } else {
                    throw new Error("Cannot happen");
                }
            } elseif ($this->flags & Modifiers::ABSTRACT) {
                $name = "NULL";
            } else {
                $name = "zim_" . $this->name->getDeclarationClassName() . "_" . $this->name->methodName;

                if ($isVanillaEntry) {
                    $template = "\tZEND_ME(" . $this->name->getDeclarationClassName() . ", " . $this->name->methodName . ", $argInfoName, %s)\n";
                    $flagsCode = $flagsByPhpVersions->generateVersionDependentFlagCode(
                        $template,
                        $this->minimumPhpVersionIdCompatibility
                    );
                    return rtrim($flagsCode) . "\n";
                }
            }
        } else if ($this->name instanceof FunctionName) {
            $functionName = $this->name->getFunctionName();
            $declarationName = $this->alias ? $this->alias->getNonNamespacedName() : $this->name->getDeclarationName();
            $name = "zif_$declarationName";

            if ($this->name->getNamespace()) {
                $namespace = addslashes($this->name->getNamespace());
                $zendName = "ZEND_NS_NAME(\"$namespace\", \"$functionName\")";
            } else {
                // Can only use ZEND_FE() if we have no flags for *all* versions
                if ($isVanillaEntry && $flagsByPhpVersions->isEmpty()) {
                    return "\tZEND_FE($declarationName, $argInfoName)\n";
                }
                $zendName = '"' . $functionName . '"';
            }
        } else {
            throw new Error("Cannot happen");
        }

        $docComment = $this->exposedDocComment ? '"' . $this->exposedDocComment->escape() . '"' : "NULL";
        $framelessFuncInfosName = !empty($this->framelessFunctionInfos) ? $this->getFramelessFunctionInfosName() : "NULL";

        // Assume 8.4+ here, if older versions are supported this is conditional
        $code = $flagsByPhpVersions->generateVersionDependentFlagCode(
            "\tZEND_RAW_FENTRY($zendName, $name, $argInfoName, %s, $framelessFuncInfosName, $docComment)\n",
            PHP_84_VERSION_ID
        );

        $php84MinimumCompatibility = $this->minimumPhpVersionIdCompatibility === null || $this->minimumPhpVersionIdCompatibility >= PHP_84_VERSION_ID;
        if (!$php84MinimumCompatibility) {
            $code = "#if (PHP_VERSION_ID >= " . PHP_84_VERSION_ID . ")\n$code";
            $code .= "#else\n";

            $code .= $flagsByPhpVersions->generateVersionDependentFlagCode(
                "\tZEND_RAW_FENTRY($zendName, $name, $argInfoName, %s)\n",
                $this->minimumPhpVersionIdCompatibility,
                PHP_83_VERSION_ID
            );

            $code .= "#endif\n";
        }

        return $code;
    }

    public function getOptimizerInfo(): ?string {
        if ($this->isMethod()) {
            return null;
        }

        if ($this->alias !== null) {
            return null;
        }

        if ($this->return->refcount !== ReturnInfo::REFCOUNT_1 && $this->return->phpDocType === null) {
            return null;
        }

        $type = $this->return->phpDocType ?? $this->return->type;
        if ($type === null) {
            return null;
        }

        return "\tF" . $this->return->refcount . '("' . addslashes($this->name->__toString()) . '", ' . $type->toOptimizerTypeMask() . "),\n";
    }

    public function discardInfoForOldPhpVersions(?int $minimumPhpVersionIdCompatibility): void {
        $this->attributes = [];
        $this->return->type = null;
        $this->framelessFunctionInfos = [];
        $this->exposedDocComment = null;
        $this->supportsCompileTimeEval = false;
        foreach ($this->args as $arg) {
            $arg->type = null;
            $arg->defaultValue = null;
            $arg->attributes = [];
        }
        $this->minimumPhpVersionIdCompatibility = $minimumPhpVersionIdCompatibility;
    }

    private function getArginfoFlagsByPhpVersions(): VersionFlags
    {
        $flags = [];

        if ($this->isMethod()) {
            if ($this->flags & Modifiers::PROTECTED) {
                $flags[] = "ZEND_ACC_PROTECTED";
            } elseif ($this->flags & Modifiers::PRIVATE) {
                $flags[] = "ZEND_ACC_PRIVATE";
            } else {
                $flags[] = "ZEND_ACC_PUBLIC";
            }

            if ($this->flags & Modifiers::STATIC) {
                $flags[] = "ZEND_ACC_STATIC";
            }

            if ($this->flags & Modifiers::FINAL) {
                $flags[] = "ZEND_ACC_FINAL";
            }

            if ($this->flags & Modifiers::ABSTRACT) {
                $flags[] = "ZEND_ACC_ABSTRACT";
            }
        }

        if ($this->isDeprecated) {
            $flags[] = "ZEND_ACC_DEPRECATED";
        }

        if (array_any(
            $this->attributes,
            static fn (AttributeInfo $attr): bool => $attr->class === "Deprecated"
        )) {
            $flags[] = "ZEND_ACC_DEPRECATED";
        }

        $flags = new VersionFlags($flags);

        if ($this->isMethod() === false && $this->supportsCompileTimeEval) {
            $flags->addForVersionsAbove("ZEND_ACC_COMPILE_TIME_EVAL", PHP_82_VERSION_ID);
        }

        if (array_any(
            $this->attributes,
            static fn (AttributeInfo $attr): bool => $attr->class === "NoDiscard"
        )) {
            $flags->addForVersionsAbove("ZEND_ACC_NODISCARD", PHP_85_VERSION_ID);
        }

        return $flags;
    }

    private function generateRefSect1(DOMDocument $doc, string $role): DOMElement {
        $refSec = $doc->createElement('refsect1');
        $refSec->setAttribute('role', $role);
        $refSec->append(
            "\n  ",
            $doc->createEntityReference('reftitle.' . $role),
            "\n  "
        );
        return $refSec;
    }

    public function getMethodSynopsisDocument(): ?string {
        $REFSEC1_SEPARATOR = "\n\n ";

        $doc = new DOMDocument("1.0", "utf-8");
        $doc->formatOutput = true;

        $refentry = $doc->createElement('refentry');
        $doc->appendChild($refentry);

        if ($this->isMethod()) {
            assert($this->name instanceof MethodName);
            /* Namespaces are separated by '-', '_' must be converted to '-' too.
             * Trim away the __ for magic methods */
            $id = strtolower(
                str_replace('\\', '-', $this->name->className->__toString())
                . '.'
                . str_replace('_', '-', ltrim($this->name->methodName, '_'))
            );
        } else {
            $id = 'function.' . strtolower(str_replace('_', '-', $this->name->__toString()));
        }
        $refentry->setAttribute("xml:id", $id);
        /* We create an attribute for xmlns, as libxml otherwise force it to be the first one */
        //$refentry->setAttribute("xmlns", "http://docbook.org/ns/docbook");
        $namespace = $doc->createAttribute('xmlns');
        $namespace->value = "http://docbook.org/ns/docbook";
        $refentry->setAttributeNode($namespace);
        $refentry->setAttribute("xmlns:xlink", "http://www.w3.org/1999/xlink");
        $refentry->appendChild(new DOMText("\n "));

        /* Creation of <refnamediv> */
        $refnamediv = $doc->createElement('refnamediv');
        $refnamediv->appendChild(new DOMText("\n  "));
        $refname = $doc->createElement('refname', $this->name->__toString());
        $refnamediv->appendChild($refname);
        $refnamediv->appendChild(new DOMText("\n  "));
        $refpurpose = $doc->createElement('refpurpose', 'Description');
        $refnamediv->appendChild($refpurpose);

        $refnamediv->appendChild(new DOMText("\n "));
        $refentry->append($refnamediv, $REFSEC1_SEPARATOR);

        /* Creation of <refsect1 role="description"> */
        $descriptionRefSec = $this->generateRefSect1($doc, 'description');

        $methodSynopsis = $this->getMethodSynopsisElement($doc);
        if (!$methodSynopsis) {
            return null;
        }
        $descriptionRefSec->appendChild($methodSynopsis);
        $descriptionRefSec->appendChild(new DOMText("\n  "));
        $undocumentedEntity = $doc->createEntityReference('warn.undocumented.func');
        $descriptionRefSec->appendChild($undocumentedEntity);
        $descriptionRefSec->appendChild(new DOMText("\n  "));
        $returnDescriptionPara = $doc->createElement('simpara');
        $returnDescriptionPara->appendChild(new DOMText("\n   Description.\n  "));
        $descriptionRefSec->appendChild($returnDescriptionPara);

        $descriptionRefSec->appendChild(new DOMText("\n "));
        $refentry->append($descriptionRefSec, $REFSEC1_SEPARATOR);

        /* Creation of <refsect1 role="parameters"> */
        $parametersRefSec = $this->getParameterSection($doc);
        $refentry->append($parametersRefSec, $REFSEC1_SEPARATOR);

        /* Creation of <refsect1 role="returnvalues"> */
        if (!$this->name->isConstructor() && !$this->name->isDestructor()) {
            $returnRefSec = $this->getReturnValueSection($doc);
            $refentry->append($returnRefSec, $REFSEC1_SEPARATOR);
        }

        /* Creation of <refsect1 role="errors"> */
        $errorsRefSec = $this->generateRefSect1($doc, 'errors');
        $errorsDescriptionParaConstantTag = $doc->createElement('constant');
        $errorsDescriptionParaConstantTag->append('E_*');
        $errorsDescriptionParaExceptionTag = $doc->createElement('exceptionname');
        $errorsDescriptionParaExceptionTag->append('Exception');
        $errorsDescriptionPara = $doc->createElement('simpara');
        $errorsDescriptionPara->append(
            "\n   When does this function issue ",
            $errorsDescriptionParaConstantTag,
            " level errors,\n   and/or throw ",
            $errorsDescriptionParaExceptionTag,
            "s.\n  "
        );
        $errorsRefSec->appendChild($errorsDescriptionPara);
        $errorsRefSec->appendChild(new DOMText("\n "));

        $refentry->append($errorsRefSec, $REFSEC1_SEPARATOR);

        /* Creation of <refsect1 role="changelog"> */
        $changelogRefSec = $this->getChangelogSection($doc);
        $refentry->append($changelogRefSec, $REFSEC1_SEPARATOR);

        $exampleRefSec = $this->getExampleSection($doc, $id);
        $refentry->append($exampleRefSec, $REFSEC1_SEPARATOR);

        /* Creation of <refsect1 role="notes"> */
        $notesRefSec = $this->generateRefSect1($doc, 'notes');

        $noteTagSimara = $doc->createElement('simpara');
        $noteTagSimara->append(
            "\n    Any notes that don't fit anywhere else should go here.\n   "
        );
        $noteTag = $doc->createElement('note');
        $noteTag->append("\n   ", $noteTagSimara, "\n  ");
        $notesRefSec->append($noteTag, "\n ");

        $refentry->append($notesRefSec, $REFSEC1_SEPARATOR);

        /* Creation of <refsect1 role="seealso"> */
        $seeAlsoRefSec = $this->generateRefSect1($doc, 'seealso');

        $seeAlsoMemberClassMethod = $doc->createElement('member');
        $seeAlsoMemberClassMethodTag = $doc->createElement('methodname');
        $seeAlsoMemberClassMethodTag->appendChild(new DOMText("ClassName::otherMethodName"));
        $seeAlsoMemberClassMethod->appendChild($seeAlsoMemberClassMethodTag);

        $seeAlsoMemberFunction = $doc->createElement('member');
        $seeAlsoMemberFunctionTag = $doc->createElement('function');
        $seeAlsoMemberFunctionTag->appendChild(new DOMText("some_function"));
        $seeAlsoMemberFunction->appendChild($seeAlsoMemberFunctionTag);

        $seeAlsoMemberLink = $doc->createElement('member');
        $seeAlsoMemberLinkTag = $doc->createElement('link');
        $seeAlsoMemberLinkTag->setAttribute('linkend', 'some.id.chunk.to.link');
        $seeAlsoMemberLinkTag->appendChild(new DOMText('something appendix'));
        $seeAlsoMemberLink->appendChild($seeAlsoMemberLinkTag);

        $seeAlsoList = $doc->createElement('simplelist');
        $seeAlsoList->append(
            "\n   ",
            $seeAlsoMemberClassMethod,
            "\n   ",
            $seeAlsoMemberFunction,
            "\n   ",
            $seeAlsoMemberLink,
            "\n  "
        );

        $seeAlsoRefSec->appendChild($seeAlsoList);
        $seeAlsoRefSec->appendChild(new DOMText("\n "));

        $refentry->appendChild($seeAlsoRefSec);

        $refentry->appendChild(new DOMText("\n\n"));

        $doc->appendChild(new DOMComment(
            <<<ENDCOMMENT
 Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1

ENDCOMMENT
        ));
        return $doc->saveXML();
    }

    private function getParameterSection(DOMDocument $doc): DOMElement {
        $parametersRefSec = $this->generateRefSect1($doc, 'parameters');
        if (empty($this->args)) {
            $noParamEntity = $doc->createEntityReference('no.function.parameters');
            $parametersRefSec->appendChild($noParamEntity);
            return $parametersRefSec;
        }
        $parametersContainer = $doc->createDocumentFragment();

        $parametersContainer->appendChild(new DOMText("\n  "));
        $parametersList = $doc->createElement('variablelist');
        $parametersContainer->appendChild($parametersList);

        /*
        <varlistentry>
            <term><parameter>name</parameter></term>
            <listitem>
            <simpara>
            Description.
            </simpara>
            </listitem>
        </varlistentry>
        */
        foreach ($this->args as $arg) {
            $parameter = $doc->createElement('parameter', $arg->name);
            $parameterTerm = $doc->createElement('term');
            $parameterTerm->appendChild($parameter);

            $listItemPara = $doc->createElement('simpara');
            $listItemPara->append(
                "\n      ",
                "Description.",
                "\n     ",
            );

            $parameterEntryListItem = $doc->createElement('listitem');
            $parameterEntryListItem->append(
                "\n     ",
                $listItemPara,
                "\n    ",
            );

            $parameterEntry = $doc->createElement('varlistentry');
            $parameterEntry->append(
                "\n    ",
                $parameterTerm,
                "\n    ",
                $parameterEntryListItem,
                "\n   ",
            );

            $parametersList->appendChild(new DOMText("\n   "));
            $parametersList->appendChild($parameterEntry);
        }
        $parametersList->appendChild(new DOMText("\n  "));

        $parametersContainer->appendChild(new DOMText("\n "));
        $parametersRefSec->appendChild($parametersContainer);
        $parametersRefSec->appendChild(new DOMText("\n "));
        return $parametersRefSec;
    }

    private function getReturnValueSection(DOMDocument $doc): DOMElement {
        $returnRefSec = $this->generateRefSect1($doc, 'returnvalues');

        $returnDescriptionPara = $doc->createElement('simpara');
        $returnDescriptionPara->appendChild(new DOMText("\n   "));

        $returnType = $this->return->getMethodSynopsisType();
        if ($returnType === null) {
            $returnDescriptionPara->appendChild(new DOMText("Description."));
        } else if (count($returnType->types) === 1) {
            $type = $returnType->types[0];

            $descriptionNode = match ($type->name) {
                'void' => $doc->createEntityReference('return.void'),
                'true' => $doc->createEntityReference('return.true.always'),
                'bool' => $doc->createEntityReference('return.success'),
                default => new DOMText("Description."),
            };
            $returnDescriptionPara->appendChild($descriptionNode);
        } else {
            $returnDescriptionPara->appendChild(new DOMText("Description."));
        }
        $returnDescriptionPara->appendChild(new DOMText("\n  "));
        $returnRefSec->appendChild($returnDescriptionPara);
        $returnRefSec->appendChild(new DOMText("\n "));
        return $returnRefSec;
    }

    /**
     * @param array<DOMNode> $headers [count($headers) === $columns]
     * @param array<array<DOMNode>> $rows [count($rows[$i]) === $columns]
     */
    private function generateDocbookInformalTable(
        DOMDocument $doc,
        int $indent,
        int $columns,
        array $headers,
        array $rows
    ): DOMElement {
        $strIndent = str_repeat(' ', $indent);

        $headerRow = $doc->createElement('row');
        foreach ($headers as $header) {
            $headerEntry = $doc->createElement('entry');
            $headerEntry->appendChild($header);

            $headerRow->append("\n$strIndent    ", $headerEntry);
        }
        $headerRow->append("\n$strIndent   ");

        $thead = $doc->createElement('thead');
        $thead->append(
            "\n$strIndent   ",
            $headerRow,
            "\n$strIndent  ",
        );

        $tbody = $doc->createElement('tbody');
        foreach ($rows as $row) {
            $bodyRow = $doc->createElement('row');
            foreach ($row as $cell) {
                $entry = $doc->createElement('entry');
                $entry->appendChild($cell);

                $bodyRow->appendChild(new DOMText("\n$strIndent    "));
                $bodyRow->appendChild($entry);
            }
            $bodyRow->appendChild(new DOMText("\n$strIndent   "));

            $tbody->append(
                "\n$strIndent   ",
                $bodyRow,
                "\n$strIndent  ",
            );
        }

        $tgroup = $doc->createElement('tgroup');
        $tgroup->setAttribute('cols', (string) $columns);
        $tgroup->append(
            "\n$strIndent  ",
            $thead,
            "\n$strIndent  ",
            $tbody,
            "\n$strIndent ",
        );

        $table = $doc->createElement('informaltable');
        $table->append(
            "\n$strIndent ",
            $tgroup,
            "\n$strIndent",
        );

        return $table;
    }

    private function getChangelogSection(DOMDocument $doc): DOMElement {
        $refSec = $this->generateRefSect1($doc, 'changelog');
        $headers = [
            $doc->createEntityReference('Version'),
            $doc->createEntityReference('Description'),
        ];
        $rows = [[
            new DOMText('8.X.0'),
            new DOMText("\n       Description\n      "),
        ]];
        $table = $this->generateDocbookInformalTable(
            $doc,
            /* indent: */ 2,
            /* columns: */ 2,
            /* headers: */ $headers,
            /* rows: */ $rows
        );
        $refSec->appendChild($table);

        $refSec->appendChild(new DOMText("\n "));
        return $refSec;
    }

    private function getExampleSection(DOMDocument $doc, string $id): DOMElement {
        $refSec = $this->generateRefSect1($doc, 'examples');

        $example = $doc->createElement('example');
        $fnName = $this->name->__toString();
        $example->setAttribute('xml:id', $id . '.example.basic');

        $title = $doc->createElement('title');
        $fn = $doc->createElement($this->isMethod() ? 'methodname' : 'function');
        $fn->append($fnName);
        $title->append($fn, ' example');

        $example->append("\n   ", $title);

        $para = $doc->createElement('simpara');
        $para->append("\n    ", "Description.", "\n   ");
        $example->append("\n   ", $para);

        $prog = $doc->createElement('programlisting');
        $prog->setAttribute('role', 'php');
        // So that GitHub syntax highlighting doesn't treat the closing tag
        // in the DOMCdataSection as indication that it should stop syntax
        // highlighting, break it up
        $empty = '';
        $code = new DOMCdataSection(
            <<<CODE_EXAMPLE

<?php
echo "Code example";
?$empty>

CODE_EXAMPLE
        );
        $prog->append("\n");
        $prog->appendChild($code);
        $prog->append("\n   ");

        $example->append("\n   ", $prog);
        $example->append("\n   ", $doc->createEntityReference('example.outputs'));

        $output = new DOMCdataSection(
            <<<OUPUT_EXAMPLE

Code example

OUPUT_EXAMPLE
        );
        $screen = $doc->createElement('screen');
        $screen->append("\n");
        $screen->appendChild($output);
        $screen->append("\n   ");

        $example->append(
            "\n   ",
            $screen,
            "\n  ",
        );

        $refSec->append(
            $example,
            "\n ",
        );
        return $refSec;
    }

    public function getMethodSynopsisElement(DOMDocument $doc): ?DOMElement {
        if ($this->hasParamWithUnknownDefaultValue()) {
            return null;
        }

        if ($this->name->isConstructor()) {
            $synopsisType = "constructorsynopsis";
        } elseif ($this->name->isDestructor()) {
            $synopsisType = "destructorsynopsis";
        } else {
            $synopsisType = "methodsynopsis";
        }

        $methodSynopsis = $doc->createElement($synopsisType);

        if ($this->isMethod()) {
            assert($this->name instanceof MethodName);
            $role = $doc->createAttribute("role");
            $role->value = addslashes($this->name->className->__toString());
            $methodSynopsis->appendChild($role);
        }

        $methodSynopsis->appendChild(new DOMText("\n   "));

        foreach ($this->attributes as $attribute) {
            $modifier = $doc->createElement("modifier", "#[\\" . $attribute->class . "]");
            $modifier->setAttribute("role", "attribute");
            $methodSynopsis->appendChild($modifier);
            $methodSynopsis->appendChild(new DOMText("\n   "));
        }

        foreach ($this->getModifierNames() as $modifierString) {
            $modifierElement = $doc->createElement('modifier', $modifierString);
            $methodSynopsis->appendChild($modifierElement);
            $methodSynopsis->appendChild(new DOMText(" "));
        }

        $returnType = $this->return->getMethodSynopsisType();
        if ($returnType) {
            $methodSynopsis->appendChild($returnType->getTypeForDoc($doc));
        }

        $methodname = $doc->createElement('methodname', $this->name->__toString());
        $methodSynopsis->appendChild($methodname);

        if (empty($this->args)) {
            $methodSynopsis->appendChild(new DOMText("\n   "));
            $void = $doc->createElement('void');
            $methodSynopsis->appendChild($void);
        } else {
            foreach ($this->args as $arg) {
                $methodSynopsis->appendChild(new DOMText("\n   "));
                $methodparam = $doc->createElement('methodparam');
                if ($arg->defaultValue !== null) {
                    $methodparam->setAttribute("choice", "opt");
                }
                if ($arg->isVariadic) {
                    $methodparam->setAttribute("rep", "repeat");
                }

                $methodSynopsis->appendChild($methodparam);
                foreach ($arg->attributes as $attribute) {
                    $attribute = $doc->createElement("modifier", "#[\\" . $attribute->class . "]");
                    $attribute->setAttribute("role", "attribute");

                    $methodparam->appendChild($attribute);
                }

                $methodparam->appendChild($arg->getMethodSynopsisType()->getTypeForDoc($doc));

                $parameter = $doc->createElement('parameter', $arg->name);
                if ($arg->sendBy !== ArgInfo::SEND_BY_VAL) {
                    $parameter->setAttribute("role", "reference");
                }

                $methodparam->appendChild($parameter);
                $defaultValue = $arg->getDefaultValueAsMethodSynopsisString();
                if ($defaultValue !== null) {
                    $initializer = $doc->createElement('initializer');
                    if (preg_match('/^[a-zA-Z_][a-zA-Z_0-9\:\\\\]*$/', $defaultValue)) {
                        $constant = $doc->createElement('constant', $defaultValue);
                        $initializer->appendChild($constant);
                    } else {
                        $initializer->nodeValue = $defaultValue;
                    }
                    $methodparam->appendChild($initializer);
                }
            }
        }
        $methodSynopsis->appendChild(new DOMText("\n  "));

        return $methodSynopsis;
    }

    /** @param FuncInfo[] $generatedFuncInfos */
    public function findEquivalent(array $generatedFuncInfos): ?FuncInfo {
        foreach ($generatedFuncInfos as $generatedFuncInfo) {
            if ($generatedFuncInfo->equalsApartFromNameAndRefcount($this)) {
                return $generatedFuncInfo;
            }
        }
        return null;
    }

    public function toArgInfoCode(?int $minPHPCompatibility): string {
        $code = $this->return->beginArgInfo(
            $this->getArgInfoName(),
            $this->numRequiredArgs,
            $minPHPCompatibility === null || $minPHPCompatibility >= PHP_81_VERSION_ID
        );

        foreach ($this->args as $argInfo) {
            $code .= $argInfo->toZendInfo();
        }

        $code .= "ZEND_END_ARG_INFO()";
        return $code . "\n";
    }

    public function __clone()
    {
        $this->args = array_map((\clone)(...), $this->args);
        $this->return = clone $this->return;
    }
}

class EvaluatedValue
{

    /**
     * @param ConstInfo[] $originatingConsts
     */
    private function __construct(
        public readonly mixed $value,
        public SimpleType $type,
        public Expr $expr,
        public array $originatingConsts,
        public bool $isUnknownConstValue,
    ) {}

    /**
     * @param array<string, ConstInfo> $allConstInfos
     */
    public static function createFromExpression(Expr $expr, ?SimpleType $constType, ?string $cConstName, array $allConstInfos): EvaluatedValue
    {
        // This visitor replaces the PHP constants by C constants. It allows direct expansion of the compiled constants, e.g. later in the pretty printer.
        $visitor = new class($allConstInfos) extends PhpParser\NodeVisitorAbstract
        {
            /** @var iterable<ConstInfo> */
            public array $visitedConstants = [];

            /** @param array<string, ConstInfo> $allConstInfos */
            public function __construct(
                public array $allConstInfos,
            ) {}

            /** @return Node|null */
            public function enterNode(Node $expr)
            {
                if (!$expr instanceof Expr\ConstFetch && !$expr instanceof Expr\ClassConstFetch) {
                    return null;
                }

                if ($expr instanceof Expr\ClassConstFetch) {
                    $originatingConstName = new ClassConstName($expr->class, $expr->name->toString());
                } else {
                    $originatingConstName = new ConstName($expr->name->getAttribute('namespacedName'), $expr->name->toString());
                }

                if ($originatingConstName->isUnknown()) {
                    return null;
                }

                $const = $this->allConstInfos[$originatingConstName->__toString()] ?? null;
                if ($const !== null) {
                    $this->visitedConstants[] = $const;
                    return $const->getValue($this->allConstInfos)->expr;
                }
            }
        };

        $nodeTraverser = new PhpParser\NodeTraverser;
        $nodeTraverser->addVisitor($visitor);
        $expr = $nodeTraverser->traverse([$expr])[0];

        $isUnknownConstValue = false;

        $evaluator = new ConstExprEvaluator(
            static function (Expr $expr) use ($allConstInfos, &$isUnknownConstValue) {
                // $expr is a ConstFetch with a name of a C macro here
                if (!$expr instanceof Expr\ConstFetch) {
                    throw new Exception("Expression at line " . $expr->getStartLine() . " must be a global, non-magic constant");
                }

                $constName = $expr->name->__toString();
                if (strtolower($constName) === "unknown") {
                    $isUnknownConstValue = true;
                    return null;
                }

                foreach ($allConstInfos as $const) {
                    if ($constName != $const->cValue) {
                        continue;
                    }

                    $constType = ($const->phpDocType ?? $const->type)->tryToSimpleType();
                    if ($constType) {
                        if ($constType->isBool()) {
                            return true;
                        } elseif ($constType->isInt()) {
                            return 1;
                        } elseif ($constType->isFloat()) {
                            return M_PI;
                        } elseif ($constType->isString()) {
                            return $const->name;
                        } elseif ($constType->isArray()) {
                            return [];
                        }
                    }

                    return null;
                }

                throw new Exception("Constant " . $constName . " cannot be found");
            }
        );

        $result = $evaluator->evaluateDirectly($expr);

        return new EvaluatedValue(
            $result, // note: we are generally not interested in the actual value of $result, unless it's a bare value, without constants
            $constType ?? SimpleType::fromValue($result),
            $cConstName === null ? $expr : new Expr\ConstFetch(new Node\Name($cConstName)),
            $visitor->visitedConstants,
            $isUnknownConstValue
        );
    }

    public static function null(): EvaluatedValue
    {
        return new self(null, SimpleType::null(), new Expr\ConstFetch(new Node\Name('null')), [], false);
    }

    public function initializeZval(string $zvalName, bool $alreadyExists = false, string $forStringDef = ''): string
    {
        $cExpr = $this->getCExpr();

        $code = '';
        if (!$alreadyExists) {
            $code = "\tzval $zvalName;\n";
        }

        if ($this->type->isNull()) {
            $code .= "\tZVAL_NULL(&$zvalName);\n";
        } elseif ($this->type->isBool()) {
            if ($cExpr == 'true') {
                $code .= "\tZVAL_TRUE(&$zvalName);\n";
            } elseif ($cExpr == 'false') {
                $code .= "\tZVAL_FALSE(&$zvalName);\n";
            } else {
                $code .= "\tZVAL_BOOL(&$zvalName, $cExpr);\n";
            }
        } elseif ($this->type->isInt()) {
            $code .= "\tZVAL_LONG(&$zvalName, $cExpr);\n";
        } elseif ($this->type->isFloat()) {
            $code .= "\tZVAL_DOUBLE(&$zvalName, $cExpr);\n";
        } elseif ($this->type->isString()) {
            if ($cExpr === '""') {
                $code .= "\tZVAL_EMPTY_STRING(&$zvalName);\n";
            } else {
                if ($forStringDef === '') {
                    $forStringDef = "{$zvalName}_str";
                }
                $code .= "\tzend_string *$forStringDef = zend_string_init($cExpr, strlen($cExpr), 1);\n";
                $code .= "\tZVAL_STR(&$zvalName, $forStringDef);\n";
            }
        } elseif ($this->type->isArray()) {
            if ($cExpr == '[]') {
                $code .= "\tZVAL_EMPTY_ARRAY(&$zvalName);\n";
            } else {
                throw new Exception("Unimplemented default value");
            }
        } else {
            throw new Exception("Invalid default value: " . print_r($this->value, true) . ", type: " . print_r($this->type, true));
        }

        return $code;
    }

    public function getCExpr(): ?string
    {
        // $this->expr has all its PHP constants replaced by C constants
        $prettyPrinter = new Standard;
        $expr = $prettyPrinter->prettyPrintExpr($this->expr);
        // PHP single-quote to C double-quote string
        if ($this->type->isString()) {
            $expr = preg_replace("/(^'|'$)/", '"', $expr);
        }
        return $expr[0] == '"' ? $expr : preg_replace('(\bnull\b)', 'NULL', str_replace('\\', '', $expr));
    }
}

abstract class VariableLike
{
    /**
     * @param AttributeInfo[] $attributes
     */
    public function __construct(
        protected int $flags,
        public ?Type $type,
        public readonly ?Type $phpDocType,
        private readonly ?string $link,
        protected ?int $phpVersionIdMinimumCompatibility,
        public array $attributes,
        protected readonly ?ExposedDocComment $exposedDocComment,
    ) {}

    abstract protected function getVariableTypeName(): string;

    abstract protected function getFieldSynopsisDefaultLinkend(): string;

    abstract protected function getFieldSynopsisName(): string;

    /** @param array<string, ConstInfo> $allConstInfos */
    abstract protected function getFieldSynopsisValueString(array $allConstInfos): ?string;

    abstract public function discardInfoForOldPhpVersions(?int $minimumPhpVersionIdCompatibility): void;

    protected function getFlagsByPhpVersion(): VersionFlags
    {
        $flags = "ZEND_ACC_PUBLIC";
        if ($this->flags & Modifiers::PROTECTED) {
            $flags = "ZEND_ACC_PROTECTED";
        } elseif ($this->flags & Modifiers::PRIVATE) {
            $flags = "ZEND_ACC_PRIVATE";
        }

        return new VersionFlags([$flags]);
    }

    protected function getTypeCode(string $variableLikeName, string &$code): string
    {
        $variableLikeType = $this->getVariableTypeName();
        if ($this->type) {
            $arginfoType = $this->type->toArginfoType();
            if ($arginfoType->hasClassType()) {
                if (count($arginfoType->classTypes) >= 2) {
                    foreach ($arginfoType->classTypes as $classType) {
                        $escapedClassName = $classType->toEscapedName();
                        $varEscapedClassName = $classType->toVarEscapedName();
                        $code .= "\tzend_string *{$variableLikeType}_{$variableLikeName}_class_{$varEscapedClassName} = zend_string_init(\"{$escapedClassName}\", sizeof(\"{$escapedClassName}\") - 1, 1);\n";
                    }

                    $classTypeCount = count($arginfoType->classTypes);
                    $code .= "\tzend_type_list *{$variableLikeType}_{$variableLikeName}_type_list = malloc(ZEND_TYPE_LIST_SIZE($classTypeCount));\n";
                    $code .= "\t{$variableLikeType}_{$variableLikeName}_type_list->num_types = $classTypeCount;\n";

                    foreach ($arginfoType->classTypes as $k => $classType) {
                        $varEscapedClassName = $classType->toVarEscapedName();
                        $code .= "\t{$variableLikeType}_{$variableLikeName}_type_list->types[$k] = (zend_type) ZEND_TYPE_INIT_CLASS({$variableLikeType}_{$variableLikeName}_class_{$varEscapedClassName}, 0, 0);\n";
                    }

                    $typeMaskCode = $this->type->toArginfoType()->toTypeMask();

                    if ($this->type->isIntersection) {
                        $code .= "\tzend_type {$variableLikeType}_{$variableLikeName}_type = ZEND_TYPE_INIT_INTERSECTION({$variableLikeType}_{$variableLikeName}_type_list, $typeMaskCode);\n";
                    } else {
                        $code .= "\tzend_type {$variableLikeType}_{$variableLikeName}_type = ZEND_TYPE_INIT_UNION({$variableLikeType}_{$variableLikeName}_type_list, $typeMaskCode);\n";
                    }
                    return "{$variableLikeType}_{$variableLikeName}_type";
                }
                $escapedClassName = $arginfoType->classTypes[0]->toEscapedName();
                $varEscapedClassName = $arginfoType->classTypes[0]->toVarEscapedName();
                $code .= "\tzend_string *{$variableLikeType}_{$variableLikeName}_class_{$varEscapedClassName} = zend_string_init(\"{$escapedClassName}\", sizeof(\"{$escapedClassName}\")-1, 1);\n";

                return "(zend_type) ZEND_TYPE_INIT_CLASS({$variableLikeType}_{$variableLikeName}_class_{$varEscapedClassName}, 0, " . $arginfoType->toTypeMask() . ")";
            }
            return "(zend_type) ZEND_TYPE_INIT_MASK(" . $arginfoType->toTypeMask() . ")";
        }
        return "(zend_type) ZEND_TYPE_INIT_NONE(0)";
    }

    /** @param array<string, ConstInfo> $allConstInfos */
    public function getFieldSynopsisElement(DOMDocument $doc, array $allConstInfos, int $indentationLevel): DOMElement
    {
        $indentation = str_repeat(" ", $indentationLevel);

        $fieldsynopsisElement = $doc->createElement("fieldsynopsis");

        $this->addModifiersToFieldSynopsis($doc, $fieldsynopsisElement, $indentationLevel + 1);

        $type = $this->phpDocType ?? $this->type;
        if ($type) {
            $fieldsynopsisElement->appendChild(new DOMText("\n$indentation "));
            $fieldsynopsisElement->appendChild($type->getTypeForDoc($doc));
        }

        $varnameElement = $doc->createElement("varname", $this->getFieldSynopsisName());
        if ($this->link) {
            $varnameElement->setAttribute("linkend", $this->link);
        } else {
            $varnameElement->setAttribute("linkend", $this->getFieldSynopsisDefaultLinkend());
        }

        $fieldsynopsisElement->appendChild(new DOMText("\n$indentation "));
        $fieldsynopsisElement->appendChild($varnameElement);

        $valueString = $this->getFieldSynopsisValueString($allConstInfos);
        if ($valueString) {
            $fieldsynopsisElement->appendChild(new DOMText("\n$indentation "));
            $initializerElement = $doc->createElement("initializer",  $valueString);
            $fieldsynopsisElement->appendChild($initializerElement);
        }

        $fieldsynopsisElement->appendChild(new DOMText("\n$indentation"));

        return $fieldsynopsisElement;
    }

    protected function addModifiersToFieldSynopsis(DOMDocument $doc, DOMElement $fieldsynopsisElement, int $indentationLevel): void
    {
        $indentation = str_repeat(" ", $indentationLevel);

        if ($this->flags & Modifiers::PUBLIC) {
            $fieldsynopsisElement->appendChild(new DOMText("\n$indentation"));
            $fieldsynopsisElement->appendChild($doc->createElement("modifier", "public"));
        } elseif ($this->flags & Modifiers::PROTECTED) {
            $fieldsynopsisElement->appendChild(new DOMText("\n$indentation"));
            $fieldsynopsisElement->appendChild($doc->createElement("modifier", "protected"));
        } elseif ($this->flags & Modifiers::PRIVATE) {
            $fieldsynopsisElement->appendChild(new DOMText("\n$indentation"));
            $fieldsynopsisElement->appendChild($doc->createElement("modifier", "private"));
        }
    }

}

class ConstInfo extends VariableLike
{

    /**
     * @param AttributeInfo[] $attributes
     */
    public function __construct(
        public readonly AbstractConstName $name,
        int $flags,
        public readonly Expr $value,
        private readonly ?string $valueString,
        ?Type $type,
        ?Type $phpDocType,
        private bool $isDeprecated,
        public readonly ?string $cond,
        public readonly ?string $cValue,
        public readonly bool $isUndocumentable,
        ?string $link,
        ?int $phpVersionIdMinimumCompatibility,
        array $attributes,
        ?ExposedDocComment $exposedDocComment,
        private readonly bool $isFileCacheAllowed,
    ) {
        if (array_any(
            $attributes,
            static fn (AttributeInfo $attr): bool => $attr->class === "Deprecated"
        )) {
            $this->isDeprecated = true;
        }

        parent::__construct($flags, $type, $phpDocType, $link, $phpVersionIdMinimumCompatibility, $attributes, $exposedDocComment);
    }

    /** @param array<string, ConstInfo> $allConstInfos */
    public function getValue(array $allConstInfos): EvaluatedValue
    {
        return EvaluatedValue::createFromExpression(
            $this->value,
            ($this->phpDocType ?? $this->type)->tryToSimpleType(),
            $this->cValue,
            $allConstInfos
        );
    }

    protected function getVariableTypeName(): string
    {
        return "constant";
    }

    protected function getFieldSynopsisDefaultLinkend(): string
    {
        $className = str_replace(["\\", "_"], ["-", "-"], $this->name->class->toLowerString());

        return "$className.constants." . strtolower(str_replace("_", "-", trim($this->name->getDeclarationName(), "_")));
    }

    protected function getFieldSynopsisName(): string
    {
        return $this->name->__toString();
    }

    /** @param array<string, ConstInfo> $allConstInfos */
    protected function getFieldSynopsisValueString(array $allConstInfos): ?string
    {
        $value = EvaluatedValue::createFromExpression($this->value, null, $this->cValue, $allConstInfos);
        if ($value->isUnknownConstValue) {
            return null;
        }

        if ($value->originatingConsts) {
            return implode("\n", array_map(function (ConstInfo $const) use ($allConstInfos) {
                return $const->getFieldSynopsisValueString($allConstInfos);
            }, $value->originatingConsts));
        }

        return $this->valueString;
    }

    private function getPredefinedConstantElement(
        DOMDocument $doc,
        int $indentationLevel,
        string $name
    ): DOMElement {
        $indentation = str_repeat(" ", $indentationLevel);

        $element = $doc->createElement($name);

        $constantElement = $doc->createElement("constant");
        $constantElement->textContent = $this->name->__toString();

        $typeElement = ($this->phpDocType ?? $this->type)->getTypeForDoc($doc);

        $element->appendChild(new DOMText("\n$indentation "));
        $element->appendChild($constantElement);
        $element->appendChild(new DOMText("\n$indentation ("));
        $element->appendChild($typeElement);
        $element->appendChild(new DOMText(")\n$indentation"));

        return $element;
    }

    public function getPredefinedConstantTerm(DOMDocument $doc, int $indentationLevel): DOMElement {
        return $this->getPredefinedConstantElement($doc, $indentationLevel, "term");
    }

    public function getPredefinedConstantEntry(DOMDocument $doc, int $indentationLevel): DOMElement {
        return $this->getPredefinedConstantElement($doc, $indentationLevel, "entry");
    }

    public function discardInfoForOldPhpVersions(?int $phpVersionIdMinimumCompatibility): void {
        $this->type = null;
        $this->flags &= ~Modifiers::FINAL;
        $this->isDeprecated = false;
        $this->attributes = [];
        $this->phpVersionIdMinimumCompatibility = $phpVersionIdMinimumCompatibility;
    }

    /** @param array<string, ConstInfo> $allConstInfos */
    public function getDeclaration(array $allConstInfos): string
    {
        $type = $this->phpDocType ?? $this->type;
        $simpleType = $type ? $type->tryToSimpleType() : null;
        if ($simpleType && $simpleType->name === "mixed") {
            $simpleType = null;
        }

        $value = EvaluatedValue::createFromExpression($this->value, $simpleType, $this->cValue, $allConstInfos);
        if ($value->isUnknownConstValue && ($simpleType === null || !$simpleType->isBuiltin)) {
            throw new Exception("Constant " . $this->name->__toString() . " must have a built-in PHPDoc type as the type couldn't be inferred from its value");
        }

        // i.e. const NAME = UNKNOWN;, without the annotation
        if ($value->isUnknownConstValue && $this->cValue === null && $value->expr instanceof Expr\ConstFetch && $value->expr->name->__toString() === "UNKNOWN") {
            throw new Exception("Constant " . $this->name->__toString() . " must have a @cvalue annotation");
        }

        // Condition will be added by generateCodeWithConditions()

        if ($this->name instanceof ClassConstName) {
            $code = $this->getClassConstDeclaration($value);
        } else {
            $code = $this->getGlobalConstDeclaration($value);
        }
        $code .= $this->getValueAssertion($value);

        return $code;
    }

    private function getGlobalConstDeclaration(EvaluatedValue $value): string
    {
        $constName = str_replace('\\', '\\\\', $this->name->__toString());
        $constValue = $value->value;
        $cExpr = $value->getCExpr();

        $flags = "CONST_PERSISTENT";
        if (!$this->isFileCacheAllowed) {
            $flags .= " | CONST_NO_FILE_CACHE";
        }
        if ($this->phpVersionIdMinimumCompatibility !== null && $this->phpVersionIdMinimumCompatibility < 80000) {
            $flags .= " | CONST_CS";
        }

        if ($this->isDeprecated) {
            $flags .= " | CONST_DEPRECATED";
        }

        $code = "\t";
        if ($this->attributes !== []) {
            if ($this->phpVersionIdMinimumCompatibility === null || $this->phpVersionIdMinimumCompatibility >= PHP_85_VERSION_ID) {
                // Registration only returns the constant since PHP 8.5, it's
                // not worth the bloat to add two different registration blocks
                // with conditions for the PHP version
                $constVarName = 'const_' . $constName;
                $code .= "zend_constant *$constVarName = ";
            }
        }

        if ($value->type->isNull()) {
            return $code . "REGISTER_NULL_CONSTANT(\"$constName\", $flags);\n";
        }

        if ($value->type->isBool()) {
            return $code . "REGISTER_BOOL_CONSTANT(\"$constName\", " . ($cExpr ?: ($constValue ? "true" : "false")) . ", $flags);\n";
        }

        if ($value->type->isInt()) {
            return $code . "REGISTER_LONG_CONSTANT(\"$constName\", " . ($cExpr ?: (int) $constValue) . ", $flags);\n";
        }

        if ($value->type->isFloat()) {
            return $code . "REGISTER_DOUBLE_CONSTANT(\"$constName\", " . ($cExpr ?: (float) $constValue) . ", $flags);\n";
        }

        if ($value->type->isString()) {
            return $code . "REGISTER_STRING_CONSTANT(\"$constName\", " . ($cExpr ?: '"' . addslashes($constValue) . '"') . ", $flags);\n";
        }

        throw new Exception("Unimplemented constant type");
    }

    private function getClassConstDeclaration(EvaluatedValue $value): string
    {
        $constName = $this->name->getDeclarationName();

        $zvalCode = $value->initializeZval("const_{$constName}_value");

        $code = "\n" . $zvalCode;

        $code .= "\tzend_string *const_{$constName}_name = zend_string_init_interned(\"$constName\", sizeof(\"$constName\") - 1, true);\n";
        $nameCode = "const_{$constName}_name";

        if ($this->exposedDocComment) {
            $commentCode = "const_{$constName}_comment";
            $escapedCommentInit = $this->exposedDocComment->getInitCode();
            $code .= "\tzend_string *$commentCode = $escapedCommentInit\n";
        } else {
            $commentCode = "NULL";
        }

        $php83MinimumCompatibility = $this->phpVersionIdMinimumCompatibility === null || $this->phpVersionIdMinimumCompatibility >= PHP_83_VERSION_ID;

        if ($this->type && !$php83MinimumCompatibility) {
            $code .= "#if (PHP_VERSION_ID >= " . PHP_83_VERSION_ID . ")\n";
        }

        if ($this->type) {
            $typeCode = $this->getTypeCode($constName, $code);

            if (!empty($this->attributes)) {
                $template = "\tzend_class_constant *const_" . $this->name->getDeclarationName() . " = ";
            } else {
                $template = "\t";
            }
            $template .= "zend_declare_typed_class_constant(class_entry, $nameCode, &const_{$constName}_value, %s, $commentCode, $typeCode);\n";

            $code .= $this->getFlagsByPhpVersion()->generateVersionDependentFlagCode(
                $template,
                $this->phpVersionIdMinimumCompatibility
            );
        }

        if ($this->type && !$php83MinimumCompatibility) {
            $code .= "#else\n";
        }

        if (!$this->type || !$php83MinimumCompatibility) {
            if (!empty($this->attributes)) {
                $template = "\tzend_class_constant *const_" . $this->name->getDeclarationName() . " = ";
            } else {
                $template = "\t";
            }
            $template .= "zend_declare_class_constant_ex(class_entry, $nameCode, &const_{$constName}_value, %s, $commentCode);\n";
            $code .= $this->getFlagsByPhpVersion()->generateVersionDependentFlagCode(
                $template,
                $this->phpVersionIdMinimumCompatibility
            );
        }

        if ($this->type && !$php83MinimumCompatibility) {
            $code .= "#endif\n";
        }

        $code .= "\tzend_string_release_ex(const_{$constName}_name, true);\n";

        return $code;
    }

    private function getValueAssertion(EvaluatedValue $value): string
    {
        if ($value->isUnknownConstValue || $value->originatingConsts || $this->cValue === null) {
            return "";
        }

        $cExpr = $value->getCExpr();
        $constValue = $value->value;

        if ($value->type->isNull()) {
            return "\tZEND_ASSERT($cExpr == NULL);\n";
        }

        if ($value->type->isBool()) {
            $cValue = $constValue ? "true" : "false";
            return "\tZEND_ASSERT($cExpr == $cValue);\n";
        }

        if ($value->type->isInt()) {
            $cValue = (int) $constValue;
            return "\tZEND_ASSERT($cExpr == $cValue);\n";
        }

        if ($value->type->isFloat()) {
            $cValue = (float) $constValue;
            return "\tZEND_ASSERT($cExpr == $cValue);\n";
        }

        if ($value->type->isString()) {
            $cValue = '"' . addslashes($constValue) . '"';
            return "\tZEND_ASSERT(strcmp($cExpr, $cValue) == 0);\n";
        }

        throw new Exception("Unimplemented constant type");
    }

    protected function getFlagsByPhpVersion(): VersionFlags
    {
        $flags = parent::getFlagsByPhpVersion();

        // $this->isDeprecated also accounts for any #[\Deprecated] attributes
        if ($this->isDeprecated) {
            $flags->addForVersionsAbove("ZEND_ACC_DEPRECATED", PHP_80_VERSION_ID);
        }

        if ($this->flags & Modifiers::FINAL) {
            $flags->addForVersionsAbove("ZEND_ACC_FINAL", PHP_81_VERSION_ID);
        }

        return $flags;
    }

    protected function addModifiersToFieldSynopsis(DOMDocument $doc, DOMElement $fieldsynopsisElement, int $indentationLevel): void
    {
        parent::addModifiersToFieldSynopsis($doc, $fieldsynopsisElement, $indentationLevel);

        $indentation = str_repeat(" ", $indentationLevel);

        if ($this->flags & Modifiers::FINAL) {
            $fieldsynopsisElement->appendChild(new DOMText("\n$indentation"));
            $fieldsynopsisElement->appendChild($doc->createElement("modifier", "final"));
        }

        $fieldsynopsisElement->appendChild(new DOMText("\n$indentation"));
        $fieldsynopsisElement->appendChild($doc->createElement("modifier", "const"));
    }
}

class StringBuilder {

    // Map possible variable names to the known string constant, see
    // ZEND_KNOWN_STRINGS
    private const PHP_80_KNOWN = [
        "file" => "ZEND_STR_FILE",
        "line" => "ZEND_STR_LINE",
        "function" => "ZEND_STR_FUNCTION",
        "class" => "ZEND_STR_CLASS",
        "object" => "ZEND_STR_OBJECT",
        "type" => "ZEND_STR_TYPE",
        // ZEND_STR_OBJECT_OPERATOR and ZEND_STR_PAAMAYIM_NEKUDOTAYIM are
        // not valid variable names
        "args" => "ZEND_STR_ARGS",
        "unknown" => "ZEND_STR_UNKNOWN",
        "eval" => "ZEND_STR_EVAL",
        "include" => "ZEND_STR_INCLUDE",
        "require" => "ZEND_STR_REQUIRE",
        "include_once" => "ZEND_STR_INCLUDE_ONCE",
        "require_once" => "ZEND_STR_REQUIRE_ONCE",
        "scalar" => "ZEND_STR_SCALAR",
        "error_reporting" => "ZEND_STR_ERROR_REPORTING",
        "static" => "ZEND_STR_STATIC",
        // ZEND_STR_THIS cannot be used since $this cannot be reassigned
        "value" => "ZEND_STR_VALUE",
        "key" => "ZEND_STR_KEY",
        "__invoke" => "ZEND_STR_MAGIC_INVOKE",
        "previous" => "ZEND_STR_PREVIOUS",
        "code" => "ZEND_STR_CODE",
        "message" => "ZEND_STR_MESSAGE",
        "severity" => "ZEND_STR_SEVERITY",
        "string" => "ZEND_STR_STRING",
        "trace" => "ZEND_STR_TRACE",
        "scheme" => "ZEND_STR_SCHEME",
        "host" => "ZEND_STR_HOST",
        "port" => "ZEND_STR_PORT",
        "user" => "ZEND_STR_USER",
        "pass" => "ZEND_STR_PASS",
        "path" => "ZEND_STR_PATH",
        "query" => "ZEND_STR_QUERY",
        "fragment" => "ZEND_STR_FRAGMENT",
        "NULL" => "ZEND_STR_NULL",
        "boolean" => "ZEND_STR_BOOLEAN",
        "integer" => "ZEND_STR_INTEGER",
        "double" => "ZEND_STR_DOUBLE",
        "array" => "ZEND_STR_ARRAY",
        "resource" => "ZEND_STR_RESOURCE",
        // ZEND_STR_CLOSED_RESOURCE has a space in it
        "name" => "ZEND_STR_NAME",
        // ZEND_STR_ARGV and ZEND_STR_ARGC are superglobals that wouldn't be
        // variable names
        "Array" => "ZEND_STR_ARRAY_CAPITALIZED",
        "bool" => "ZEND_STR_BOOL",
        "int" => "ZEND_STR_INT",
        "float" => "ZEND_STR_FLOAT",
        "callable" => "ZEND_STR_CALLABLE",
        "iterable" => "ZEND_STR_ITERABLE",
        "void" => "ZEND_STR_VOID",
        "false" => "ZEND_STR_FALSE",
        "null" => "ZEND_STR_NULL_LOWERCASE",
        "mixed" => "ZEND_STR_MIXED",
    ];

    // NEW in 8.1
    private const PHP_81_KNOWN = [
        "Unknown" => "ZEND_STR_UNKNOWN_CAPITALIZED",
        "never" => "ZEND_STR_NEVER",
        "__sleep" => "ZEND_STR_SLEEP",
        "__wakeup" => "ZEND_STR_WAKEUP",
        "cases" => "ZEND_STR_CASES",
        "from" => "ZEND_STR_FROM",
        "tryFrom" => "ZEND_STR_TRYFROM",
        "tryfrom" => "ZEND_STR_TRYFROM_LOWERCASE",
        // Omit ZEND_STR_AUTOGLOBAL_(SERVER|ENV|REQUEST)
    ];

    // NEW in 8.2
    private const PHP_82_KNOWN = [
        "true" => "ZEND_STR_TRUE",
        "Traversable" => "ZEND_STR_TRAVERSABLE",
        "count" => "ZEND_STR_COUNT",
        "SensitiveParameter" => "ZEND_STR_SENSITIVEPARAMETER",
    ];

    // Only new string in 8.3 is ZEND_STR_CONST_EXPR_PLACEHOLDER which is
    // not a valid variable name ("[constant expression]")

    // NEW in 8.4
    private const PHP_84_KNOWN = [
        "exit" => "ZEND_STR_EXIT",
        "Deprecated" => "ZEND_STR_DEPRECATED_CAPITALIZED",
        "since" => "ZEND_STR_SINCE",
        "get" => "ZEND_STR_GET",
        "set" => "ZEND_STR_SET",
    ];

    // NEW in 8.5
    private const PHP_85_KNOWN = [
        "self" => "ZEND_STR_SELF",
        "parent" => "ZEND_STR_PARENT",
        "username" => "ZEND_STR_USERNAME",
        "password" => "ZEND_STR_PASSWORD",
        "clone" => "ZEND_STR_CLONE",
        '8.0' => 'ZEND_STR_8_DOT_0',
        '8.1' => 'ZEND_STR_8_DOT_1',
        '8.2' => 'ZEND_STR_8_DOT_2',
        '8.3' => 'ZEND_STR_8_DOT_3',
        '8.4' => 'ZEND_STR_8_DOT_4',
        '8.5' => 'ZEND_STR_8_DOT_5',
    ];

    /**
     * Get an array of three strings:
     *   - declaration of zend_string, if needed, or empty otherwise
     *   - usage of that zend_string, or usage with ZSTR_KNOWN()
     *   - freeing the zend_string, if needed
     *
     * @param string $varName
     * @param string $strContent
     * @param ?int $minPHPCompatibility
     * @param bool $interned
     * @return string[]
     */
    public static function getString(
        string $varName,
        string $content,
        ?int $minPHPCompatibility,
        bool $interned = false
    ): array {
        // Generally strings will not be known
        $initFn = $interned ? 'zend_string_init_interned' : 'zend_string_init';
        $result = [
            "\tzend_string *$varName = $initFn(\"$content\", sizeof(\"$content\") - 1, true);\n",
            $varName,
            "\tzend_string_release_ex($varName, true);\n"
        ];
        // For attribute values that are not freed
        if ($varName === '') {
            $result[0] = "$initFn(\"$content\", sizeof(\"$content\") - 1, true);\n";
        }
        // If not set, use the current latest version
        $allVersions = ALL_PHP_VERSION_IDS;
        $minPhp = $minPHPCompatibility ?? end($allVersions);
        if ($minPhp < PHP_80_VERSION_ID) {
            // No known strings in 7.0
            return $result;
        }
        $include = self::PHP_80_KNOWN;
        switch ($minPhp) {
            case PHP_85_VERSION_ID:
                $include = array_merge($include, self::PHP_85_KNOWN);
                // Intentional fall through

            case PHP_84_VERSION_ID:
                $include = array_merge($include, self::PHP_84_KNOWN);
                // Intentional fall through

            case PHP_83_VERSION_ID:
            case PHP_82_VERSION_ID:
                $include = array_merge($include, self::PHP_82_KNOWN);
                // Intentional fall through

            case PHP_81_VERSION_ID:
                $include = array_merge($include, self::PHP_81_KNOWN);
                break;
        }
        if (array_key_exists($content, $include)) {
            $knownStr = $include[$content];
            return [
                '',
                "ZSTR_KNOWN($knownStr)",
                '',
            ];
        }
        return $result;
    }
}

class PropertyInfo extends VariableLike
{

    /**
     * @param AttributeInfo[] $attributes
     */
    public function __construct(
        public readonly PropertyName $name,
        private readonly int $classFlags,
        int $flags,
        ?Type $type,
        ?Type $phpDocType,
        private readonly ?Expr $defaultValue,
        private readonly ?string $defaultValueString,
        private readonly bool $isDocReadonly,
        private readonly bool $isVirtual,
        ?string $link,
        ?int $phpVersionIdMinimumCompatibility,
        array $attributes,
        ?ExposedDocComment $exposedDocComment
    ) {
        parent::__construct($flags, $type, $phpDocType, $link, $phpVersionIdMinimumCompatibility, $attributes, $exposedDocComment);
    }

    protected function getVariableTypeName(): string
    {
        return "property";
    }

    protected function getFieldSynopsisDefaultLinkend(): string
    {
        $className = str_replace(["\\", "_"], ["-", "-"], $this->name->class->toLowerString());

        return "$className.props." . strtolower(str_replace("_", "-", trim($this->name->getDeclarationName(), "_")));
    }

    protected function getFieldSynopsisName(): string
    {
        return $this->name->getDeclarationName();
    }

    /** @param array<string, ConstInfo> $allConstInfos */
    protected function getFieldSynopsisValueString(array $allConstInfos): ?string
    {
        return $this->defaultValueString;
    }

    public function discardInfoForOldPhpVersions(?int $phpVersionIdMinimumCompatibility): void {
        $this->type = null;
        $this->flags &= ~Modifiers::READONLY;
        $this->attributes = [];
        $this->phpVersionIdMinimumCompatibility = $phpVersionIdMinimumCompatibility;
    }

    /** @param array<string, ConstInfo> $allConstInfos */
    public function getDeclaration(array $allConstInfos): string {
        $code = "\n";

        $propertyName = $this->name->getDeclarationName();

        if ($this->defaultValue === null) {
            $defaultValue = EvaluatedValue::null();
        } else {
            $defaultValue = EvaluatedValue::createFromExpression($this->defaultValue, null, null, $allConstInfos);
            if ($defaultValue->isUnknownConstValue || ($defaultValue->originatingConsts && $defaultValue->getCExpr() === null)) {
                echo "Skipping code generation for property $this->name, because it has an unknown constant default value\n";
                return "";
            }
        }

        $zvalName = "property_{$propertyName}_default_value";
        if ($this->defaultValue === null && $this->type !== null) {
            $code .= "\tzval $zvalName;\n\tZVAL_UNDEF(&$zvalName);\n";
        } else {
            $code .= $defaultValue->initializeZval($zvalName);
        }

        [$stringInit, $nameCode, $stringRelease] = StringBuilder::getString(
            "property_{$propertyName}_name",
            $propertyName,
            $this->phpVersionIdMinimumCompatibility
        );
        $code .= $stringInit;

        if ($this->exposedDocComment) {
            $commentCode = "property_{$propertyName}_comment";
            $escapedCommentInit = $this->exposedDocComment->getInitCode();
            $code .= "\tzend_string *$commentCode = $escapedCommentInit\n";
        } else {
            $commentCode = "NULL";
        }

        if (!empty($this->attributes)) {
            $template = "\tzend_property_info *property_" . $this->name->getDeclarationName() . " = ";
        } else {
            $template = "\t";
        }

        if ($this->phpVersionIdMinimumCompatibility === null || $this->phpVersionIdMinimumCompatibility >= PHP_80_VERSION_ID) {
            $typeCode = $this->getTypeCode($propertyName, $code);
            $template .= "zend_declare_typed_property(class_entry, $nameCode, &$zvalName, %s, $commentCode, $typeCode);\n";
        } else {
            $template .= "zend_declare_property_ex(class_entry, $nameCode, &$zvalName, %s, $commentCode);\n";
        }

        $code .= $this->getFlagsByPhpVersion()->generateVersionDependentFlagCode(
            $template,
            $this->phpVersionIdMinimumCompatibility
        );

        $code .= $stringRelease;

        return $code;
    }

    protected function getFlagsByPhpVersion(): VersionFlags
    {
        $flags = parent::getFlagsByPhpVersion();

        if ($this->flags & Modifiers::STATIC) {
            $flags->addForVersionsAbove("ZEND_ACC_STATIC", PHP_70_VERSION_ID);
        }

        if ($this->flags & Modifiers::FINAL) {
            $flags->addForVersionsAbove("ZEND_ACC_FINAL", PHP_84_VERSION_ID);
        }

        if ($this->flags & Modifiers::READONLY) {
            $flags->addForVersionsAbove("ZEND_ACC_READONLY", PHP_81_VERSION_ID);
        } elseif ($this->classFlags & Modifiers::READONLY) {
            $flags->addForVersionsAbove("ZEND_ACC_READONLY", PHP_82_VERSION_ID);
        }

        if ($this->isVirtual) {
            $flags->addForVersionsAbove("ZEND_ACC_VIRTUAL", PHP_84_VERSION_ID);
        }

        return $flags;
    }

    protected function addModifiersToFieldSynopsis(DOMDocument $doc, DOMElement $fieldsynopsisElement, int $indentationLevel): void
    {
        parent::addModifiersToFieldSynopsis($doc, $fieldsynopsisElement, $indentationLevel);

        $indentation = str_repeat(" ", $indentationLevel);

        if ($this->flags & Modifiers::STATIC) {
            $fieldsynopsisElement->appendChild(new DOMText("\n$indentation"));
            $fieldsynopsisElement->appendChild($doc->createElement("modifier", "static"));
        }

        if ($this->flags & Modifiers::FINAL) {
            $fieldsynopsisElement->appendChild(new DOMText("\n$indentation"));
            $fieldsynopsisElement->appendChild($doc->createElement("modifier", "final"));
        }

        if ($this->flags & Modifiers::READONLY || $this->isDocReadonly) {
            $fieldsynopsisElement->appendChild(new DOMText("\n$indentation"));
            $fieldsynopsisElement->appendChild($doc->createElement("modifier", "readonly"));
        }
    }
}

class EnumCaseInfo {
    public function __construct(
        public readonly EnumCaseName $name,
        private readonly ?Expr $value,
        private readonly ?string $valueString
    ) {}

    /** @param array<string, ConstInfo> $allConstInfos */
    public function getDeclaration(array $allConstInfos): string {
        $escapedName = addslashes($this->name->case);
        if ($this->value === null) {
            return "\n\tzend_enum_add_case_cstr(class_entry, \"$escapedName\", NULL);\n";
        }
        $value = EvaluatedValue::createFromExpression($this->value, null, null, $allConstInfos);

        $zvalName = "enum_case_{$escapedName}_value";
        $code = "\n" . $value->initializeZval($zvalName);
        $code .= "\tzend_enum_add_case_cstr(class_entry, \"$escapedName\", &$zvalName);\n";

        return $code;
    }

    /** @param array<string, ConstInfo> $allConstInfos */
    public function getEnumSynopsisItemElement(DOMDocument $doc, array $allConstInfos, int $indentationLevel): DOMElement
    {
        $indentation = str_repeat(" ", $indentationLevel);

        $itemElement = $doc->createElement("enumitem");

        $identifierElement = $doc->createElement("enumidentifier", $this->name->case);

        $itemElement->appendChild(new DOMText("\n$indentation "));
        $itemElement->appendChild($identifierElement);

        $valueString = $this->getEnumSynopsisValueString($allConstInfos);
        if ($valueString) {
            $itemElement->appendChild(new DOMText("\n$indentation "));
            $valueElement = $doc->createElement("enumvalue",  $valueString);
            $itemElement->appendChild($valueElement);
        }

        $descriptionElement = $doc->createElement("enumitemdescription", "Description.");
        $itemElement->appendChild(new DOMText("\n$indentation "));
        $itemElement->appendChild($descriptionElement);

        $itemElement->appendChild(new DOMText("\n$indentation"));

        return $itemElement;
    }

    /** @param array<string, ConstInfo> $allConstInfos */
    public function getEnumSynopsisValueString(array $allConstInfos): ?string
    {
        if ($this->value === null) {
            return null;
        }

        $value = EvaluatedValue::createFromExpression($this->value, null, null, $allConstInfos);
        if ($value->isUnknownConstValue) {
            return null;
        }

        if ($value->originatingConsts) {
            return implode("\n", array_map(function (ConstInfo $const) use ($allConstInfos) {
                return $const->getFieldSynopsisValueString($allConstInfos);
            }, $value->originatingConsts));
        }

        return $this->valueString;
    }
}

// Instances of AttributeInfo are immutable and do not need to be cloned
// when held by an object that is cloned
class AttributeInfo {

    /** @param \PhpParser\Node\Arg[] $args */
    public function __construct(
        public readonly string $class,
        private readonly array $args,
    ) {}

    /**
     * @param array<string, ConstInfo> $allConstInfos
     * @param array<string, string> &$declaredStrings Map of string content to
     *   the name of a zend_string already created with that content
     */
    public function generateCode(string $invocation, string $nameSuffix, array $allConstInfos, ?int $phpVersionIdMinimumCompatibility, array &$declaredStrings = []): string {
        $escapedAttributeName = strtr($this->class, '\\', '_');
        [$stringInit, $nameCode, $stringRelease] = StringBuilder::getString(
            "attribute_name_{$escapedAttributeName}_$nameSuffix",
            addcslashes($this->class, "\\"),
            $phpVersionIdMinimumCompatibility,
            true
        );
        $code = "\n";
        $code .= $stringInit;
        $code .= "\t" . ($this->args ? "zend_attribute *attribute_{$escapedAttributeName}_$nameSuffix = " : "") . "$invocation, $nameCode, " . count($this->args) . ");\n";
        $code .= $stringRelease;

        foreach ($this->args as $i => $arg) {
            $initValue = '';
            if ($arg->value instanceof Node\Scalar\String_) {
                $strVal = $arg->value->value;
                [$strInit, $strUse, $strRelease] = StringBuilder::getString(
                    'unused',
                    $strVal,
                    $phpVersionIdMinimumCompatibility
                );
                if ($strInit === '') {
                    $initValue = "\tZVAL_STR(&attribute_{$escapedAttributeName}_{$nameSuffix}->args[$i].value, $strUse);\n";
                } elseif (isset($declaredStrings[$strVal])) {
                    $strUse = $declaredStrings[$strVal];
                    $initValue = "\tZVAL_STR_COPY(&attribute_{$escapedAttributeName}_{$nameSuffix}->args[$i].value, $strUse);\n";
                }
            }
            if ($initValue === '') {
                $value = EvaluatedValue::createFromExpression($arg->value, null, null, $allConstInfos);
                $code .= $value->initializeZval(
                    "attribute_{$escapedAttributeName}_{$nameSuffix}->args[$i].value",
                    true,
                    "attribute_{$escapedAttributeName}_{$nameSuffix}_arg{$i}_str"
                );
                if ($arg->value instanceof Node\Scalar\String_) {
                    $declaredStrings[$arg->value->value] = "attribute_{$escapedAttributeName}_{$nameSuffix}_arg{$i}_str";
                }
            } else {
                $code .= $initValue;
            }
            if ($arg->name) {
                [$stringInit, $nameCode, $stringRelease] = StringBuilder::getString(
                    "",
                    $arg->name->name,
                    $phpVersionIdMinimumCompatibility,
                    true
                );
                if ($stringInit === '') {
                    $nameCode .= ";\n";
                } else {
                    $nameCode = $stringInit;
                }
                $code .= "\tattribute_{$escapedAttributeName}_{$nameSuffix}->args[$i].name = $nameCode";
            }
        }
        return $code;
    }

    /**
     * @param AttributeGroup[] $attributeGroups
     * @return AttributeInfo[]
     */
    public static function createFromGroups(array $attributeGroups): array {
        $attributes = [];

        foreach ($attributeGroups as $attrGroup) {
            foreach ($attrGroup->attrs as $attr) {
                $attributes[] = new AttributeInfo($attr->name->toString(), $attr->args);
            }
        }

        return $attributes;
    }
}

class ClassInfo {

    /**
     * @param AttributeInfo[] $attributes
     * @param Name[] $extends
     * @param Name[] $implements
     * @param ConstInfo[] $constInfos
     * @param PropertyInfo[] $propertyInfos
     * @param FuncInfo[] $funcInfos
     * @param EnumCaseInfo[] $enumCaseInfos
     */
    public function __construct(
        public readonly Name $name,
        private int $flags,
        public string $type,
        public readonly ?string $alias,
        private readonly ?SimpleType $enumBackingType,
        private readonly bool $isDeprecated,
        private bool $isStrictProperties,
        private array $attributes,
        private ?ExposedDocComment $exposedDocComment,
        private bool $isNotSerializable,
        private readonly array $extends,
        private readonly array $implements,
        public /* readonly */ array $constInfos,
        private /* readonly */ array $propertyInfos,
        public array $funcInfos,
        private readonly array $enumCaseInfos,
        public readonly ?string $cond,
        public ?int $phpVersionIdMinimumCompatibility,
        public readonly bool $isUndocumentable,
    ) {}

    /** @param array<string, ConstInfo> $allConstInfos */
    public function getRegistration(array $allConstInfos): string
    {
        $params = [];
        foreach ($this->extends as $extends) {
            $params[] = "zend_class_entry *class_entry_" . implode("_", $extends->getParts());
        }
        foreach ($this->implements as $implements) {
            $params[] = "zend_class_entry *class_entry_" . implode("_", $implements->getParts());
        }

        $escapedName = implode("_", $this->name->getParts());

        $code = '';

        $php80MinimumCompatibility = $this->phpVersionIdMinimumCompatibility === null || $this->phpVersionIdMinimumCompatibility >= PHP_80_VERSION_ID;
        $php81MinimumCompatibility = $this->phpVersionIdMinimumCompatibility === null || $this->phpVersionIdMinimumCompatibility >= PHP_81_VERSION_ID;
        $php84MinimumCompatibility = $this->phpVersionIdMinimumCompatibility === null || $this->phpVersionIdMinimumCompatibility >= PHP_84_VERSION_ID;

        if ($this->type === "enum" && !$php81MinimumCompatibility) {
            $code .= "#if (PHP_VERSION_ID >= " . PHP_81_VERSION_ID . ")\n";
        }

        if ($this->cond) {
            $code .= "#if {$this->cond}\n";
        }

        $code .= "static zend_class_entry *register_class_$escapedName(" . (empty($params) ? "void" : implode(", ", $params)) . ")\n";

        $code .= "{\n";

        $flags = $this->getFlagsByPhpVersion();

        $classMethods = ($this->funcInfos === []) ? 'NULL' : "class_{$escapedName}_methods";
        if ($this->type === "enum") {
            $name = addslashes((string) $this->name);
            $backingType = $this->enumBackingType
                ? $this->enumBackingType->toTypeCode() : "IS_UNDEF";
            $code .= "\tzend_class_entry *class_entry = zend_register_internal_enum(\"$name\", $backingType, $classMethods);\n";
            if (!$flags->isEmpty()) {
                $code .= $this->getFlagsByPhpVersion()->generateVersionDependentFlagCode("\tclass_entry->ce_flags = %s;\n", $this->phpVersionIdMinimumCompatibility);
            }
        } else {
            $code .= "\tzend_class_entry ce, *class_entry;\n\n";
            if (count($this->name->getParts()) > 1) {
                $className = $this->name->getLast();
                $namespace = addslashes((string) $this->name->slice(0, -1));

                $code .= "\tINIT_NS_CLASS_ENTRY(ce, \"$namespace\", \"$className\", $classMethods);\n";
            } else {
                $code .= "\tINIT_CLASS_ENTRY(ce, \"$this->name\", $classMethods);\n";
            }

            if ($this->type === "class" || $this->type === "trait") {
                if (!$php84MinimumCompatibility) {
                    $code .= "#if (PHP_VERSION_ID >= " . PHP_84_VERSION_ID . ")\n";
                }

                $template = "\tclass_entry = zend_register_internal_class_with_flags(&ce, " . (isset($this->extends[0]) ? "class_entry_" . str_replace("\\", "_", $this->extends[0]->toString()) : "NULL") . ", %s);\n";
                $entries = $flags->generateVersionDependentFlagCode($template, $this->phpVersionIdMinimumCompatibility ? max($this->phpVersionIdMinimumCompatibility, PHP_84_VERSION_ID) : null);
                if ($entries !== '') {
                    $code .= $entries;
                } else {
                    $code .= sprintf($template, "0");
                }

                if (!$php84MinimumCompatibility) {
                    $code .= "#else\n";

                    $code .= "\tclass_entry = zend_register_internal_class_ex(&ce, " . (isset($this->extends[0]) ? "class_entry_" . str_replace("\\", "_", $this->extends[0]->toString()) : "NULL") . ");\n";
                    if (!$flags->isEmpty()) {
                        $code .= $flags->generateVersionDependentFlagCode("\tclass_entry->ce_flags |= %s;\n", $this->phpVersionIdMinimumCompatibility);
                    }
                    $code .= "#endif\n";
                }
            } else {
                $code .= "\tclass_entry = zend_register_internal_interface(&ce);\n";
                if (!$flags->isEmpty()) {
                    $code .= $flags->generateVersionDependentFlagCode("\tclass_entry->ce_flags |= %s;\n", $this->phpVersionIdMinimumCompatibility);
                }

            }
        }

        if ($this->exposedDocComment) {
            if (!$php84MinimumCompatibility) {
                $code .= "#if (PHP_VERSION_ID >= " . PHP_84_VERSION_ID . ")\n";
            }

            $code .= "\tclass_entry->doc_comment = " . $this->exposedDocComment->getInitCode() . "\n";

            if (!$php84MinimumCompatibility) {
                $code .= "#endif\n";
            }
        }

        $implements = array_map(
            function (Name $item) {
                return "class_entry_" . implode("_", $item->getParts());
            },
            $this->type === "interface" ? $this->extends : $this->implements
        );

        if (!empty($implements)) {
            $code .= "\tzend_class_implements(class_entry, " . count($implements) . ", " . implode(", ", $implements) . ");\n";
        }

        if ($this->alias) {
            $code .= "\tzend_register_class_alias(\"" . str_replace("\\", "\\\\", $this->alias) . "\", class_entry);\n";
        }

        $code .= generateCodeWithConditions(
            $this->constInfos,
            '',
            static fn (ConstInfo $const): string => $const->getDeclaration($allConstInfos)
        );

        foreach ($this->enumCaseInfos as $enumCase) {
            $code .= $enumCase->getDeclaration($allConstInfos);
        }

        foreach ($this->propertyInfos as $property) {
            $code .= $property->getDeclaration($allConstInfos);
        }
        // Reusable strings for wrapping conditional PHP 8.0+ code
        if ($php80MinimumCompatibility) {
            $php80CondStart = '';
            $php80CondEnd = '';
        } else {
            $php80CondStart = "\n#if (PHP_VERSION_ID >= " . PHP_80_VERSION_ID . ")";
            $php80CondEnd = "#endif\n";
        }

        $declaredStrings = [];

        if (!empty($this->attributes)) {
            $code .= $php80CondStart;

            foreach ($this->attributes as $key => $attribute) {
                $code .= $attribute->generateCode(
                    "zend_add_class_attribute(class_entry",
                    "class_{$escapedName}_$key",
                    $allConstInfos,
                    $this->phpVersionIdMinimumCompatibility,
                    $declaredStrings
                );
            }

            $code .= $php80CondEnd;
        }

        if ($attributeInitializationCode = generateConstantAttributeInitialization($this->constInfos, $allConstInfos, $this->phpVersionIdMinimumCompatibility, $this->cond, $declaredStrings)) {
            $code .= $php80CondStart;
            $code .= "\n" . $attributeInitializationCode;
            $code .= $php80CondEnd;
        }

        if ($attributeInitializationCode = generatePropertyAttributeInitialization($this->propertyInfos, $allConstInfos, $this->phpVersionIdMinimumCompatibility, $declaredStrings)) {
            $code .= $php80CondStart;
            $code .= "\n" . $attributeInitializationCode;
            $code .= $php80CondEnd;
        }

        if ($attributeInitializationCode = generateFunctionAttributeInitialization($this->funcInfos, $allConstInfos, $this->phpVersionIdMinimumCompatibility, $this->cond, $declaredStrings)) {
            $code .= $php80CondStart;
            $code .= "\n" . $attributeInitializationCode;
            $code .= $php80CondEnd;
        }

        $code .= "\n\treturn class_entry;\n";

        $code .= "}\n";

        if ($this->cond) {
            $code .= "#endif\n";
        }

        if ($this->type === "enum" && !$php81MinimumCompatibility) {
            $code .= "#endif\n";
        }

        return $code;
    }

    public function getCDeclarations(): string
    {
        if ($this->type !== "enum") {
            return '';
        }

        $code = '';

        if ($this->cond) {
            $code .= "#if {$this->cond}\n";
        }

        $cEnumName = 'zend_enum_' . str_replace('\\', '_', $this->name->toString());

        $code .= "typedef enum {$cEnumName} {\n";

        $i = 1;
        foreach ($this->enumCaseInfos as $case) {
            $cName = 'ZEND_ENUM_' . str_replace('\\', '_', $this->name->toString()) . '_' . $case->name->case;
            $code .= "\t{$cName} = {$i},\n";
            $i++;
        }

        $code .= "} {$cEnumName};\n";

        if ($this->cond) {
            $code .= "#endif\n";
        }

        return $code;
    }

    private function getFlagsByPhpVersion(): VersionFlags
    {
        $php70Flags = [];

        if ($this->type === "trait") {
            $php70Flags[] = "ZEND_ACC_TRAIT";
        }

        if ($this->flags & Modifiers::FINAL) {
            $php70Flags[] = "ZEND_ACC_FINAL";
        }

        if ($this->flags & Modifiers::ABSTRACT) {
            $php70Flags[] = "ZEND_ACC_ABSTRACT";
        }

        if ($this->isDeprecated) {
            $php70Flags[] = "ZEND_ACC_DEPRECATED";
        }

        $flags = new VersionFlags($php70Flags);

        if ($this->isStrictProperties) {
            $flags->addForVersionsAbove("ZEND_ACC_NO_DYNAMIC_PROPERTIES", PHP_80_VERSION_ID);
        }

        if ($this->isNotSerializable) {
            $flags->addForVersionsAbove("ZEND_ACC_NOT_SERIALIZABLE", PHP_81_VERSION_ID);
        }

        if ($this->flags & Modifiers::READONLY) {
            $flags->addForVersionsAbove("ZEND_ACC_READONLY_CLASS", PHP_82_VERSION_ID);
        }

        if (array_any(
            $this->attributes,
            static fn (AttributeInfo $attr): bool => $attr->class === "AllowDynamicProperties"
        )) {
            $flags->addForVersionsAbove("ZEND_ACC_ALLOW_DYNAMIC_PROPERTIES", PHP_82_VERSION_ID);
        }

        return $flags;
    }

    public function discardInfoForOldPhpVersions(?int $phpVersionIdMinimumCompatibility): void {
        $this->attributes = [];
        $this->flags &= ~Modifiers::READONLY;
        $this->exposedDocComment = null;
        $this->isStrictProperties = false;
        $this->isNotSerializable = false;

        foreach ($this->propertyInfos as $propertyInfo) {
            $propertyInfo->discardInfoForOldPhpVersions($phpVersionIdMinimumCompatibility);
        }
        $this->phpVersionIdMinimumCompatibility = $phpVersionIdMinimumCompatibility;
    }

    /**
     * @param array<string, ClassInfo> $classMap
     * @param array<string, ConstInfo> $allConstInfos
     */
    public function getClassSynopsisDocument(array $classMap, array $allConstInfos): ?string {
        $doc = new DOMDocument();
        $doc->formatOutput = true;
        $classSynopsis = $this->getClassSynopsisElement($doc, $classMap, $allConstInfos);
        if (!$classSynopsis) {
            return null;
        }

        $doc->appendChild($classSynopsis);

        return $doc->saveXML();
    }

    /**
     * @param array<string, ClassInfo> $classMap
     * @param array<string, ConstInfo> $allConstInfos
     */
    public function getClassSynopsisElement(DOMDocument $doc, array $classMap, array $allConstInfos): ?DOMElement {
        if ($this->type === "enum") {
            $classSynopsis = $doc->createElement("enumsynopsis");
        } else {
            $classSynopsis = $doc->createElement("classsynopsis");
            $classSynopsis->setAttribute("class", $this->type === "interface" ? "interface" : "class");
        }

        $namespace = $this->getNamespace();
        if ($namespace) {
            $classSynopsisIndentationLevel = 4;
            $classSynopsisIndentation = str_repeat(" ", $classSynopsisIndentationLevel);
            $packageSynopsis = $doc->createElement("packagesynopsis");
            $packageSynopsis->appendChild(new DOMText("\n$classSynopsisIndentation"));
            $package = $doc->createElement("package", $namespace);
            $packageSynopsis->appendChild($package);
            $packageSynopsis->appendChild(new DOMText("\n\n$classSynopsisIndentation"));
            $packageSynopsis->appendChild($classSynopsis);
            $packageSynopsis->appendChild(new DOMText("\n   "));
            $root = $packageSynopsis;
        } else {
            $root = $classSynopsis;
            $classSynopsisIndentationLevel = 3;
            $classSynopsisIndentation = str_repeat(" ", $classSynopsisIndentationLevel);
        }

        $classSynopsis->appendChild(new DOMText("\n$classSynopsisIndentation "));

        if ($this->type === "enum") {
            $enumName = $doc->createElement("enumname", $this->getClassName());
            $classSynopsis->appendChild($enumName);

            foreach ($this->enumCaseInfos as $enumCaseInfo) {
                $classSynopsis->appendChild(new DOMText("\n\n$classSynopsisIndentation "));
                $enumItemElement = $enumCaseInfo->getEnumSynopsisItemElement($doc, $allConstInfos, $classSynopsisIndentationLevel + 1);
                $classSynopsis->appendChild($enumItemElement);
            }
        } else {
            $exceptionOverride = $this->type === "class" && $this->isException($classMap) ? "exception" : null;
            $ooElement = self::createOoElement($doc, $this, $exceptionOverride, true, null, $classSynopsisIndentationLevel + 1);
            if (!$ooElement) {
                return null;
            }
            $classSynopsis->appendChild($ooElement);

            foreach ($this->extends as $k => $parent) {
                $parentInfo = $classMap[$parent->toString()] ?? null;
                if ($parentInfo === null) {
                    throw new Exception("Missing parent class " . $parent->toString());
                }

                $ooElement = self::createOoElement(
                    $doc,
                    $parentInfo,
                    null,
                    false,
                    $k === 0 ? "extends" : null,
                    $classSynopsisIndentationLevel + 1
                );
                if (!$ooElement) {
                    return null;
                }

                $classSynopsis->appendChild(new DOMText("\n\n$classSynopsisIndentation "));
                $classSynopsis->appendChild($ooElement);
            }

            foreach ($this->implements as $k => $interface) {
                $interfaceInfo = $classMap[$interface->toString()] ?? null;
                if (!$interfaceInfo) {
                    throw new Exception("Missing implemented interface " . $interface->toString());
                }

                $ooElement = self::createOoElement($doc, $interfaceInfo, null, false, $k === 0 ? "implements" : null, $classSynopsisIndentationLevel + 1);
                if (!$ooElement) {
                    return null;
                }
                $classSynopsis->appendChild(new DOMText("\n\n$classSynopsisIndentation "));
                $classSynopsis->appendChild($ooElement);
            }

            /** @var array<string, Name> $parentsWithInheritedConstants */
            $parentsWithInheritedConstants = [];
            /** @var array<string, Name> $parentsWithInheritedProperties */
            $parentsWithInheritedProperties = [];
            /** @var array<int, array{name: Name, types: int[]}> $parentsWithInheritedMethods */
            $parentsWithInheritedMethods = [];

            $this->collectInheritedMembers(
                $parentsWithInheritedConstants,
                $parentsWithInheritedProperties,
                $parentsWithInheritedMethods,
                $this->hasConstructor(),
                $classMap
            );

            $this->appendInheritedMemberSectionToClassSynopsis(
                $doc,
                $classSynopsis,
                $parentsWithInheritedConstants,
                "&Constants;",
                "&InheritedConstants;",
                $classSynopsisIndentationLevel + 1
            );

            if (!empty($this->constInfos)) {
                $classSynopsis->appendChild(new DOMText("\n\n$classSynopsisIndentation "));
                $classSynopsisInfo = $doc->createElement("classsynopsisinfo", "&Constants;");
                $classSynopsisInfo->setAttribute("role", "comment");
                $classSynopsis->appendChild($classSynopsisInfo);

                foreach ($this->constInfos as $constInfo) {
                    $classSynopsis->appendChild(new DOMText("\n$classSynopsisIndentation "));
                    $fieldSynopsisElement = $constInfo->getFieldSynopsisElement($doc, $allConstInfos, $classSynopsisIndentationLevel + 1);
                    $classSynopsis->appendChild($fieldSynopsisElement);
                }
            }

            if (!empty($this->propertyInfos)) {
                $classSynopsis->appendChild(new DOMText("\n\n$classSynopsisIndentation "));
                $classSynopsisInfo = $doc->createElement("classsynopsisinfo", "&Properties;");
                $classSynopsisInfo->setAttribute("role", "comment");
                $classSynopsis->appendChild($classSynopsisInfo);

                foreach ($this->propertyInfos as $propertyInfo) {
                    $classSynopsis->appendChild(new DOMText("\n$classSynopsisIndentation "));
                    $fieldSynopsisElement = $propertyInfo->getFieldSynopsisElement($doc, $allConstInfos, $classSynopsisIndentationLevel + 1);
                    $classSynopsis->appendChild($fieldSynopsisElement);
                }
            }

            $this->appendInheritedMemberSectionToClassSynopsis(
                $doc,
                $classSynopsis,
                $parentsWithInheritedProperties,
                "&Properties;",
                "&InheritedProperties;",
                $classSynopsisIndentationLevel + 1
            );
        }

        if (!empty($this->funcInfos)) {
            $classSynopsis->appendChild(new DOMText("\n\n$classSynopsisIndentation "));
            $classSynopsisInfo = $doc->createElement("classsynopsisinfo", "&Methods;");
            $classSynopsisInfo->setAttribute("role", "comment");
            $classSynopsis->appendChild($classSynopsisInfo);

            $classReference = self::getClassSynopsisReference($this->name);
            $escapedName = addslashes($this->name->__toString());

            if ($this->hasConstructor()) {
                $classSynopsis->appendChild(new DOMText("\n$classSynopsisIndentation "));
                $includeElement = $this->createIncludeElement(
                    $doc,
                    "xmlns(db=http://docbook.org/ns/docbook) xpointer(id('$classReference')/db:refentry/db:refsect1[@role='description']/descendant::db:constructorsynopsis[@role='$escapedName'])",
                    $classSynopsisIndentationLevel + 1
                );
                $classSynopsis->appendChild($includeElement);
            }

            if ($this->hasMethods()) {
                $classSynopsis->appendChild(new DOMText("\n$classSynopsisIndentation "));
                $includeElement = $this->createIncludeElement(
                    $doc,
                    "xmlns(db=http://docbook.org/ns/docbook) xpointer(id('$classReference')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[@role='$escapedName'])",
                    $classSynopsisIndentationLevel + 1
                );
                $classSynopsis->appendChild($includeElement);
            }

            if ($this->hasDestructor()) {
                $classSynopsis->appendChild(new DOMText("\n$classSynopsisIndentation "));
                $includeElement = $this->createIncludeElement(
                    $doc,
                    "xmlns(db=http://docbook.org/ns/docbook) xpointer(id('$classReference')/db:refentry/db:refsect1[@role='description']/descendant::db:destructorsynopsis[@role='$escapedName'])",
                    $classSynopsisIndentationLevel + 1
                );
                $classSynopsis->appendChild($includeElement);
            }
        }

        if (!empty($parentsWithInheritedMethods)) {
            $classSynopsis->appendChild(new DOMText("\n\n$classSynopsisIndentation "));
            $classSynopsisInfo = $doc->createElement("classsynopsisinfo", "&InheritedMethods;");
            $classSynopsisInfo->setAttribute("role", "comment");
            $classSynopsis->appendChild($classSynopsisInfo);

            foreach ($parentsWithInheritedMethods as $parent) {
                $parentName = $parent["name"];
                $parentMethodsynopsisTypes = $parent["types"];

                $parentReference = self::getClassSynopsisReference($parentName);
                $escapedParentName = addslashes($parentName->__toString());

                foreach ($parentMethodsynopsisTypes as $parentMethodsynopsisType) {
                    $classSynopsis->appendChild(new DOMText("\n$classSynopsisIndentation "));
                    $includeElement = $this->createIncludeElement(
                        $doc,
                        "xmlns(db=http://docbook.org/ns/docbook) xpointer(id('$parentReference')/db:refentry/db:refsect1[@role='description']/descendant::db:{$parentMethodsynopsisType}[@role='$escapedParentName'])",
                        $classSynopsisIndentationLevel + 1
                    );

                    $classSynopsis->appendChild($includeElement);
                }
            }
        }

        $classSynopsis->appendChild(new DOMText("\n$classSynopsisIndentation"));

        return $root;
    }

    private static function createOoElement(
        DOMDocument $doc,
        ClassInfo $classInfo,
        ?string $typeOverride,
        bool $isMainClass,
        ?string $modifierOverride,
        int $indentationLevel
    ): ?DOMElement {
        $indentation = str_repeat(" ", $indentationLevel);

        if ($classInfo->type !== "class" && $classInfo->type !== "interface") {
            echo "Warning: Class synopsis generation is not implemented for " . $classInfo->type . " of type " . $classInfo->name . "\n";
            return null;
        }

        $type = $typeOverride !== null ? $typeOverride : $classInfo->type;

        $ooElement = $doc->createElement("oo$type");
        $ooElement->appendChild(new DOMText("\n$indentation "));
        if ($modifierOverride !== null) {
            $ooElement->appendChild($doc->createElement('modifier', $modifierOverride));
            $ooElement->appendChild(new DOMText("\n$indentation "));
        } elseif ($isMainClass) {
            foreach ($classInfo->attributes as $attribute) {
                $modifier = $doc->createElement("modifier", "#[\\" . $attribute->class . "]");
                $modifier->setAttribute("role", "attribute");
                $ooElement->appendChild($modifier);
                $ooElement->appendChild(new DOMText("\n$indentation "));
            }

            if ($classInfo->flags & Modifiers::FINAL) {
                $ooElement->appendChild($doc->createElement('modifier', 'final'));
                $ooElement->appendChild(new DOMText("\n$indentation "));
            }
            if ($classInfo->flags & Modifiers::ABSTRACT) {
                $ooElement->appendChild($doc->createElement('modifier', 'abstract'));
                $ooElement->appendChild(new DOMText("\n$indentation "));
            }
            if ($classInfo->flags & Modifiers::READONLY) {
                $ooElement->appendChild($doc->createElement('modifier', 'readonly'));
                $ooElement->appendChild(new DOMText("\n$indentation "));
            }
        }

        $nameElement = $doc->createElement("{$type}name", $isMainClass ? $classInfo->getClassName() : $classInfo->name->toString());
        $ooElement->appendChild($nameElement);
        $ooElement->appendChild(new DOMText("\n$indentation"));

        return $ooElement;
    }

    public static function getClassSynopsisFilename(Name $name): string {
        return strtolower(str_replace("_", "-", implode('-', $name->getParts())));
    }

    private static function getClassSynopsisReference(Name $name): string {
        return "class." . self::getClassSynopsisFilename($name);
    }

    /**
     * @param array<string, Name> $parentsWithInheritedConstants
     * @param array<string, Name> $parentsWithInheritedProperties
     * @param array<string, array{name: Name, types: int[]}> $parentsWithInheritedMethods
     * @param array<string, ClassInfo> $classMap
     */
    private function collectInheritedMembers(
        array &$parentsWithInheritedConstants,
        array &$parentsWithInheritedProperties,
        array &$parentsWithInheritedMethods,
        bool $hasConstructor,
        array $classMap
    ): void {
        foreach ($this->extends as $parent) {
            $parentInfo = $classMap[$parent->toString()] ?? null;
            $parentName = $parent->toString();

            if (!$parentInfo) {
                throw new Exception("Missing parent class $parentName");
            }

            if (!empty($parentInfo->constInfos) && !isset($parentsWithInheritedConstants[$parentName])) {
                $parentsWithInheritedConstants[] = $parent;
            }

            if (!empty($parentInfo->propertyInfos) && !isset($parentsWithInheritedProperties[$parentName])) {
                $parentsWithInheritedProperties[$parentName] = $parent;
            }

            if (!$hasConstructor && $parentInfo->hasNonPrivateConstructor()) {
                $parentsWithInheritedMethods[$parentName]["name"] = $parent;
                $parentsWithInheritedMethods[$parentName]["types"][] = "constructorsynopsis";
            }

            if ($parentInfo->hasMethods()) {
                $parentsWithInheritedMethods[$parentName]["name"] = $parent;
                $parentsWithInheritedMethods[$parentName]["types"][] = "methodsynopsis";
            }

            if ($parentInfo->hasDestructor()) {
                $parentsWithInheritedMethods[$parentName]["name"] = $parent;
                $parentsWithInheritedMethods[$parentName]["types"][] = "destructorsynopsis";
            }

            $parentInfo->collectInheritedMembers(
                $parentsWithInheritedConstants,
                $parentsWithInheritedProperties,
                $parentsWithInheritedMethods,
                $hasConstructor,
                $classMap
            );
        }

        foreach ($this->implements as $parent) {
            $parentInfo = $classMap[$parent->toString()] ?? null;
            if (!$parentInfo) {
                throw new Exception("Missing parent interface " . $parent->toString());
            }

            if (!empty($parentInfo->constInfos) && !isset($parentsWithInheritedConstants[$parent->toString()])) {
                $parentsWithInheritedConstants[$parent->toString()] = $parent;
            }

            $unusedParentsWithInheritedProperties = [];
            $unusedParentsWithInheritedMethods = [];

            $parentInfo->collectInheritedMembers(
                $parentsWithInheritedConstants,
                $unusedParentsWithInheritedProperties,
                $unusedParentsWithInheritedMethods,
                $hasConstructor,
                $classMap
            );
        }
    }

    /** @param array<string, ClassInfo> $classMap */
    private function isException(array $classMap): bool
    {
        if ($this->name->toString() === "Throwable") {
            return true;
        }

        foreach ($this->extends as $parentName) {
            $parent = $classMap[$parentName->toString()] ?? null;
            if ($parent === null) {
                throw new Exception("Missing parent class " . $parentName->toString());
            }

            if ($parent->isException($classMap)) {
                return true;
            }
        }

        if ($this->type === "class") {
            foreach ($this->implements as $interfaceName) {
                $interface = $classMap[$interfaceName->toString()] ?? null;
                if ($interface === null) {
                    throw new Exception("Missing implemented interface " . $interfaceName->toString());
                }

                if ($interface->isException($classMap)) {
                    return true;
                }
            }
        }

        return false;
    }

    private function hasConstructor(): bool
    {
        return array_any(
            $this->funcInfos,
            static fn (FuncInfo $funcInfo): bool => $funcInfo->name->isConstructor()
        );
    }

    private function hasNonPrivateConstructor(): bool
    {
        return array_any(
            $this->funcInfos,
            static fn (FuncInfo $funcInfo): bool => $funcInfo->name->isConstructor() && !($funcInfo->flags & Modifiers::PRIVATE)
        );
    }

    private function hasDestructor(): bool
    {
        return array_any(
            $this->funcInfos,
            static fn (FuncInfo $funcInfo): bool => $funcInfo->name->isDestructor()
        );
    }

    private function hasMethods(): bool
    {
        return array_any(
            $this->funcInfos,
            static fn (FuncInfo $funcInfo): bool => !$funcInfo->name->isConstructor() && !$funcInfo->name->isDestructor()
        );
    }

    public function getNamespace(): ?string {
        if ($this->name->isQualified()) {
            return $this->name->slice(0, -1)->toString();
        }

        return null;
    }

    public function getClassName(): string {
        return $this->name->getLast();
    }

    private function createIncludeElement(DOMDocument $doc, string $query, int $indentationLevel): DOMElement
    {
        $indentation = str_repeat(" ", $indentationLevel);

        $includeElement = $doc->createElement("xi:include");
        $attr = $doc->createAttribute("xpointer");
        $attr->value = $query;
        $includeElement->appendChild($attr);
        $fallbackElement = $doc->createElement("xi:fallback");
        $includeElement->appendChild(new DOMText("\n$indentation "));
        $includeElement->appendChild($fallbackElement);
        $includeElement->appendChild(new DOMText("\n$indentation"));

        return $includeElement;
    }

    public function __clone()
    {
        $this->constInfos = array_map((\clone)(...), $this->constInfos);
        $this->propertyInfos = array_map((\clone)(...), $this->propertyInfos);
        $this->funcInfos = array_map((\clone)(...), $this->funcInfos);
    }

    /**
     * @param Name[] $parents
     */
    private function appendInheritedMemberSectionToClassSynopsis(DOMDocument $doc, DOMElement $classSynopsis, array $parents, string $label, string $inheritedLabel, int $indentationLevel): void
    {
        if (empty($parents)) {
            return;
        }

        $indentation = str_repeat(" ", $indentationLevel);

        $classSynopsis->appendChild(new DOMText("\n\n$indentation"));
        $classSynopsisInfo = $doc->createElement("classsynopsisinfo", "$inheritedLabel");
        $classSynopsisInfo->setAttribute("role", "comment");
        $classSynopsis->appendChild($classSynopsisInfo);

        foreach ($parents as $parent) {
            $classSynopsis->appendChild(new DOMText("\n$indentation"));
            $parentReference = self::getClassSynopsisReference($parent);

            $includeElement = $this->createIncludeElement(
                $doc,
                "xmlns(db=http://docbook.org/ns/docbook) xpointer(id('$parentReference')/db:partintro/db:section/db:classsynopsis/db:fieldsynopsis[preceding-sibling::db:classsynopsisinfo[1][@role='comment' and text()='$label']]))",
                $indentationLevel
            );
            $classSynopsis->appendChild($includeElement);
        }
    }
}

class FileInfo {
    /** @var string[] */
    public array $dependencies = [];
    /** @var ConstInfo[] */
    public array $constInfos = [];
    /** @var FuncInfo[] */
    private array $funcInfos = [];
    /** @var ClassInfo[] */
    public array $classInfos = [];
    private bool $generateFunctionEntries = false;
    private string $declarationPrefix = "";
    private bool $generateClassEntries = false;
    private bool $generateCEnums = false;
    private bool $isUndocumentable = false;
    private bool $legacyArginfoGeneration = false;
    private ?int $minimumPhpVersionIdCompatibility = null;

    /** @param array<int, DocCommentTag> $fileTags */
    public function __construct(array $fileTags) {
        foreach ($fileTags as $tag) {
            if ($tag->name === 'generate-function-entries') {
                $this->generateFunctionEntries = true;
                $this->declarationPrefix = $tag->value ? $tag->value . " " : "";
            } else if ($tag->name === 'generate-legacy-arginfo') {
                if ($tag->value && !in_array((int) $tag->value, ALL_PHP_VERSION_IDS, true)) {
                    throw new Exception(
                        "Legacy PHP version must be one of: \"" . PHP_70_VERSION_ID . "\" (PHP 7.0), \"" . PHP_80_VERSION_ID . "\" (PHP 8.0), " .
                        "\"" . PHP_81_VERSION_ID . "\" (PHP 8.1), \"" . PHP_82_VERSION_ID . "\" (PHP 8.2), \"" . PHP_83_VERSION_ID . "\" (PHP 8.3), " .
                        "\"" . PHP_84_VERSION_ID . "\" (PHP 8.4), \"" . PHP_85_VERSION_ID . "\" (PHP 8.5), \"" . $tag->value . "\" provided"
                    );
                }

                $this->minimumPhpVersionIdCompatibility = ($tag->value ? (int) $tag->value : PHP_70_VERSION_ID);
            } else if ($tag->name === 'generate-class-entries') {
                $this->generateClassEntries = true;
                $this->declarationPrefix = $tag->value ? $tag->value . " " : "";
            } else if ($tag->name === 'undocumentable') {
                $this->isUndocumentable = true;
            } else if ($tag->name === 'generate-c-enums') {
                $this->generateCEnums = true;
            }
        }

        // Generating class entries require generating function/method entries
        if ($this->generateClassEntries && !$this->generateFunctionEntries) {
            $this->generateFunctionEntries = true;
        }
    }

    /**
     * @return iterable<FuncInfo>
     */
    public function getAllFuncInfos(): iterable {
        yield from $this->funcInfos;
        foreach ($this->classInfos as $classInfo) {
            yield from $classInfo->funcInfos;
        }
    }

    /** @return array<string, ConstInfo> */
    public function getAllConstInfos(): array {
        $result = [];

        foreach ($this->constInfos as $constInfo) {
            $result[$constInfo->name->__toString()] = $constInfo;
        }

        foreach ($this->classInfos as $classInfo) {
            foreach ($classInfo->constInfos as $constInfo) {
                $result[$constInfo->name->__toString()] = $constInfo;
            }
        }

        return $result;
    }

    public function __clone()
    {
        $this->constInfos = array_map((\clone)(...), $this->constInfos);
        $this->funcInfos = array_map((\clone)(...), $this->funcInfos);
        $this->classInfos = array_map((\clone)(...), $this->classInfos);
    }

    private function getMinimumPhpVersionIdCompatibility(): ?int {
        // Non-legacy arginfo files are always PHP 8.0+ compatible
        if (!$this->legacyArginfoGeneration &&
            $this->minimumPhpVersionIdCompatibility !== null &&
            $this->minimumPhpVersionIdCompatibility < PHP_80_VERSION_ID
        ) {
            return PHP_80_VERSION_ID;
        }

        return $this->minimumPhpVersionIdCompatibility;
    }

    public function shouldGenerateLegacyArginfo(): bool {
        return $this->minimumPhpVersionIdCompatibility !== null && $this->minimumPhpVersionIdCompatibility < PHP_80_VERSION_ID;
    }

    public function getLegacyVersion(): FileInfo {
        $legacyFileInfo = clone $this;
        $legacyFileInfo->legacyArginfoGeneration = true;
        $phpVersionIdMinimumCompatibility = $legacyFileInfo->getMinimumPhpVersionIdCompatibility();

        foreach ($legacyFileInfo->getAllFuncInfos() as $funcInfo) {
            $funcInfo->discardInfoForOldPhpVersions($phpVersionIdMinimumCompatibility);
        }
        foreach ($legacyFileInfo->classInfos as $classInfo) {
            $classInfo->discardInfoForOldPhpVersions($phpVersionIdMinimumCompatibility);
        }
        foreach ($legacyFileInfo->getAllConstInfos() as $constInfo) {
            $constInfo->discardInfoForOldPhpVersions($phpVersionIdMinimumCompatibility);
        }
        return $legacyFileInfo;
    }

    public static function parseStubFile(string $code): FileInfo {
        $parser = new PhpParser\Parser\Php7(new PhpParser\Lexer\Emulative());
        $nodeTraverser = new PhpParser\NodeTraverser;
        $nodeTraverser->addVisitor(new PhpParser\NodeVisitor\NameResolver);
        $prettyPrinter = new class extends Standard {
            protected function pName_FullyQualified(Name\FullyQualified $node): string {
                return implode('\\', $node->getParts());
            }
        };

        $stmts = $parser->parse($code);
        $nodeTraverser->traverse($stmts);

        $fileTags = DocCommentTag::parseDocComments(self::getFileDocComments($stmts));
        $fileInfo = new FileInfo($fileTags);

        $fileInfo->handleStatements($stmts, $prettyPrinter);
        return $fileInfo;
    }

    /** @return DocComment[] */
    private static function getFileDocComments(array $stmts): array {
        if (empty($stmts)) {
            return [];
        }

        return array_filter(
            $stmts[0]->getComments(),
            static fn ($comment): bool => $comment instanceof DocComment
        );
    }

    private function handleStatements(array $stmts, PrettyPrinterAbstract $prettyPrinter): void {
        $conds = [];
        foreach ($stmts as $stmt) {
            $cond = self::handlePreprocessorConditions($conds, $stmt);

            if ($stmt instanceof Stmt\Nop) {
                continue;
            }

            if ($stmt instanceof Stmt\Namespace_) {
                $this->handleStatements($stmt->stmts, $prettyPrinter);
                continue;
            }

            if ($stmt instanceof Stmt\Const_) {
                foreach ($stmt->consts as $const) {
                    $this->constInfos[] = parseConstLike(
                        $prettyPrinter,
                        new ConstName($const->namespacedName, $const->name->toString()),
                        $const,
                        0,
                        null,
                        $stmt->getComments(),
                        $cond,
                        $this->isUndocumentable,
                        $this->getMinimumPhpVersionIdCompatibility(),
                        AttributeInfo::createFromGroups($stmt->attrGroups)
                    );
                }
                continue;
            }

            if ($stmt instanceof Stmt\Function_) {
                $this->funcInfos[] = parseFunctionLike(
                    $prettyPrinter,
                    new FunctionName($stmt->namespacedName),
                    0,
                    0,
                    $stmt,
                    $cond,
                    $this->isUndocumentable,
                    $this->getMinimumPhpVersionIdCompatibility()
                );
                continue;
            }

            if ($stmt instanceof Stmt\ClassLike) {
                $className = $stmt->namespacedName;
                $constInfos = [];
                $propertyInfos = [];
                $methodInfos = [];
                $enumCaseInfos = [];
                foreach ($stmt->stmts as $classStmt) {
                    $cond = self::handlePreprocessorConditions($conds, $classStmt);
                    if ($classStmt instanceof Stmt\Nop) {
                        continue;
                    }

                    $classFlags = $stmt instanceof Class_ ? $stmt->flags : 0;
                    $abstractFlag = $stmt instanceof Stmt\Interface_ ? Modifiers::ABSTRACT : 0;

                    if ($classStmt instanceof Stmt\ClassConst) {
                        foreach ($classStmt->consts as $const) {
                            $constInfos[] = parseConstLike(
                                $prettyPrinter,
                                new ClassConstName($className, $const->name->toString()),
                                $const,
                                $classStmt->flags,
                                $classStmt->type,
                                $classStmt->getComments(),
                                $cond,
                                $this->isUndocumentable,
                                $this->getMinimumPhpVersionIdCompatibility(),
                                AttributeInfo::createFromGroups($classStmt->attrGroups)
                            );
                        }
                    } else if ($classStmt instanceof Stmt\Property) {
                        if (!($classStmt->flags & Class_::VISIBILITY_MODIFIER_MASK)) {
                            throw new Exception("Visibility modifier is required");
                        }
                        foreach ($classStmt->props as $property) {
                            $propertyInfos[] = parseProperty(
                                $className,
                                $classFlags,
                                $classStmt->flags,
                                $property,
                                $classStmt->type,
                                $classStmt->getComments(),
                                $prettyPrinter,
                                $this->getMinimumPhpVersionIdCompatibility(),
                                AttributeInfo::createFromGroups($classStmt->attrGroups)
                            );
                        }
                    } else if ($classStmt instanceof Stmt\ClassMethod) {
                        if (!($classStmt->flags & Class_::VISIBILITY_MODIFIER_MASK)) {
                            throw new Exception("Visibility modifier is required");
                        }
                        $methodInfos[] = parseFunctionLike(
                            $prettyPrinter,
                            new MethodName($className, $classStmt->name->toString()),
                            $classFlags,
                            $classStmt->flags | $abstractFlag,
                            $classStmt,
                            $cond,
                            $this->isUndocumentable,
                            $this->getMinimumPhpVersionIdCompatibility()
                        );
                    } else if ($classStmt instanceof Stmt\EnumCase) {
                        $enumCaseInfos[] = new EnumCaseInfo(
                            new EnumCaseName($className, $classStmt->name->toString()),
                            $classStmt->expr,
                            $classStmt->expr ? $prettyPrinter->prettyPrintExpr($classStmt->expr) : null,
                        );
                    } else {
                        throw new Exception("Not implemented {$classStmt->getType()}");
                    }
                }

                $this->classInfos[] = parseClass(
                    $className,
                    $stmt,
                    $constInfos,
                    $propertyInfos,
                    $methodInfos,
                    $enumCaseInfos,
                    $cond,
                    $this->getMinimumPhpVersionIdCompatibility(),
                    $this->isUndocumentable
                );
                continue;
            }

            if ($stmt instanceof Stmt\Expression) {
                $expr = $stmt->expr;
                if ($expr instanceof Expr\Include_) {
                    $this->dependencies[] = (string)EvaluatedValue::createFromExpression($expr->expr, null, null, [])->value;
                    continue;
                }
            }

            if ($stmt instanceof Stmt\Use_ || $stmt instanceof Stmt\GroupUse) {
                // use statements are resolved by NameResolver before this point
                continue;
            }

            throw new Exception("Unexpected node {$stmt->getType()}");
        }
        if (!empty($conds)) {
            throw new Exception("Unterminated preprocessor conditions");
        }
    }

    private static function handlePreprocessorConditions(array &$conds, Stmt $stmt): ?string {
        foreach ($stmt->getComments() as $comment) {
            $text = trim($comment->getText());
            if (preg_match('/^#\s*if\s+(.+)$/', $text, $matches)) {
                $conds[] = $matches[1];
            } else if (preg_match('/^#\s*ifdef\s+(.+)$/', $text, $matches)) {
                $conds[] = "defined($matches[1])";
            } else if (preg_match('/^#\s*ifndef\s+(.+)$/', $text, $matches)) {
                $conds[] = "!defined($matches[1])";
            } else if (preg_match('/^#\s*else$/', $text)) {
                if (empty($conds)) {
                    throw new Exception("Encountered else without corresponding #if");
                }
                $cond = array_pop($conds);
                $conds[] = "!($cond)";
            } else if (preg_match('/^#\s*endif$/', $text)) {
                if (empty($conds)) {
                    throw new Exception("Encountered #endif without corresponding #if");
                }
                array_pop($conds);
            } else if ($text[0] === '#') {
                throw new Exception("Unrecognized preprocessor directive \"$text\"");
            }
        }

        return empty($conds) ? null : implode(' && ', $conds);
    }

    /** @param array<string, ConstInfo> $allConstInfos */
    public function generateClassEntryCode(array $allConstInfos): string {
        $code = "";

        foreach ($this->classInfos as $class) {
            $code .= "\n" . $class->getRegistration($allConstInfos);
        }

        return $code;
    }

    public function generateCDeclarations(): string {
        $code = "";

        if (!$this->generateCEnums) {
            return $code;
        }

        foreach ($this->classInfos as $class) {
            $cdecl = $class->getCDeclarations();
            if ($cdecl !== '') {
                $code .= "\n" . $cdecl;
            }
        }

        return $code;
    }


    /**
     * @param array<string, ConstInfo> $allConstInfos
     * @return array{string, string}
     */
    public function generateArgInfoCode(
        string $stubFilenameWithoutExtension,
        array $allConstInfos,
        string $stubHash
    ): array {
        $code = "";

        $generatedFuncInfos = [];

        $argInfoCode = generateCodeWithConditions(
            $this->getAllFuncInfos(), "\n",
            function (FuncInfo $funcInfo) use (&$generatedFuncInfos) {
                /* If there already is an equivalent arginfo structure, only emit a #define */
                if ($generatedFuncInfo = $funcInfo->findEquivalent($generatedFuncInfos)) {
                    $code = sprintf(
                        "#define %s %s\n",
                        $funcInfo->getArgInfoName(), $generatedFuncInfo->getArgInfoName()
                    );
                } else {
                    $code = $funcInfo->toArgInfoCode($this->getMinimumPhpVersionIdCompatibility());
                }

                $generatedFuncInfos[] = $funcInfo;
                return $code;
            }
        );

        if ($argInfoCode !== "") {
            $code .= "$argInfoCode\n";
        }

        if ($this->generateFunctionEntries) {
            $framelessFunctionCode = generateCodeWithConditions(
                $this->getAllFuncInfos(), "\n",
                static function (FuncInfo $funcInfo) {
                    return $funcInfo->getFramelessDeclaration();
                }
            );

            if ($framelessFunctionCode !== "") {
                $code .= "$framelessFunctionCode\n";
            }

            $generatedFunctionDeclarations = [];
            $code .= generateCodeWithConditions(
                $this->getAllFuncInfos(), "",
                function (FuncInfo $funcInfo) use (&$generatedFunctionDeclarations) {
                    $key = $funcInfo->getDeclarationKey();
                    if (isset($generatedFunctionDeclarations[$key])) {
                        return null;
                    }

                    $generatedFunctionDeclarations[$key] = true;
                    return $this->declarationPrefix . $funcInfo->getDeclaration();
                }
            );

            $code .= generateFunctionEntries(null, $this->funcInfos);

            foreach ($this->classInfos as $classInfo) {
                $code .= generateFunctionEntries($classInfo->name, $classInfo->funcInfos, $classInfo->cond);
            }
        }

        $php80MinimumCompatibility = $this->getMinimumPhpVersionIdCompatibility() === null || $this->getMinimumPhpVersionIdCompatibility() >= PHP_80_VERSION_ID;

        if ($this->generateClassEntries) {
            $declaredStrings = [];
            $attributeInitializationCode = generateFunctionAttributeInitialization($this->funcInfos, $allConstInfos, $this->getMinimumPhpVersionIdCompatibility(), null, $declaredStrings);
            $attributeInitializationCode .= generateGlobalConstantAttributeInitialization($this->constInfos, $allConstInfos, $this->getMinimumPhpVersionIdCompatibility(), null, $declaredStrings);
            if ($attributeInitializationCode) {
                if (!$php80MinimumCompatibility) {
                    $attributeInitializationCode = "\n#if (PHP_VERSION_ID >= " . PHP_80_VERSION_ID . ")" . $attributeInitializationCode . "#endif\n";
                }
            }

            if ($attributeInitializationCode !== "" || !empty($this->constInfos)) {
                $code .= "\nstatic void register_{$stubFilenameWithoutExtension}_symbols(int module_number)\n";
                $code .= "{\n";

                $code .= generateCodeWithConditions(
                    $this->constInfos,
                    '',
                    static fn (ConstInfo $constInfo): string => $constInfo->getDeclaration($allConstInfos)
                );

                if ($attributeInitializationCode !== "" && $this->constInfos) {
                    $code .= "\n";
                }

                $code .= $attributeInitializationCode;
                $code .= "}\n";
            }

            $code .= $this->generateClassEntryCode($allConstInfos);
        }

        $hasDeclFile = false;
        $declCode = $this->generateCDeclarations();
        if ($declCode !== '') {
            $hasDeclFile = true;
            $headerName = "ZEND_" . strtoupper($stubFilenameWithoutExtension) . "_DECL_{$stubHash}_H";
            $declCode = "/* This is a generated file, edit {$stubFilenameWithoutExtension}.stub.php instead.\n"
                . " * Stub hash: $stubHash */\n"
                . "\n"
                . "#ifndef {$headerName}\n"
                . "#define {$headerName}\n"
                . $declCode . "\n"
                . "#endif /* {$headerName} */\n";
        }

        $code = "/* This is a generated file, edit {$stubFilenameWithoutExtension}.stub.php instead.\n"
            . " * Stub hash: $stubHash"
            . ($hasDeclFile ? "\n * Has decl header: yes */\n" : " */\n")
            . $code;

        return [$code, $declCode];
    }
}

class DocCommentTag {

    public function __construct(
        public readonly string $name,
        public readonly ?string $value,
    ) {}

    public function getValue(): string {
        if ($this->value === null) {
            throw new Exception("@$this->name does not have a value");
        }

        return $this->value;
    }

    public function getType(): string {
        $value = $this->getValue();

        $matches = [];

        if ($this->name === "param") {
            preg_match('/^\s*([\w\|\\\\\[\]<>, ]+)\s*(?:[{(]|(\.\.\.)?\$\w+).*$/', $value, $matches);
        } elseif ($this->name === "return" || $this->name === "var") {
            preg_match('/^\s*([\w\|\\\\\[\]<>, ]+)/', $value, $matches);
        }

        if (!isset($matches[1])) {
            throw new Exception("@$this->name doesn't contain a type or has an invalid format \"$value\"");
        }

        return trim($matches[1]);
    }

    public function getVariableName(): string {
        $value = $this->value;
        if ($value === null || strlen($value) === 0) {
            throw new Exception("@$this->name doesn't have any value");
        }

        $matches = [];

        if ($this->name === "param") {
            // Allow for parsing extended types like callable(string):mixed in docblocks
            preg_match('/^\s*(?<type>[\w\|\\\\]+(?<parens>\((?<inparens>(?:(?&parens)|[^(){}[\]<>]*+))++\)|\{(?&inparens)\}|\[(?&inparens)\]|<(?&inparens)>)*+(?::(?&type))?)\s*(\.\.\.)?\$(?<name>\w+).*$/', $value, $matches);
        } elseif ($this->name === "prefer-ref") {
            preg_match('/^\s*\$(?<name>\w+).*$/', $value, $matches);
        }

        if (!isset($matches["name"])) {
            throw new Exception("@$this->name doesn't contain a variable name or has an invalid format \"$value\"");
        }

        return $matches["name"];
    }

    /** @return DocCommentTag[] */
    public static function parseDocComments(array $comments): array {
        $tags = [];
        foreach ($comments as $comment) {
            if (!($comment instanceof DocComment)) {
                continue;
            }
            $commentText = substr($comment->getText(), 2, -2);
            foreach (explode("\n", $commentText) as $commentLine) {
                $regex = '/^\*\s*@([a-z-]+)(?:\s+(.+))?$/';
                if (preg_match($regex, trim($commentLine), $matches)) {
                    $tags[] = new DocCommentTag($matches[1], $matches[2] ?? null);
                }
            }
        }

        return $tags;
    }

    /**
     * @param DocCommentTag[] $tags
     * @return array<string, ?string> Mapping tag names to the value (or null),
     *   if a tag is present multiple times the last value is used
     */
    public static function makeTagMap(array $tags): array {
        $map = [];
        foreach ($tags as $tag) {
            $map[$tag->name] = $tag->value;
        }
        return $map;
    }
}

// Instances of ExposedDocComment are immutable and do not need to be cloned
// when held by an object that is cloned
class ExposedDocComment {

    public function __construct(
        private readonly string $docComment,
    ) {}

    public function escape(): string {
        return str_replace("\n", '\n', addslashes($this->docComment));
    }

    public function getInitCode(): string {
        return "zend_string_init_interned(\"" . $this->escape() . "\", " . strlen($this->docComment) . ", 1);";
    }

    /** @param array<int, DocComment> $comments */
    public static function extractExposedComment(array $comments): ?ExposedDocComment {
        $exposedDocComment = null;

        foreach ($comments as $comment) {
            $text = $comment->getText();
            $matches = [];
            $pattern = "#^(\s*\/\*\*)(\s*@genstubs-expose-comment-block)(\s*)$#m";

            if (preg_match($pattern, $text, $matches) !== 1) {
                continue;
            }

            if ($exposedDocComment !== null) {
                throw new Exception("Only one PHPDoc comment block can be exposed");
            }

            $exposedDocComment = preg_replace($pattern, '$1$3', $text);
        }

        return $exposedDocComment ? new ExposedDocComment($exposedDocComment) : null;
    }
}

// Instances of FramelessFunctionInfo are immutable and do not need to be cloned
// when held by an object that is cloned
class FramelessFunctionInfo {
    public readonly int $arity;

    public function __construct(string $json) {
        // FIXME: Should have some validation
        $json = json_decode($json, true);

        $this->arity = $json["arity"];
    }
}

function parseFunctionLike(
    PrettyPrinterAbstract $prettyPrinter,
    FunctionOrMethodName $name,
    int $classFlags,
    int $flags,
    Node\FunctionLike $func,
    ?string $cond,
    bool $isUndocumentable,
    ?int $minimumPhpVersionIdCompatibility
): FuncInfo {
    try {
        $comments = $func->getComments();
        $paramMeta = [];
        $aliasType = null;
        $alias = null;
        $isDeprecated = false;
        $supportsCompileTimeEval = false;
        $verify = true;
        $docReturnType = null;
        $tentativeReturnType = false;
        $docParamTypes = [];
        $refcount = null;
        $framelessFunctionInfos = [];

        if ($comments) {
            $tags = DocCommentTag::parseDocComments($comments);
            $tagMap = DocCommentTag::makeTagMap($tags);

            $isDeprecated = array_key_exists('deprecated', $tagMap);
            $verify = !array_key_exists('no-verify', $tagMap);
            $tentativeReturnType = array_key_exists('tentative-return-type', $tagMap);
            $supportsCompileTimeEval = array_key_exists('compile-time-eval', $tagMap);
            $isUndocumentable = $isUndocumentable || array_key_exists('undocumentable', $tagMap);

            foreach ($tags as $tag) {
                switch ($tag->name) {
                    case 'alias':
                    case 'implementation-alias':
                        $aliasType = $tag->name;
                        $aliasParts = explode("::", $tag->getValue());
                        if (count($aliasParts) === 1) {
                            $alias = new FunctionName(new Name($aliasParts[0]));
                        } else {
                            $alias = new MethodName(new Name($aliasParts[0]), $aliasParts[1]);
                        }
                        break;

                    case 'return':
                        $docReturnType = $tag->getType();
                        break;

                    case 'param':
                        $docParamTypes[$tag->getVariableName()] = $tag->getType();
                        break;

                    case 'refcount':
                        $refcount = $tag->getValue();
                        break;

                    case 'prefer-ref':
                        $varName = $tag->getVariableName();
                        if (!isset($paramMeta[$varName])) {
                            $paramMeta[$varName] = [];
                        }
                        $paramMeta[$varName][$tag->name] = true;
                        break;

                    case 'frameless-function':
                        $framelessFunctionInfos[] = new FramelessFunctionInfo($tag->getValue());
                        break;
                }
            }
        }

        $varNameSet = [];
        $args = [];
        $numRequiredArgs = 0;
        $foundVariadic = false;
        foreach ($func->getParams() as $i => $param) {
            if ($param->isPromoted()) {
                throw new Exception("Promoted properties are not supported");
            }

            $varName = $param->var->name;
            $preferRef = !empty($paramMeta[$varName]['prefer-ref']);
            unset($paramMeta[$varName]);

            if (isset($varNameSet[$varName])) {
                throw new Exception("Duplicate parameter name $varName");
            }
            $varNameSet[$varName] = true;

            if ($preferRef) {
                $sendBy = ArgInfo::SEND_PREFER_REF;
            } else if ($param->byRef) {
                $sendBy = ArgInfo::SEND_BY_REF;
            } else {
                $sendBy = ArgInfo::SEND_BY_VAL;
            }

            if ($foundVariadic) {
                throw new Exception("Only the last parameter can be variadic");
            }

            $type = $param->type ? Type::fromNode($param->type) : null;
            if ($type === null && !isset($docParamTypes[$varName])) {
                throw new Exception("Missing parameter type");
            }

            if ($param->default instanceof Expr\ConstFetch &&
                $param->default->name->toLowerString() === "null" &&
                $type && !$type->isNullable()
            ) {
                $simpleType = $type->tryToSimpleType();
                if ($simpleType === null || !$simpleType->isMixed()) {
                    throw new Exception("Parameter $varName has null default, but is not nullable");
                }
            }

            if ($param->default instanceof Expr\ClassConstFetch && $param->default->class->toLowerString() === "self") {
                throw new Exception('The exact class name must be used instead of "self"');
            }

            $foundVariadic = $param->variadic;

            $args[] = new ArgInfo(
                $varName,
                $sendBy,
                $param->variadic,
                $type,
                isset($docParamTypes[$varName]) ? Type::fromString($docParamTypes[$varName]) : null,
                $param->default ? $prettyPrinter->prettyPrintExpr($param->default) : null,
                AttributeInfo::createFromGroups($param->attrGroups)
            );
            if (!$param->default && !$param->variadic) {
                $numRequiredArgs = $i + 1;
            }
        }

        foreach (array_keys($paramMeta) as $var) {
            throw new Exception("Found metadata for invalid param $var");
        }

        $returnType = $func->getReturnType();
        if ($returnType === null && $docReturnType === null && !$name->isConstructor() && !$name->isDestructor()) {
            throw new Exception("Missing return type");
        }

        $return = new ReturnInfo(
            $func->returnsByRef(),
            $returnType ? Type::fromNode($returnType) : null,
            $docReturnType ? Type::fromString($docReturnType) : null,
            $tentativeReturnType,
            $refcount
        );

        return new FuncInfo(
            $name,
            $classFlags,
            $flags,
            $aliasType,
            $alias,
            $isDeprecated,
            $supportsCompileTimeEval,
            $verify,
            $args,
            $return,
            $numRequiredArgs,
            $cond,
            $isUndocumentable,
            $minimumPhpVersionIdCompatibility,
            AttributeInfo::createFromGroups($func->attrGroups),
            $framelessFunctionInfos,
            ExposedDocComment::extractExposedComment($comments)
        );
    } catch (Exception $e) {
        throw new Exception($name . "(): " .$e->getMessage());
    }
}

/**
 * @param array<int, array<int, AttributeGroup> $attributes
 */
function parseConstLike(
    PrettyPrinterAbstract $prettyPrinter,
    AbstractConstName $name,
    Node\Const_ $const,
    int $flags,
    ?Node $type,
    array $comments,
    ?string $cond,
    bool $isUndocumentable,
    ?int $phpVersionIdMinimumCompatibility,
    array $attributes
): ConstInfo {
    $phpDocType = null;

    $tags = DocCommentTag::parseDocComments($comments);
    $tagMap = DocCommentTag::makeTagMap($tags);

    $deprecated = array_key_exists('deprecated', $tagMap);
    $isUndocumentable = $isUndocumentable || array_key_exists('undocumentable', $tagMap);
    $isFileCacheAllowed = !array_key_exists('no-file-cache', $tagMap);
    $cValue = $tagMap['cvalue'] ?? null;
    $link = $tagMap['link'] ?? null;

    foreach ($tags as $tag) {
        if ($tag->name === 'var') {
            $phpDocType = $tag->getType();
        }
    }

    if ($type === null && $phpDocType === null) {
        if ($const->value instanceof Node\Scalar\Float_) {
            $phpDocType = 'float';
        } elseif ($const->value instanceof Node\Scalar\Int_
            || ($const->value instanceof Expr\UnaryMinus
                && $const->value->expr instanceof Node\Scalar\Int_
            )
        ) {
            $phpDocType = 'int';
        } elseif ($const->value instanceof Node\Scalar\String_) {
            $phpDocType = 'string';
        } elseif ($const->value instanceof Expr\ConstFetch
            && $const->value->name instanceof Node\Name\FullyQualified
            && (
                $const->value->name->name === 'false'
                || $const->value->name->name === 'true'
            )
        ) {
            $phpDocType = 'bool';
        } elseif ($const->value instanceof Expr\ConstFetch
            && $const->value->name instanceof Node\Name\FullyQualified
            && $const->value->name->name === 'null'
        ) {
            $phpDocType = 'null';
        } else {
            throw new Exception("Missing type for constant " . $name->__toString());
        }
    }

    $constType = $type ? Type::fromNode($type) : null;
    $constPhpDocType = $phpDocType ? Type::fromString($phpDocType) : null;

    if ($const->value instanceof Expr\ConstFetch &&
        $const->value->name->toLowerString() === "null" &&
        $constType && !$constType->isNullable()
    ) {
        $simpleType = $constType->tryToSimpleType();
        if ($simpleType === null || !$simpleType->isMixed()) {
            throw new Exception("Constant " . $name->__toString() . " has null value, but is not nullable");
        }
    }

    return new ConstInfo(
        $name,
        $flags,
        $const->value,
        $prettyPrinter->prettyPrintExpr($const->value),
        $constType,
        $constPhpDocType,
        $deprecated,
        $cond,
        $cValue,
        $isUndocumentable,
        $link,
        $phpVersionIdMinimumCompatibility,
        $attributes,
        ExposedDocComment::extractExposedComment($comments),
        $isFileCacheAllowed
    );
}

/**
 * @param array<int, array<int, AttributeGroup> $attributes
 */
function parseProperty(
    Name $class,
    int $classFlags,
    int $flags,
    Stmt\PropertyProperty $property,
    ?Node $type,
    array $comments,
    PrettyPrinterAbstract $prettyPrinter,
    ?int $phpVersionIdMinimumCompatibility,
    array $attributes
): PropertyInfo {
    $phpDocType = null;

    $tags = DocCommentTag::parseDocComments($comments);
    $tagMap = DocCommentTag::makeTagMap($tags);

    $isDocReadonly = array_key_exists('readonly', $tagMap);
    $link = $tagMap['link'] ?? null;
    $isVirtual = array_key_exists('virtual', $tagMap);

    foreach ($tags as $tag) {
        if ($tag->name === 'var') {
            $phpDocType = $tag->getType();
        }
    }

    $propertyType = $type ? Type::fromNode($type) : null;
    if ($propertyType === null && !$phpDocType) {
        throw new Exception("Missing type for property $class::\$$property->name");
    }

    if ($property->default instanceof Expr\ConstFetch &&
        $property->default->name->toLowerString() === "null" &&
        $propertyType && !$propertyType->isNullable()
    ) {
        $simpleType = $propertyType->tryToSimpleType();
        if ($simpleType === null || !$simpleType->isMixed()) {
            throw new Exception("Property $class::\$$property->name has null default, but is not nullable");
        }
    }

    return new PropertyInfo(
        new PropertyName($class, $property->name->__toString()),
        $classFlags,
        $flags,
        $propertyType,
        $phpDocType ? Type::fromString($phpDocType) : null,
        $property->default,
        $property->default ? $prettyPrinter->prettyPrintExpr($property->default) : null,
        $isDocReadonly,
        $isVirtual,
        $link,
        $phpVersionIdMinimumCompatibility,
        $attributes,
        ExposedDocComment::extractExposedComment($comments)
    );
}

/**
 * @param ConstInfo[] $consts
 * @param PropertyInfo[] $properties
 * @param FuncInfo[] $methods
 * @param EnumCaseInfo[] $enumCases
 */
function parseClass(
    Name $name,
    Stmt\ClassLike $class,
    array $consts,
    array $properties,
    array $methods,
    array $enumCases,
    ?string $cond,
    ?int $minimumPhpVersionIdCompatibility,
    bool $isUndocumentable
): ClassInfo {
    $comments = $class->getComments();
    $alias = null;

    $tags = DocCommentTag::parseDocComments($comments);
    $tagMap = DocCommentTag::makeTagMap($tags);

    $isDeprecated = array_key_exists('deprecated', $tagMap);
    $isStrictProperties = array_key_exists('strict-properties', $tagMap);
    $isNotSerializable = array_key_exists('not-serializable', $tagMap);
    $isUndocumentable = $isUndocumentable || array_key_exists('undocumentable', $tagMap);
    foreach ($tags as $tag) {
        if ($tag->name === 'alias') {
            $alias = $tag->getValue();
        }
    }

    $attributes = AttributeInfo::createFromGroups($class->attrGroups);
    $allowsDynamicProperties = array_any(
        $attributes,
        static fn (AttributeInfo $attribute): bool => $attribute->class === 'AllowDynamicProperties'
    );

    if ($isStrictProperties && $allowsDynamicProperties) {
        throw new Exception("A class may not have '@strict-properties' and '#[\\AllowDynamicProperties]' at the same time.");
    }

    $extends = [];
    $implements = [];

    if ($class instanceof Class_) {
        $classKind = "class";
        if ($class->extends) {
            $extends[] = $class->extends;
        }
        $implements = $class->implements;
    } elseif ($class instanceof Interface_) {
        $classKind = "interface";
        $extends = $class->extends;
    } else if ($class instanceof Trait_) {
        $classKind = "trait";
    } else if ($class instanceof Enum_) {
        $classKind = "enum";
        $implements = $class->implements;
    } else {
        throw new Exception("Unknown class kind " . get_class($class));
    }

    if ($isUndocumentable) {
        foreach ($methods as $method) {
            $method->isUndocumentable = true;
        }
    }

    return new ClassInfo(
        $name,
        $class instanceof Class_ ? $class->flags : 0,
        $classKind,
        $alias,
        $class instanceof Enum_ && $class->scalarType !== null
            ? SimpleType::fromNode($class->scalarType) : null,
        $isDeprecated,
        $isStrictProperties,
        $attributes,
        ExposedDocComment::extractExposedComment($comments),
        $isNotSerializable,
        $extends,
        $implements,
        $consts,
        $properties,
        $methods,
        $enumCases,
        $cond,
        $minimumPhpVersionIdCompatibility,
        $isUndocumentable
    );
}

/**
 * @template T
 * @param iterable<T> $infos
 * @param Closure(T): string|null $codeGenerator
 * @param ?string $parentCond
 */
function generateCodeWithConditions(
    iterable $infos, string $separator, Closure $codeGenerator, ?string $parentCond = null): string {
    $code = "";

    // For combining the conditional blocks of the infos with the same condition
    $openCondition = null;
    foreach ($infos as $info) {
        $infoCode = $codeGenerator($info);
        if ($infoCode === null) {
            continue;
        }

        if ($info->cond && $info->cond !== $parentCond) {
            if ($openCondition !== null
                && $info->cond !== $openCondition
            ) {
                // Changing condition, end old
                $code .= "#endif\n";
                $code .= $separator;
                $code .= "#if {$info->cond}\n";
                $openCondition = $info->cond;
            } elseif ($openCondition === null) {
                // New condition with no existing one
                $code .= $separator;
                $code .= "#if {$info->cond}\n";
                $openCondition = $info->cond;
            } else {
                // Staying in the same condition
                $code .= $separator;
            }
            $code .= $infoCode;
        } else {
            if ($openCondition !== null) {
                // Ending the condition
                $code .= "#endif\n";
                $openCondition = null;
            }
            $code .= $separator;
            $code .= $infoCode;
        }
    }
    // The last info might have been in a conditional block
    if ($openCondition !== null) {
        $code .= "#endif\n";
    }

    return $code;
}

/** @param FuncInfo[] $funcInfos */
function generateFunctionEntries(?Name $className, array $funcInfos, ?string $cond = null): string {
    // No need to add anything if there are no function entries
    if ($funcInfos === []) {
        return '';
    }

    $functionEntryName = "ext_functions";
    if ($className) {
        $underscoreName = implode("_", $className->getParts());
        $functionEntryName = "class_{$underscoreName}_methods";
    }

    $code = "\nstatic const zend_function_entry {$functionEntryName}[] = {\n";
    $code .= generateCodeWithConditions($funcInfos, "", static function (FuncInfo $funcInfo) {
        return $funcInfo->getFunctionEntry();
    }, $cond);
    $code .= "\tZEND_FE_END\n";
    $code .= "};\n";

    if ($cond) {
        $code = "\n#if {$cond}{$code}#endif\n";
    }

    return $code;
}

/**
 * @param iterable<FuncInfo> $funcInfos
 * @param array<string, string> &$declaredStrings Map of string content to
 *   the name of a zend_string already created with that content
 */
function generateFunctionAttributeInitialization(iterable $funcInfos, array $allConstInfos, ?int $phpVersionIdMinimumCompatibility, ?string $parentCond = null, array &$declaredStrings = []): string {
    return generateCodeWithConditions(
        $funcInfos,
        "",
        static function (FuncInfo $funcInfo) use ($allConstInfos, $phpVersionIdMinimumCompatibility, &$declaredStrings) {
            $code = null;

            if ($funcInfo->name instanceof MethodName) {
                $functionTable = "&class_entry->function_table";
            } else {
                $functionTable = "CG(function_table)";
            }

            // Make sure we don't try and use strings that might only be
            // conditionally available; string reuse is only among declarations
            // that are always there
            if ($funcInfo->cond) {
                $useDeclared = [];
            } else {
                $useDeclared = &$declaredStrings;
            }

            foreach ($funcInfo->attributes as $key => $attribute) {
                $code .= $attribute->generateCode(
                    "zend_add_function_attribute(zend_hash_str_find_ptr($functionTable, \"" . $funcInfo->name->getNameForAttributes() . "\", sizeof(\"" . $funcInfo->name->getNameForAttributes() . "\") - 1)",
                    "func_" . $funcInfo->name->getNameForAttributes() . "_$key",
                    $allConstInfos,
                    $phpVersionIdMinimumCompatibility,
                    $useDeclared
                );
            }

            foreach ($funcInfo->args as $index => $arg) {
                foreach ($arg->attributes as $key => $attribute) {
                    $code .= $attribute->generateCode(
                        "zend_add_parameter_attribute(zend_hash_str_find_ptr($functionTable, \"" . $funcInfo->name->getNameForAttributes() . "\", sizeof(\"" . $funcInfo->name->getNameForAttributes() . "\") - 1), $index",
                        "func_{$funcInfo->name->getNameForAttributes()}_arg{$index}_$key",
                        $allConstInfos,
                        $phpVersionIdMinimumCompatibility,
                        $useDeclared
                    );
                }
            }

            return $code;
        },
        $parentCond
    );
}

/**
 * @param iterable<ConstInfo> $constInfos
 * @param array<string, ConstInfo> $allConstInfos
 * @param array<string, string> &$declaredStrings Map of string content to
 *   the name of a zend_string already created with that content
 */
function generateGlobalConstantAttributeInitialization(
    iterable $constInfos,
    array $allConstInfos,
    ?int $phpVersionIdMinimumCompatibility,
    ?string $parentCond = null,
    array &$declaredStrings = []
): string {
    $isConditional = false;
    if ($phpVersionIdMinimumCompatibility !== null && $phpVersionIdMinimumCompatibility < PHP_85_VERSION_ID) {
        $isConditional = true;
    }
    $code = generateCodeWithConditions(
        $constInfos,
        "",
        static function (ConstInfo $constInfo) use ($allConstInfos, $isConditional, &$declaredStrings) {
            $code = "";

            if ($constInfo->attributes === []) {
                return null;
            }
            // Make sure we don't try and use strings that might only be
            // conditionally available; string reuse is only among declarations
            // that are always there
            if ($constInfo->cond) {
                $useDeclared = [];
            } else {
                $useDeclared = &$declaredStrings;
            }
            $constName = str_replace('\\', '\\\\', $constInfo->name->__toString());
            $constVarName = 'const_' . $constName;

            // The entire attribute block will be conditional if PHP < 8.5 is
            // supported, but also if PHP < 8.5 is supported we need to search
            // for the constant; see GH-19029
            if ($isConditional) {
                $code .= "\tzend_constant *$constVarName = zend_hash_str_find_ptr(EG(zend_constants), \"" . $constName . "\", sizeof(\"" . $constName . "\") - 1);\n";
            }
            foreach ($constInfo->attributes as $key => $attribute) {
                $code .= $attribute->generateCode(
                    "zend_add_global_constant_attribute($constVarName",
                    $constVarName . "_$key",
                    $allConstInfos,
                    PHP_85_VERSION_ID,
                    $useDeclared
                );
            }

            return $code;
        },
        $parentCond
    );
    if ($code && $isConditional) {
        return "\n#if (PHP_VERSION_ID >= " . PHP_85_VERSION_ID . ")\n" . $code . "#endif\n";
    }
    return $code;
}

/**
 * @param iterable<ConstInfo> $constInfos
 * @param array<string, ConstInfo> $allConstInfos
 * @param array<string, string> &$declaredStrings Map of string content to
 *    the name of a zend_string already created with that content
 */
function generateConstantAttributeInitialization(
    iterable $constInfos,
    array $allConstInfos,
    ?int $phpVersionIdMinimumCompatibility,
    ?string $parentCond = null,
    array &$declaredStrings = []
): string {
    return generateCodeWithConditions(
        $constInfos,
        "",
        static function (ConstInfo $constInfo) use ($allConstInfos, $phpVersionIdMinimumCompatibility, &$declaredStrings) {
            $code = null;

            // Make sure we don't try and use strings that might only be
            // conditionally available; string reuse is only among declarations
            // that are always there
            if ($constInfo->cond) {
                $useDeclared = [];
            } else {
                $useDeclared = &$declaredStrings;
            }
            foreach ($constInfo->attributes as $key => $attribute) {
                $code .= $attribute->generateCode(
                    "zend_add_class_constant_attribute(class_entry, const_" . $constInfo->name->getDeclarationName(),
                    "const_" . $constInfo->name->getDeclarationName() . "_$key",
                    $allConstInfos,
                    $phpVersionIdMinimumCompatibility,
                    $useDeclared
                );
            }

            return $code;
        },
        $parentCond
    );
}

/**
 * @param iterable<PropertyInfo> $propertyInfos
 * @param array<string, ConstInfo> $allConstInfos
 * @param array<string, string> &$declaredStrings Map of string content to
 *    the name of a zend_string already created with that content
 */
function generatePropertyAttributeInitialization(
    iterable $propertyInfos,
    array $allConstInfos,
    ?int $phpVersionIdMinimumCompatibility,
    array &$declaredStrings
): string {
    $code = "";
    foreach ($propertyInfos as $propertyInfo) {
        foreach ($propertyInfo->attributes as $key => $attribute) {
            $code .= $attribute->generateCode(
                "zend_add_property_attribute(class_entry, property_" . $propertyInfo->name->getDeclarationName(),
                "property_" . $propertyInfo->name->getDeclarationName() . "_" . $key,
                $allConstInfos,
                $phpVersionIdMinimumCompatibility,
                $declaredStrings
            );
        }
    }

    return $code;
}

/** @param array<string, FuncInfo> $funcMap */
function generateOptimizerInfo(array $funcMap): string {
    $code = "/* This is a generated file, edit the .stub.php files instead. */\n\n";

    $code .= "static const func_info_t func_infos[] = {\n";

    $code .= generateCodeWithConditions($funcMap, "", static function (FuncInfo $funcInfo) {
        return $funcInfo->getOptimizerInfo();
    });

    $code .= "};\n";

    return $code;
}

/**
 * @param array<string, ConstInfo> $constMap
 * @param array<string, ConstInfo> $undocumentedConstMap
 * @return array<string, string|null>
 */
function replacePredefinedConstants(string $targetDirectory, array $constMap, array &$undocumentedConstMap): array {
    /** @var array<string, string> $documentedConstMap */
    $documentedConstMap = [];
    /** @var array<string, string> $predefinedConstants */
    $predefinedConstants = [];

    $it = new RecursiveIteratorIterator(
        new RecursiveDirectoryIterator($targetDirectory),
        RecursiveIteratorIterator::LEAVES_ONLY
    );

    foreach ($it as $file) {
        $pathName = $file->getPathName();
        if (!preg_match('/(?:[\w\.]*constants[\w\._]*|tokens).xml$/i', basename($pathName))) {
            continue;
        }

        $xml = file_get_contents($pathName);
        if ($xml === false) {
            continue;
        }

        if (stripos($xml, "<appendix") === false && stripos($xml, "<sect2") === false &&
            stripos($xml, "<chapter") === false && stripos($xml, 'role="constant_list"') === false
        ) {
            continue;
        }

        $replacedXml = getReplacedSynopsisXml($xml);

        $doc = new DOMDocument();
        $doc->formatOutput = false;
        $doc->preserveWhiteSpace = true;
        $doc->validateOnParse = true;
        $success = $doc->loadXML($replacedXml);
        if (!$success) {
            echo "Failed opening $pathName\n";
            continue;
        }

        $updated = false;

        foreach ($doc->getElementsByTagName("varlistentry") as $entry) {
            if (!$entry instanceof DOMElement) {
                continue;
            }

            foreach ($entry->getElementsByTagName("term") as $manualTermElement) {
                $manualConstantElement = $manualTermElement->getElementsByTagName("constant")->item(0);
                if (!$manualConstantElement instanceof DOMElement) {
                    continue;
                }

                $manualConstantName = $manualConstantElement->textContent;

                $stubConstant = $constMap[$manualConstantName] ?? null;
                if ($stubConstant === null) {
                    continue;
                }

                $documentedConstMap[$manualConstantName] = $manualConstantName;

                if ($entry->firstChild instanceof DOMText) {
                    $indentationLevel = strlen(str_replace("\n", "", $entry->firstChild->textContent));
                } else {
                    $indentationLevel = 3;
                }
                $newTermElement = $stubConstant->getPredefinedConstantTerm($doc, $indentationLevel);

                if ($manualTermElement->textContent === $newTermElement->textContent) {
                    continue;
                }

                $manualTermElement->parentNode->replaceChild($newTermElement, $manualTermElement);
                $updated = true;
            }
        }

        foreach ($doc->getElementsByTagName("row") as $row) {
            if (!$row instanceof DOMElement) {
                continue;
            }

            $entry = $row->getElementsByTagName("entry")->item(0);
            if (!$entry instanceof DOMElement) {
                continue;
            }

            foreach ($entry->getElementsByTagName("constant") as $manualConstantElement) {
                if (!$manualConstantElement instanceof DOMElement) {
                    continue;
                }

                $manualConstantName = $manualConstantElement->textContent;

                $stubConstant = $constMap[$manualConstantName] ?? null;
                if ($stubConstant === null) {
                    continue;
                }

                $documentedConstMap[$manualConstantName] = $manualConstantName;

                if ($row->firstChild instanceof DOMText) {
                    $indentationLevel = strlen(str_replace("\n", "", $row->firstChild->textContent));
                } else {
                    $indentationLevel = 3;
                }
                $newEntryElement = $stubConstant->getPredefinedConstantEntry($doc, $indentationLevel);

                if ($entry->textContent === $newEntryElement->textContent) {
                    continue;
                }

                $entry->parentNode->replaceChild($newEntryElement, $entry);
                $updated = true;
            }
        }

        if ($updated) {
            $replacedXml = $doc->saveXML();

            $replacedXml = preg_replace(
                [
                    "/REPLACED-ENTITY-([A-Za-z0-9._{}%-]+?;)/",
                    '/<appendix\s+xmlns="([^"]+)"\s+xml:id="([^"]+)"\s*>/i',
                    '/<appendix\s+xmlns="([^"]+)"\s+xmlns:xlink="([^"]+)"\s+xml:id="([^"]+)"\s*>/i',
                    '/<sect2\s+xmlns="([^"]+)"\s+xml:id="([^"]+)"\s*>/i',
                    '/<sect2\s+xmlns="([^"]+)"\s+xmlns:xlink="([^"]+)"\s+xml:id="([^"]+)"\s*>/i',
                    '/<chapter\s+xmlns="([^"]+)"\s+xml:id="([^"]+)"\s*>/i',
                    '/<chapter\s+xmlns="([^"]+)"\s+xmlns:xlink="([^"]+)"\s+xml:id="([^"]+)"\s*>/i',
                ],
                [
                    "&$1",
                    "<appendix xml:id=\"$2\" xmlns=\"$1\">",
                    "<appendix xml:id=\"$3\" xmlns=\"$1\" xmlns:xlink=\"$2\">",
                    "<sect2 xml:id=\"$2\" xmlns=\"$1\">",
                    "<sect2 xml:id=\"$3\" xmlns=\"$1\" xmlns:xlink=\"$2\">",
                    "<chapter xml:id=\"$2\" xmlns=\"$1\">",
                    "<chapter xml:id=\"$3\" xmlns=\"$1\" xmlns:xlink=\"$2\">",
                ],
                $replacedXml
            );

            $predefinedConstants[$pathName] = $replacedXml;
        }
    }

    $undocumentedConstMap = array_diff_key($constMap, $documentedConstMap);

    return $predefinedConstants;
}

/**
 * @param array<string, ClassInfo> $classMap
 * @param array<string, ConstInfo> $allConstInfos
 * @return array<string, string>
 */
function generateClassSynopses(array $classMap, array $allConstInfos): array {
    $result = [];

    foreach ($classMap as $classInfo) {
        $classSynopsis = $classInfo->getClassSynopsisDocument($classMap, $allConstInfos);
        if ($classSynopsis !== null) {
            $result[ClassInfo::getClassSynopsisFilename($classInfo->name) . ".xml"] = $classSynopsis;
        }
    }

    return $result;
}

/**
 * @param array<string, ClassInfo> $classMap
 * @param array<string, ConstInfo> $allConstInfos
 * @param array<string, ClassInfo> $undocumentedClassMap
 * @return array<string, string>
 */
function replaceClassSynopses(
    string $targetDirectory,
    array $classMap,
    array $allConstInfos,
    array &$undocumentedClassMap
): array {
    /** @var array<string, string> $documentedClassMap */
    $documentedClassMap = [];
    /** @var array<string, string> $classSynopses */
    $classSynopses = [];

    $it = new RecursiveIteratorIterator(
        new RecursiveDirectoryIterator($targetDirectory),
        RecursiveIteratorIterator::LEAVES_ONLY
    );

    foreach ($it as $file) {
        $pathName = $file->getPathName();
        if (!preg_match('/\.xml$/i', $pathName)) {
            continue;
        }

        $xml = file_get_contents($pathName);
        if ($xml === false) {
            continue;
        }

        if (stripos($xml, "<classsynopsis") === false && stripos($xml, "<enumsynopsis") === false) {
            continue;
        }

        $replacedXml = getReplacedSynopsisXml($xml);

        $doc = new DOMDocument();
        $doc->formatOutput = false;
        $doc->preserveWhiteSpace = true;
        $doc->validateOnParse = true;
        $success = $doc->loadXML($replacedXml);
        if (!$success) {
            echo "Failed opening $pathName\n";
            continue;
        }

        $synopsisElements = [];
        foreach ($doc->getElementsByTagName("classsynopsis") as $element) {
            $synopsisElements[] = $element;
        }

        foreach ($doc->getElementsByTagName("enumsynopsis") as $element) {
            $synopsisElements[] = $element;
        }

        foreach ($synopsisElements as $synopsis) {
            if (!$synopsis instanceof DOMElement) {
                continue;
            }

            if ($synopsis->nodeName === "classsynopsis") {
                $child = $synopsis->firstElementChild;
                if ($child === null) {
                    continue;
                }
                $child = $child->lastElementChild;
                if ($child === null) {
                    continue;
                }
            } elseif ($synopsis->nodeName === "enumsynopsis") {
                $child = $synopsis->firstElementChild;
                if ($child === null) {
                    continue;
                }
            }

            $className = $child->textContent;

            if ($synopsis->parentElement->nodeName === "packagesynopsis" &&
                $synopsis->parentElement->firstElementChild->nodeName === "package"
            ) {
                $package = $synopsis->parentElement->firstElementChild;
                $namespace = $package->textContent;

                $className = $namespace . "\\" . $className;
                $elementToReplace = $synopsis->parentElement;
            } else {
                $elementToReplace = $synopsis;
            }

            if (!isset($classMap[$className])) {
                continue;
            }

            $documentedClassMap[$className] = $className;

            $classInfo = $classMap[$className];

            $newSynopsis = $classInfo->getClassSynopsisElement($doc, $classMap, $allConstInfos);
            if ($newSynopsis === null) {
                continue;
            }

            // Check if there is any change - short circuit if there is not any.

            if (replaceAndCompareXmls($doc, $elementToReplace, $newSynopsis)) {
                continue;
            }

            if ($synopsis->nodeName === "enumsynopsis") {
                $oldEnumCaseDescriptionElements = collectEnumSynopsisItemDescriptions($className, $elementToReplace);
                $newEnumCaseDescriptionElements = collectEnumSynopsisItemDescriptions($className, $newSynopsis);

                foreach ($newEnumCaseDescriptionElements as $key => $newEnumCaseDescriptionElement) {
                    if (isset($oldEnumCaseDescriptionElements[$key]) === false) {
                        continue;
                    }

                    $oldEnumCaseDescriptionElement = $oldEnumCaseDescriptionElements[$key];

                    $newEnumCaseDescriptionElement->parentElement->replaceChild($oldEnumCaseDescriptionElement, $newEnumCaseDescriptionElement);
                }
            }

            // Return the updated XML

            $replacedXml = $doc->saveXML();

            $replacedXml = preg_replace(
                [
                    "/REPLACED-ENTITY-([A-Za-z0-9._{}%-]+?;)/",
                    '/<reference\s+role="(\w+)"\s+xmlns="([^"]+)"\s+xml:id="([^"]+)"\s*>/i',
                    '/<reference\s+role="(\w+)"\s+xmlns="([^"]+)"\s+xmlns:xi="([^"]+)"\s+xml:id="([^"]+)"\s*>/i',
                    '/<reference\s+role="(\w+)"\s+xmlns="([^"]+)"\s+xmlns:xlink="([^"]+)"\s+xmlns:xi="([^"]+)"\s+xml:id="([^"]+)"\s*>/i',
                    '/<reference\s+role="(\w+)"\s+xmlns:xlink="([^"]+)"\s+xmlns:xi="([^"]+)"\s+xmlns="([^"]+)"\s+xml:id="([^"]+)"\s*>/i',
                    '/<reference\s+xmlns=\"([^"]+)\"\s+xmlns:xlink="([^"]+)"\s+xmlns:xi="([^"]+)"\s+role="(\w+)"\s+xml:id="([^"]+)"\s*>/i',
                    '/<reference\s+xmlns=\"([^"]+)\"\s+xmlns:xlink="([^"]+)"\s+xmlns:xi="([^"]+)"\s+xml:id="([^"]+)"\s+role="(\w+)"\s*>/i',
                ],
                [
                    "&$1",
                    "<reference xml:id=\"$3\" role=\"$1\" xmlns=\"$2\">",
                    "<reference xml:id=\"$4\" role=\"$1\" xmlns=\"$2\" xmlns:xi=\"$3\">",
                    "<reference xml:id=\"$5\" role=\"$1\" xmlns=\"$2\" xmlns:xlink=\"$3\" xmlns:xi=\"$4\">",
                    "<reference xml:id=\"$5\" role=\"$1\" xmlns=\"$4\" xmlns:xlink=\"$2\" xmlns:xi=\"$2\">",
                    "<reference xml:id=\"$5\" role=\"$4\" xmlns=\"$1\" xmlns:xlink=\"$2\" xmlns:xi=\"$3\">",
                    "<reference xml:id=\"$4\" role=\"$5\" xmlns=\"$1\" xmlns:xlink=\"$2\" xmlns:xi=\"$3\">",
                ],
                $replacedXml
            );

            $classSynopses[$pathName] = $replacedXml;
        }
    }

    $undocumentedClassMap = array_diff_key($classMap, $documentedClassMap);

    return $classSynopses;
}

/**
 * @return array<string, DOMElement>
 */
function collectEnumSynopsisItemDescriptions(string $className, DOMElement $synopsis): array
{
    $enumCaseDescriptionElements = [];

    $enumCaseDescriptions = $synopsis->getElementsByTagName("enumitemdescription");
    foreach ($enumCaseDescriptions as $enumItemDescription) {
        $enumCaseNames = $enumItemDescription->parentElement->getElementsByTagName("enumidentifier");
        if (empty($enumCaseNames)) {
            continue;
        }

        $enumCaseName = $enumCaseNames[0]->textContent;

        $enumCaseDescriptionElements["$className::$enumCaseName"] = $enumItemDescription;
    }

    return $enumCaseDescriptionElements;
}

function getReplacedSynopsisXml(string $xml): string
{
    return preg_replace(
        [
            "/&([A-Za-z0-9._{}%-]+?;)/",
            "/<(\/)*xi:([A-Za-z]+?)/"
        ],
        [
            "REPLACED-ENTITY-$1",
            "<$1XI$2",
        ],
        $xml
    );
}

/**
 * @param array<string, FuncInfo> $funcMap
 * @return array<string, string>
 */
function generateMethodSynopses(array $funcMap): array {
    $result = [];

    foreach ($funcMap as $funcInfo) {
        $methodSynopsis = $funcInfo->getMethodSynopsisDocument();
        if ($methodSynopsis !== null) {
            $result[$funcInfo->name->getMethodSynopsisFilename() . ".xml"] = $methodSynopsis;
        }
    }

    return $result;
}

/**
 * @param array<string, FuncInfo> $funcMap
 * @param array<int, string> $methodSynopsisWarnings
 * @param array<string, FuncInfo> $undocumentedFuncMap
 * @return array<string, string>
 */
function replaceMethodSynopses(
    string $targetDirectory,
    array $funcMap,
    bool $isVerifyManual,
    array &$methodSynopsisWarnings,
    array &$undocumentedFuncMap
): array {
    /** @var array<string, string> $documentedFuncMap */
    $documentedFuncMap = [];
    /** @var array<string, string> $methodSynopses */
    $methodSynopses = [];

    $it = new RecursiveIteratorIterator(
        new RecursiveDirectoryIterator($targetDirectory),
        RecursiveIteratorIterator::LEAVES_ONLY
    );

    foreach ($it as $file) {
        $pathName = $file->getPathName();
        if (!preg_match('/\.xml$/i', $pathName)) {
            continue;
        }

        $xml = file_get_contents($pathName);
        if ($xml === false) {
            continue;
        }

        if ($isVerifyManual) {
            $matches = [];
            preg_match("/<refname>\s*([\w:]+)\s*<\/refname>\s*<refpurpose>\s*&Alias;\s*<(?:function|methodname)>\s*([\w:]+)\s*<\/(?:function|methodname)>\s*<\/refpurpose>/i", $xml, $matches);
            $aliasName = $matches[1] ?? null;
            $alias = $funcMap[$aliasName] ?? null;
            $funcName = $matches[2] ?? null;
            $func = $funcMap[$funcName] ?? null;

            if ($alias &&
                !$alias->isUndocumentable &&
                ($func === null || $func->alias === null || $func->alias->__toString() !== $aliasName) &&
                ($alias->alias === null || $alias->alias->__toString() !== $funcName)
            ) {
                $methodSynopsisWarnings[] = "$aliasName()" . ($alias->alias ? " is an alias of " . $alias->alias->__toString() . "(), but it" : "") . " is incorrectly documented as an alias for $funcName()";
            }

            $matches = [];
            preg_match("/<(?:para|simpara)>\s*(?:&info.function.alias;|&info.method.alias;|&Alias;)\s+<(?:function|methodname)>\s*([\w:]+)\s*<\/(?:function|methodname)>/i", $xml, $matches);
            $descriptionFuncName = $matches[1] ?? null;
            $descriptionFunc = $funcMap[$descriptionFuncName] ?? null;
            if ($descriptionFunc && $funcName !== $descriptionFuncName) {
                $methodSynopsisWarnings[] = "Alias in the method synopsis description of $pathName doesn't match the alias in the <refpurpose>";
            }

            if ($aliasName) {
                $documentedFuncMap[$aliasName] = $aliasName;
            }
        }

        if (stripos($xml, "<methodsynopsis") === false && stripos($xml, "<constructorsynopsis") === false && stripos($xml, "<destructorsynopsis") === false) {
            continue;
        }

        $replacedXml = getReplacedSynopsisXml($xml);

        $doc = new DOMDocument();
        $doc->formatOutput = false;
        $doc->preserveWhiteSpace = true;
        $doc->validateOnParse = true;
        $success = $doc->loadXML($replacedXml);
        if (!$success) {
            echo "Failed opening $pathName\n";
            continue;
        }

        $methodSynopsisElements = [];
        foreach ($doc->getElementsByTagName("constructorsynopsis") as $element) {
            $methodSynopsisElements[] = $element;
        }
        foreach ($doc->getElementsByTagName("destructorsynopsis") as $element) {
            $methodSynopsisElements[] = $element;
        }
        foreach ($doc->getElementsByTagName("methodsynopsis") as $element) {
            $methodSynopsisElements[] = $element;
        }

        foreach ($methodSynopsisElements as $methodSynopsis) {
            if (!$methodSynopsis instanceof DOMElement) {
                continue;
            }

            $item = $methodSynopsis->getElementsByTagName("methodname")->item(0);
            if (!$item instanceof DOMElement) {
                continue;
            }
            $funcName = $item->textContent;
            if (!isset($funcMap[$funcName])) {
                continue;
            }

            $funcInfo = $funcMap[$funcName];
            $documentedFuncMap[$funcInfo->name->__toString()] = $funcInfo->name->__toString();

            $newMethodSynopsis = $funcInfo->getMethodSynopsisElement($doc);
            if ($newMethodSynopsis === null) {
                continue;
            }

            // Retrieve current signature

            $params = [];
            $list = $methodSynopsis->getElementsByTagName("methodparam");
            foreach ($list as $i => $item) {
                if (!$item instanceof DOMElement) {
                    continue;
                }

                $paramList = $item->getElementsByTagName("parameter");
                if ($paramList->count() !== 1) {
                    continue;
                }

                $paramName = $paramList->item(0)->textContent;
                $paramTypes = [];

                $paramList = $item->getElementsByTagName("type");
                foreach ($paramList as $type) {
                    if (!$type instanceof DOMElement) {
                        continue;
                    }

                    $paramTypes[] = $type->textContent;
                }

                $params[$paramName] = ["index" => $i, "type" => $paramTypes];
            }

            // Check if there is any change - short circuit if there is not any.

            if (replaceAndCompareXmls($doc, $methodSynopsis, $newMethodSynopsis)) {
                continue;
            }

            // Update parameter references

            $paramList = $doc->getElementsByTagName("parameter");
            /** @var DOMElement $paramElement */
            foreach ($paramList as $paramElement) {
                if ($paramElement->parentNode && $paramElement->parentNode->nodeName === "methodparam") {
                    continue;
                }

                $name = $paramElement->textContent;
                if (!isset($params[$name])) {
                    continue;
                }

                $index = $params[$name]["index"];
                if (!isset($funcInfo->args[$index])) {
                    continue;
                }

                $paramElement->textContent = $funcInfo->args[$index]->name;
            }

            // Return the updated XML

            $replacedXml = $doc->saveXML();

            $replacedXml = preg_replace(
                [
                    "/REPLACED-ENTITY-([A-Za-z0-9._{}%-]+?;)/",
                    '/<refentry\s+xmlns="([^"]+)"\s+xml:id="([^"]+)"\s*>/i',
                    '/<refentry\s+xmlns="([^"]+)"\s+xmlns:xlink="([^"]+)"\s+xml:id="([^"]+)"\s*>/i',
                ],
                [
                    "&$1",
                    "<refentry xml:id=\"$2\" xmlns=\"$1\">",
                    "<refentry xml:id=\"$3\" xmlns=\"$1\" xmlns:xlink=\"$2\">",
                ],
                $replacedXml
            );

            $methodSynopses[$pathName] = $replacedXml;
        }
    }

    $undocumentedFuncMap = array_diff_key($funcMap, $documentedFuncMap);

    return $methodSynopses;
}

function replaceAndCompareXmls(DOMDocument $doc, DOMElement $originalSynopsis, DOMElement $newSynopsis): bool
{
    $docComparator = new DOMDocument();
    $docComparator->preserveWhiteSpace = false;
    $docComparator->formatOutput = true;

    $xml1 = $doc->saveXML($originalSynopsis);
    $xml1 = getReplacedSynopsisXml($xml1);
    $docComparator->loadXML($xml1);
    $xml1 = $docComparator->saveXML();

    $originalSynopsis->parentNode->replaceChild($newSynopsis, $originalSynopsis);

    $xml2 = $doc->saveXML($newSynopsis);
    $xml2 = getReplacedSynopsisXml($xml2);

    $docComparator->loadXML($xml2);
    $xml2 = $docComparator->saveXML();

    return $xml1 === $xml2;
}

function installPhpParser(string $version, string $phpParserDir) {
    $lockFile = __DIR__ . "/PHP-Parser-install-lock";
    $lockFd = fopen($lockFile, 'w+');
    if (!flock($lockFd, LOCK_EX)) {
        throw new Exception("Failed to acquire installation lock");
    }

    try {
        // Check whether a parallel process has already installed PHP-Parser.
        if (is_dir($phpParserDir)) {
            return;
        }

        $cwd = getcwd();
        chdir(__DIR__);

        $tarName = "v$version.tar.gz";
        $downloadUrl = "https://github.com/nikic/PHP-Parser/archive/$tarName";
        passthru("wget -O $tarName $downloadUrl", $exit);
        if ($exit !== 0) {
            passthru("curl -LO $downloadUrl", $exit);
        }
        if ($exit !== 0) {
            throw new Exception("Failed to download PHP-Parser tarball");
        }
        if (!mkdir($phpParserDir)) {
            throw new Exception("Failed to create directory $phpParserDir");
        }
        passthru("tar xvzf $tarName -C PHP-Parser-$version --strip-components 1", $exit);
        if ($exit !== 0) {
            rmdir($phpParserDir);
            throw new Exception("Failed to extract PHP-Parser tarball");
        }
        unlink(__DIR__ . "/$tarName");
        chdir($cwd);
    } finally {
        flock($lockFd, LOCK_UN);
        @unlink($lockFile);
    }
}

function initPhpParser() {
    static $isInitialized = false;
    if ($isInitialized) {
        return;
    }

    if (!extension_loaded("tokenizer")) {
        throw new Exception("The \"tokenizer\" extension is not available");
    }

    $isInitialized = true;
    $version = "5.6.1";
    $phpParserDir = __DIR__ . "/PHP-Parser-$version";
    if (!is_dir($phpParserDir)) {
        installPhpParser($version, $phpParserDir);
    }

    spl_autoload_register(static function(string $class) use ($phpParserDir) {
        if (str_starts_with($class, "PhpParser\\")) {
            $fileName = $phpParserDir . "/lib/" . str_replace("\\", "/", $class) . ".php";
            require $fileName;
        }
    });
}

$optind = null;
$options = getopt(
    "fh",
    [
        "force-regeneration", "parameter-stats", "help", "verify", "verify-manual", "replace-predefined-constants",
        "generate-classsynopses", "replace-classsynopses", "generate-methodsynopses", "replace-methodsynopses",
        "generate-optimizer-info",
    ],
    $optind
);

$context = new Context;
$printParameterStats = isset($options["parameter-stats"]);
$verify = isset($options["verify"]);
$verifyManual = isset($options["verify-manual"]);
$replacePredefinedConstants = isset($options["replace-predefined-constants"]);
$generateClassSynopses = isset($options["generate-classsynopses"]);
$replaceClassSynopses = isset($options["replace-classsynopses"]);
$generateMethodSynopses = isset($options["generate-methodsynopses"]);
$replaceMethodSynopses = isset($options["replace-methodsynopses"]);
$generateOptimizerInfo = isset($options["generate-optimizer-info"]);
$context->forceRegeneration = isset($options["f"]) || isset($options["force-regeneration"]);
$context->forceParse = $context->forceRegeneration || $printParameterStats || $verify || $verifyManual || $replacePredefinedConstants || $generateClassSynopses || $generateOptimizerInfo || $replaceClassSynopses || $generateMethodSynopses || $replaceMethodSynopses;

if (isset($options["h"]) || isset($options["help"])) {
    die("\nUsage: gen_stub.php [ -f | --force-regeneration ] [ --replace-predefined-constants ] [ --generate-classsynopses ] [ --replace-classsynopses ] [ --generate-methodsynopses ] [ --replace-methodsynopses ] [ --parameter-stats ] [ --verify ]  [ --verify-manual ] [ --generate-optimizer-info ] [ -h | --help ] [ name.stub.php | directory ] [ directory ]\n\n");
}

$locations = array_slice($argv, $optind);
$locationCount = count($locations);
if ($replacePredefinedConstants && $locationCount < 2) {
    die("At least one source stub path and a target manual directory has to be provided:\n./build/gen_stub.php --replace-predefined-constants ./ ../doc-en/\n");
}
if ($replaceClassSynopses && $locationCount < 2) {
    die("At least one source stub path and a target manual directory has to be provided:\n./build/gen_stub.php --replace-classsynopses ./ ../doc-en/\n");
}
if ($generateMethodSynopses && $locationCount < 2) {
    die("At least one source stub path and a target manual directory has to be provided:\n./build/gen_stub.php --generate-methodsynopses ./ ../doc-en/\n");
}
if ($replaceMethodSynopses && $locationCount < 2) {
    die("At least one source stub path and a target manual directory has to be provided:\n./build/gen_stub.php --replace-methodsynopses ./ ../doc-en/\n");
}
if ($verifyManual && $locationCount < 2) {
    die("At least one source stub path and a target manual directory has to be provided:\n./build/gen_stub.php --verify-manual ./ ../doc-en/\n");
}
$manualTarget = null;
if ($replacePredefinedConstants || $replaceClassSynopses || $generateMethodSynopses || $replaceMethodSynopses || $verifyManual) {
    $manualTarget = array_pop($locations);
}
if ($locations === []) {
    $locations = ['.'];
}

$fileInfos = [];
foreach (array_unique($locations) as $location) {
    if (is_file($location)) {
        // Generate single file.
        $fileInfo = processStubFile($location, $context);
        if ($fileInfo) {
            $fileInfos[] = $fileInfo;
        }
    } else if (is_dir($location)) {
        array_push($fileInfos, ...processDirectory($location, $context));
    } else {
        echo "$location is neither a file nor a directory.\n";
        exit(1);
    }
}

if ($printParameterStats) {
    $parameterStats = [];

    foreach ($fileInfos as $fileInfo) {
        foreach ($fileInfo->getAllFuncInfos() as $funcInfo) {
            foreach ($funcInfo->args as $argInfo) {
                if (!isset($parameterStats[$argInfo->name])) {
                    $parameterStats[$argInfo->name] = 0;
                }
                $parameterStats[$argInfo->name]++;
            }
        }
    }

    arsort($parameterStats);
    echo json_encode($parameterStats, JSON_PRETTY_PRINT), "\n";
}

/** @var array<string, ClassInfo> $classMap */
$classMap = [];
/** @var array<string, FuncInfo> $funcMap */
$funcMap = [];
/** @var array<string, FuncInfo> $aliasMap */
$aliasMap = [];

/** @var array<string, ConstInfo> $undocumentedConstMap */
$undocumentedConstMap = [];
/** @var array<string, ClassInfo> $undocumentedClassMap */
$undocumentedClassMap = [];
/** @var array<string, FuncInfo> $undocumentedFuncMap */
$undocumentedFuncMap = [];
/** @var array<int, string> $methodSynopsisWarnings */
$methodSynopsisWarnings = [];

foreach ($fileInfos as $fileInfo) {
    foreach ($fileInfo->getAllFuncInfos() as $funcInfo) {
        $funcMap[$funcInfo->name->__toString()] = $funcInfo;

        // TODO: Don't use aliasMap for methodsynopsis?
        if ($funcInfo->aliasType === "alias") {
            $aliasMap[$funcInfo->alias->__toString()] = $funcInfo;
        }
    }

    foreach ($fileInfo->classInfos as $classInfo) {
        $classMap[$classInfo->name->__toString()] = $classInfo;

        if ($classInfo->alias !== null) {
            $classMap[$classInfo->alias] = $classInfo;
        }
    }
}

if ($verify) {
    $errors = [];

    foreach ($funcMap as $aliasFunc) {
        if (!$aliasFunc->alias || $aliasFunc->aliasType !== "alias") {
            continue;
        }

        if (!isset($funcMap[$aliasFunc->alias->__toString()])) {
            $errors[] = "Aliased function {$aliasFunc->alias}() cannot be found";
            continue;
        }

        if (!$aliasFunc->verify) {
            continue;
        }

        $aliasedFunc = $funcMap[$aliasFunc->alias->__toString()];
        $aliasedArgs = $aliasedFunc->args;
        $aliasArgs = $aliasFunc->args;

        if ($aliasFunc->isInstanceMethod() !== $aliasedFunc->isInstanceMethod()) {
            if ($aliasFunc->isInstanceMethod()) {
                $aliasedArgs = array_slice($aliasedArgs, 1);
            }

            if ($aliasedFunc->isInstanceMethod()) {
                $aliasArgs = array_slice($aliasArgs, 1);
            }
        }

        array_map(
            function(?ArgInfo $aliasArg, ?ArgInfo $aliasedArg) use ($aliasFunc, $aliasedFunc, &$errors) {
                if ($aliasArg === null) {
                    assert($aliasedArg !== null);
                    $errors[] = "{$aliasFunc->name}(): Argument \$$aliasedArg->name of aliased function {$aliasedFunc->name}() is missing";
                    return null;
                }

                if ($aliasedArg === null) {
                    $errors[] = "{$aliasedFunc->name}(): Argument \$$aliasArg->name of alias function {$aliasFunc->name}() is missing";
                    return null;
                }

                if ($aliasArg->name !== $aliasedArg->name) {
                    $errors[] = "{$aliasFunc->name}(): Argument \$$aliasArg->name and argument \$$aliasedArg->name of aliased function {$aliasedFunc->name}() must have the same name";
                    return null;
                }

                if ($aliasArg->type != $aliasedArg->type) {
                    $errors[] = "{$aliasFunc->name}(): Argument \$$aliasArg->name and argument \$$aliasedArg->name of aliased function {$aliasedFunc->name}() must have the same type";
                }

                if ($aliasArg->defaultValue !== $aliasedArg->defaultValue) {
                    $errors[] = "{$aliasFunc->name}(): Argument \$$aliasArg->name and argument \$$aliasedArg->name of aliased function {$aliasedFunc->name}() must have the same default value";
                }
            },
            $aliasArgs, $aliasedArgs
        );

        $aliasedReturn = $aliasedFunc->return;
        $aliasReturn = $aliasFunc->return;

        if (!$aliasedFunc->name->isConstructor() && !$aliasFunc->name->isConstructor()) {
            $aliasedReturnType = $aliasedReturn->type ?? $aliasedReturn->phpDocType;
            $aliasReturnType = $aliasReturn->type ?? $aliasReturn->phpDocType;
            if ($aliasReturnType != $aliasedReturnType) {
                $errors[] = "{$aliasFunc->name}() and {$aliasedFunc->name}() must have the same return type";
            }
        }

        $aliasedPhpDocReturnType = $aliasedReturn->phpDocType;
        $aliasPhpDocReturnType = $aliasReturn->phpDocType;
        if ($aliasedPhpDocReturnType != $aliasPhpDocReturnType && $aliasedPhpDocReturnType != $aliasReturn->type && $aliasPhpDocReturnType != $aliasedReturn->type) {
            $errors[] = "{$aliasFunc->name}() and {$aliasedFunc->name}() must have the same PHPDoc return type";
        }
    }

    echo implode("\n", $errors);
    if (!empty($errors)) {
        echo "\n";
        exit(1);
    }
}

if ($replacePredefinedConstants || $verifyManual) {
    $predefinedConstants = replacePredefinedConstants($manualTarget, $context->allConstInfos, $undocumentedConstMap);

    if ($replacePredefinedConstants) {
        foreach ($predefinedConstants as $filename => $content) {
            reportFilePutContents($filename, $content);
        }
    }
}

if ($generateClassSynopses) {
    $classSynopsesDirectory = getcwd() . "/classsynopses";

    $classSynopses = generateClassSynopses($classMap, $context->allConstInfos);
    if (!empty($classSynopses)) {
        if (!file_exists($classSynopsesDirectory)) {
            mkdir($classSynopsesDirectory);
        }

        foreach ($classSynopses as $filename => $content) {
            reportFilePutContents("$classSynopsesDirectory/$filename", $content);
        }
    }
}

if ($replaceClassSynopses || $verifyManual) {
    $classSynopses = replaceClassSynopses($manualTarget, $classMap, $context->allConstInfos, $undocumentedClassMap);

    if ($replaceClassSynopses) {
        foreach ($classSynopses as $filename => $content) {
            reportFilePutContents($filename, $content);
        }
    }
}

if ($generateMethodSynopses) {
    $methodSynopses = generateMethodSynopses($funcMap);
    if (!file_exists($manualTarget)) {
        mkdir($manualTarget);
    }

    foreach ($methodSynopses as $filename => $content) {
        $path = "$manualTarget/$filename";

        if (!file_exists($path)) {
            if (!file_exists(dirname($path))) {
                mkdir(dirname($path));
            }

            reportFilePutContents($path, $content);
        }
    }
}

if ($replaceMethodSynopses || $verifyManual) {
    $methodSynopses = replaceMethodSynopses($manualTarget, $funcMap, $verifyManual, $methodSynopsisWarnings, $undocumentedFuncMap);

    if ($replaceMethodSynopses) {
        foreach ($methodSynopses as $filename => $content) {
            reportFilePutContents($filename, $content);
        }
    }
}

if ($generateOptimizerInfo) {
    $filename = dirname(__FILE__, 2) . "/Zend/Optimizer/zend_func_infos.h";
    $optimizerInfo = generateOptimizerInfo($funcMap);

    reportFilePutContents($filename, $optimizerInfo);
}

if ($verifyManual) {
    foreach ($undocumentedConstMap as $constName => $info) {
        if ($info->name instanceof ClassConstName || $info->isUndocumentable) {
            continue;
        }

        echo "Warning: Missing predefined constant for $constName\n";
    }

    foreach ($methodSynopsisWarnings as $warning) {
        echo "Warning: $warning\n";
    }

    foreach ($undocumentedClassMap as $className => $info) {
        if (!$info->isUndocumentable) {
            echo "Warning: Missing class synopsis for $className\n";
        }
    }

    foreach ($undocumentedFuncMap as $functionName => $info) {
        if (!$info->isUndocumentable) {
            echo "Warning: Missing method synopsis for $functionName()\n";
        }
    }
}