Project Configuration

Tier 0 · Story 10Complete

Every Tyhp project is driven by a configuration file called tyhp.json. This file tells the compiler which source files to include, where to write compiled PHP output, and what PHP version to target. Language strictness is always on (null safety, required types). It is the equivalent of tsconfig.json in the TypeScript world.

Creating a Project

The fastest way to create a new Tyhp project is with the init command:

tyhp init

If Tyhp came from Composer, use vendor/bin/tyhp init (or composer tyhp init).

This creates tyhp.json, src/index.tyhp, src/, build/, and tyhpdef/ directories, and a root composer.json. Init writes source.tagless (default false) and, when you set a namespace, a psr4 mapping. It does not run composer install — run that next so runtime packages and the dump hooks install.

Greenfield composer.json uses @dev for tyhp/core in require and for tyhpdef/php in require-dev, adds tyhp/compiler to require-dev, sets config.allow-plugins.tyhp/core to true, and sets scripts.tyhp plus post-autoload-dump (--install-binary, then generate_tyhpdef --vendor). If composer.json already exists, init merges missing keys instead of skipping or replacing the file. Existing version pins and scripts.tyhp are left as-is. Init still aborts when tyhp.json already exists.

tyhp.json loads generated vendor stubs with "tyhpdefInclude": ["./vendor-tyhpdef/**/*.tyhpdef"] and hand overlays with "overlay": ["./tyhpdef/**/*.tyhpdef"]. .gitignore includes vendor-tyhpdef/.

File Location

By default, the Tyhp CLI looks for tyhp.json in the current working directory. You can specify a different path using the --tyhp-project option:

tyhp build --tyhp-project=/path/to/my/tyhp.json

Basic Structure

A tyhp.json file is a standard JSON file with top-level keys for general settings and nested objects for output, build, checker, and tyhpdef configuration sections.

{
    "include": ["./src/**/*.tyhp"],
    "exclude": [],

    "output": {
        "path": "./build",
        "phpVersion": "8.4",
        "strictTypes": true
    },

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

Project Structure Conventions

While Tyhp does not enforce a specific directory layout, the following structure is conventional and works well with the default configuration:

my-project/
├── tyhp.json
├── composer.json
├── src/
│   ├── Models/
│   │   └── User.tyhp
│   ├── Services/
│   │   └── AuthService.tyhp
│   └── index.tyhp
├── tyhpdef/
│   └── (hand overlay .tyhpdef files)
├── vendor-tyhpdef/
│   └── (generated by generate_tyhpdef --vendor; do not edit)
└── build/
    └── (compiled PHP output)

• src/ — Your Tyhp source files (.tyhp). This is where you write your application code.
• tyhpdef/ — Hand-written overlay tyhpdefs loaded via tyhp.json "overlay". Lasting type fixes for generated vendor stubs belong here, not in vendor-tyhpdef/.
• vendor-tyhpdef/ — Stubs generated by tyhp generate_tyhpdef --vendor (also run from post-autoload-dump). Gitignored; overwritten on regen.
• build/ — The default output directory where compiled PHP files are written. This directory is created automatically by tyhp build.

Relationship to Composer

Tyhp projects work alongside Composer. Your project can have both a tyhp.json (for the Tyhp compiler) and a composer.json (for PHP dependency management). Path interpolation in tyhp.json ({name}, {version}) reads the project-root composer.json next to tyhp.json, not a file build.updateComposer may write under output.publishPath. When build.updateComposer is enabled, the Tyhp build process can generate or update composer.json in output.publishPath (default: the project root) with PSR-4 autoload mappings for the compiled PHP code. See String interpolation.

A Composer package that ships tyhpdefs declares them on extra.tyhp.package of that package’s composer.json (include / exclude / overlay globs relative to that file, optional source.tagless). Presence of extra.tyhp.package as a JSON object is what makes the install a tyhpdef package. Vendor discovery reads vendor/*/*/composer.json. tyhpdefInclude / promoted include entries may name composer.json files the same way. tyhp.json stays the author project file; package.tyhpdef is the conventional Track C tyhpdef filename listed in include.

Install the compiler itself with composer require --dev tyhp/compiler and run vendor/bin/tyhp or composer tyhp …. tyhp install composer installs the Composer tool; tyhp composer install runs Composer’s install. See Installing Tyhp.

Tyhp runtime features (such as generics, decimal types, and async/await) are distributed as Composer packages (tyhp/core, tyhp/decimal, tyhp/async). The build process automatically adds these as dependencies based on which features your code uses. Package MAJOR is the target PHP (804 for PHP 8.4); X.Y is that package's version, independent of the compiler. tyhp init records tyhp/core as @dev in require and tyhpdef/php as @dev in require-dev. See the Composer Runtime Packages page.

No Configuration Required

If no tyhp.json file is found, the compiler uses sensible defaults: it looks for .tyhp files in the current directory, outputs to build/, and targets PHP 8.2 (warning TYHP4306). An informational message is displayed to let you know defaults are being used.