Releases

Project Options List

Tier 0 · Story 10Complete

This is the complete reference for all options available in tyhp.json. Options can also be passed as CLI arguments where noted. CLI arguments take precedence over file-based configuration.

General Options

String interpolation

Selected path-like strings in tyhp.json expand {name}-style placeholders when the project is loaded. Use {{ and }} for a literal brace. An unknown placeholder, an unset {env.NAME}, or a missing Composer field is error TYHP6009.

Identity comes from composer.json next to tyhp.json (the project root), never from a composer.json that build.updateComposer may write under output.publishPath. tyhp init writes name but not version; add "version" before using {version}. Composer is loaded only when a Composer-sourced variable is used.

Composer (from that root composer.json):

  • {name} — package name (vendor/package may contain one /)
  • {name.vendor}, {name.package} — split on /; if there is no slash, both are the whole name
  • {name.slug} — {name} with / replaced by -
  • {version} / {projectVersion} — the version string
  • {version.major}, {version.minor}, {version.patch} — leading numeric components (3.4.1-beta.1 → 3, 4, 1); a missing slice is "0"
  • {version.suffix} — everything after the patch, including the leading separator (3.4.1-beta.1 → -beta.1, 3.4.1+build → +build, 5.34.12.5.3.22 → .5.3.22). Empty when there is no suffix (not an error)
  • {composer.type} — Composer's type field

Tyhp (no Composer file required):

  • {type} — tyhp.json "application" or "library"
  • {phpVersion}, {phpVersion.major}, {phpVersion.minor} — from output.phpVersion (8.2 → major 8, minor 2)
  • {phpVersion.id} — Tyhp PHP id: major plus a two-digit minor (8.2 → 802, 8.6 → 806)
  • {profile} — build.profile, or "debug" when unset
  • {tyhpVersion} — the running compiler version
  • {env.NAME} — process environment variable NAME (set it before invoking tyhp)

Copy-time (only in output.publishContent dst, after globs are expanded):

  • {fileName}, {fileStem}, {extension} (includes the leading .; empty when the file has no extension), {recursiveDir} (directory of the matched relative path, no trailing slash; empty at the match root), {relativePath}. {fileStem} is empty for a dotfile whose name is all extension (.gitignore).

A dst that still contains file variables is the destination for that one file (it does not also append the glob-relative path). A trailing / on dst means a directory: only {fileName} is appended. That lets {fileStem}.txt be unique per match.

Interpolated keys: cache-dir; output.path; output.publishPath; output.publishContent src / dst / exclude; psr4 values (not keys); psr4Includes; build.entryPointAutoloader values; xdebugProxy.sourceMapDir, xdebugProxy.tyhpSourceRoot, and xdebugProxy.phpOutputRoot.

Not interpolated: include / exclude / tyhpdefInclude / tyhpdefExclude / overlay; output.phpVersion; output.namespacePrefix; flags and enums. Substituted values cannot be empty (except {version.suffix}, {recursiveDir}, {extension}, and {fileStem}), contain \, or use .. as a path segment. {env.*} follows the same rules (a tag like v1.2.3 is fine).

Source File Options

Output Options

These options are nested under the "output" key in tyhp.json.

Build Options

These options are nested under the "build" key in tyhp.json, except where noted.

Optimization Options

Tier 3 · Story 23Planned

Not in this alpha

In this alpha the optimize pass is a no-op.

These options are nested under the "build" key in tyhp.json and control the compiler optimizer. Each option also has a corresponding CLI flag that overrides the file value.

PSR-4 Autoload Options

Checker Options

These options are nested under the "checker" key in tyhp.json. They control resource limits and tooling behavior — not language strictness.

Note

Null safety, required type annotations, and narrowing mixed before use are unconditional language rules. There are no checker.* toggles that relax them.

Tyhpdef Options

CLI-Only Options

These options are only available as command-line arguments and override corresponding config file values.

Lint-Specific Options

Action-Specific Options

Complete Example

Below is a comprehensive tyhp.json showing all available options with their default values. In practice, you only need to specify the options you want to change from their defaults.

{
    "type": "application",
    "quiet": false,
    "locale": "en-US",
    "suppressWarnings": [],

    "include": ["./src/**/*.tyhp", "./src/**/*.php"],
    "exclude": ["./src/legacy/**"],
    "source": {
        "tagless": false
    },

    "output": {
        "path": "./build",
        "publishPath": ".",
        "publishClean": false,
        "publishContent": [],
        "phpVersion": "8.2",
        "strictTypes": true,
        "namespacePrefix": null,
        "comments": true
    },

    "build": {
        "generateSourcemap": false,
        "sourcemapIncludeContent": false,
        "generateTyhpdef": false,
        "updateComposer": false,
        "structBacking": "array",
        "decimalBacking": "bcmath",
        "decimalScale": 28,
        "decimalRounding": "halfUp",
        "allowEval": false,
        "experimentalReadonlyCloneWith": false,
        "runtimeGenericChecks": false
    },

    "psr4": {
        "App\\": "src/"
    },

    "checker": {
        "templateStringMaxStates": 256,
        "maxFixIterations": 10
    },

    "tyhpdefInclude": ["./vendor-tyhpdef/**/*.tyhpdef"],
    "overlay": ["./tyhpdef/**/*.tyhpdef"],
    "tyhpdefExclude": []
}

A library that publishes per version can interpolate the root composer.json identity (add "version" if tyhp init did not write it):

{
    "type": "library",
    "include": ["./src/**/*.tyhp"],
    "output": {
        "path": "./publish/{version}/src",
        "publishPath": "./publish/{version}",
        "phpVersion": "8.4",
        "publishContent": [
            { "src": "README.md" },
            { "src": "docs/**/*.md", "dst": "{recursiveDir}/{fileName}" }
        ]
    }
}