CLI: Tyhpdef Generation

Tier 2 · Story 20Planned

The generate_tyhpdef action produces .tyhpdef type definition files that describe the type signatures of external PHP code. Tyhpdef files allow the Tyhp compiler to type-check code that references PHP extensions, Composer packages, or other PHP libraries without access to their implementations — similar to TypeScript's .d.ts files.

Usage

tyhp generate_tyhpdef [options]

Generation Modes

The generator supports three modes of operation, selected by the flags you provide:

PHP Extension Mode

Generate tyhpdef files for a PHP extension installed on your system. This mode uses PHP's Reflection API to introspect all classes, functions, and constants provided by the extension.

tyhp generate_tyhpdef --ext-name=curl
tyhp generate_tyhpdef --ext-name=json --output=./tyhpdef/ --php-version=8.4

This mode requires a PHP installation with the target extension loaded. The generator shells out to PHP to perform the introspection. If PHP is not available, it falls back to the C# native source parsing mode.

Composer Package Mode

Generate tyhpdef files for a Composer package by introspecting its autoloaded classes:

tyhp generate_tyhpdef --package-path=./vendor/guzzlehttp/guzzle

This mode also requires PHP and uses the full generation script to introspect the package.

PHP Source File Mode

Generate tyhpdef files directly from PHP source files without requiring a PHP runtime. This mode uses the Tyhp compiler's built-in PHP parser to read source files and extracts type information from PHP type hints and PHPDoc annotations.

tyhp generate_tyhpdef --source=./vendor/guzzlehttp/guzzle/src/**/*.php
tyhp generate_tyhpdef --source=./lib/**/*.php --output=./tyhpdef/

The source mode combines PHP type hints with PHPDoc annotations for the most complete type information. PHPDoc tags like @param, @return, @var, @template, @method, and @property are parsed and included in the generated output.

Options

• --ext-name= — Name of a PHP extension to generate definitions for.
• --package-path= — Path to a Composer package directory.
• --source= — Glob pattern(s) for PHP source files to process (C# native mode).
• --output= — Output directory for generated .tyhpdef files (default: ./tyhpdef/).
• --output-file= — Explicit output file name for single-file output.
• --php= — Explicit path to the PHP binary.
• --php-version= — Target PHP version string for output metadata.
• --locale= — Locale for documentation language (default: en).
• --no-docs — Skip doc comments in the generated output.
• --include-internal — Include items marked with @internal.
• --overwrite — Overwrite existing tyhpdef files (by default, existing files are skipped).
• --no-php — Force C# native source parsing mode (skip PHP delegation).
• --validate= — Validate existing tyhpdef files by parsing them through the compiler.
• --verify — Re-generate tyhpdefs and compare against existing files to detect differences.

Auto-Generation During Build

When the build.generateTyhpdef option is set to true in tyhp.json, the build action automatically generates .tyhpdef files for the compiled Tyhp project's public API after a successful build. This allows other Tyhp (or PHP) projects to import the compiled library's type information.

{
    "build": {
        "generateTyhpdef": true
    }
}

Type Information Sources

The generator extracts type information from multiple sources, with the following priority:

1. PHP type hints — Native type declarations on parameters, return types, and properties are always used when present.
2. PHPDoc annotations — @param, @return, @var, @template, @throws, and other tags provide additional type details. When a PHPDoc type is more specific than the PHP type hint (e.g., array<string, int> vs. array), the PHPDoc type is preferred.
3. Value inference — For constants without type annotations, the type is inferred from the constant value.
4. PHPStan/Psalm extensions — @phpstan-param, @phpstan-return, @psalm-param, and @psalm-return tags are supported and take precedence over standard @param/@return.

Generated Output

Generated tyhpdef files follow the standard .tyhpdef syntax recognized by the Tyhp parser. They include constants, functions, classes, interfaces, traits, and enums with full member declarations. Here is an example of generated output:

<?tyhpdef
/** AUTO-GENERATED by tyhp generate_tyhpdef */

namespace Guzzle\Http {

    class Client {
        public function __construct(?array $config = null);
        public function request(string $method, string $uri, array $options = []): ResponseInterface;
        public function get(string $uri, array $options = []): ResponseInterface;
        public function post(string $uri, array $options = []): ResponseInterface;
    }

}

Validating Tyhpdef Files

Use the --validate flag to check that existing tyhpdef files parse correctly through the Tyhp compiler:

tyhp generate_tyhpdef --validate ./tyhpdef/

This discovers all .tyhpdef files in the specified path, parses each one, and reports per-file pass/fail status with any error details. This is useful for CI integration and for verifying tyhpdef files after manual editing.

Bundled Tyhpdef Files

Tyhp ships with pre-generated tyhpdef files for common PHP extensions, including core, json, date, pcre, mbstring, and others. These are automatically loaded by the compiler during build and lint operations.