Releases

Getting Started

Tier 0 · Story 10Complete

This guide walks you through creating your first Tyhp project, from initialization to running the compiled PHP output. Before proceeding, make sure you have Tyhp installed (see Installing Tyhp).

Initializing a Project

If you installed tyhp/compiler with Composer, use vendor/bin/tyhp (or composer tyhp …) instead of a global tyhp.

mkdir my-tyhp-project
cd my-tyhp-project
tyhp init
composer install

tyhp init writes tyhp.json, src/index.tyhp, empty tyhpdef/ and build/ directories, and a root composer.json. It does not run composer install.

Greenfield composer.json includes:

  • require: php (from --php-version), tyhp/core as @dev
  • require-dev: tyhpdef/php as @dev, tyhp/compiler
  • config.allow-plugins.tyhp/core: true
  • scripts.tyhp: vendor/bin/tyhp (so composer tyhp build forwards extra args)
  • scripts.post-autoload-dump: vendor/bin/tyhp --install-binary, then vendor/bin/tyhp generate_tyhpdef --vendor

If composer.json already exists, init merges those keys when they are missing. It does not overwrite existing version pins or an existing scripts.tyhp entry. Dump-script commands are appended when they are not already listed. Init still aborts if tyhp.json already exists.

tyhp.json includes "tyhpdefInclude": ["./vendor-tyhpdef/**/*.tyhpdef"] (generated Composer/extension stubs) and "overlay": ["./tyhpdef/**/*.tyhpdef"] (hand overlays). .gitignore gains vendor-tyhpdef/.

Project Structure

my-tyhp-project/
  tyhp.json          # Project configuration
  composer.json      # tyhpdef/php, tyhp/core, tyhp/compiler, scripts
  src/index.tyhp     # Sample entry file
  tyhpdef/           # Hand-written overlay tyhpdefs (do not put generated stubs here)
  vendor-tyhpdef/    # Generated by generate_tyhpdef --vendor (gitignored; do not edit)
  build/             # Compiled PHP output (generated)

The tyhp.json Configuration File

{
    "include": ["src/**/*.tyhp"],
    "exclude": ["vendor/**", "node_modules/**"],
    "tyhpdefInclude": ["./vendor-tyhpdef/**/*.tyhpdef"],
    "overlay": ["./tyhpdef/**/*.tyhpdef"],
    "source": {
        "tagless": false
    },
    "output": {
        "path": "build/",
        "phpVersion": "8.4",
        "strictTypes": true,
        "comments": true
    }
}

Supported output.phpVersion values are "8.0" through "8.5". If you omit the key, the compiler defaults to "8.2" and emits warning TYHP4306 once per compilation. That target also selects which version-gated declarations (in your code and in tyhpdef/php) are visible. tyhpdef/php covers 8.2–8.5. See PHP Version Gating.

Writing Your First .tyhp File

tyhp init writes src/index.tyhp. Tyhp files use the <?tyhp opening tag instead of <?php:

<?tyhp
namespace App;

echo 'Hello, World!';

Building Your Project

tyhp build

The compiler reads tyhp.json, runs parse / bind / check / emit, and writes PHP to the output directory. tyhp init already adds tyhp/core (@dev in require) and tyhpdef/php (@dev in require-dev). Allow the tyhp/core plugin (config.allow-plugins.tyhp/core). The first composer require tyhp/core often does not install ambient tyhpdefs in that same transaction — run composer update or tyhp composer sync. Ordinary tyhp build never auto-updates Composer; tyhp build --fix is the opt-in write. See CLI: Composer and Composer Runtime Packages.

tyhp build updates Composer metadata only when build.updateComposer is true (default false); otherwise it reports which packages the emit needs.

php build/src/index.php

With the Composer compiler package you can use vendor/bin/tyhp build or composer tyhp build instead of a global tyhp.

Until Packagist lists the tyhp/* and tyhpdef/* packages, use a compiler checkout so path repositories can resolve runtime/packages/.

The Compiled Output

The compiled PHP looks like standard PHP. Variable type annotations are erased — they were checked at compile time.

<?php
declare(strict_types=1);

namespace App;

echo 'Hello, World!';

Checking Without Building

tyhp lint

Faster than a full build. Useful in development and CI.

Using PHP Libraries with Tyhpdef

Install tyhpdef/php for PHP builtin types (\strlen, DateTime, and so on). One package covers 8.2–8.5; the compiler filters version-gated stubs to match output.phpVersion. After composer install, generate_tyhpdef --vendor (also wired on post-autoload-dump) types other installed Composer libraries: published tyhpdef/* companions when they exist, otherwise generated files under vendor-tyhpdef/. Do not edit those generated files — put lasting fixes in overlay tyhpdefs (tyhp.json "overlay", or tyhp overlay create). See CLI: Tyhpdef Generation and Tyhpdef Overlays.

The Development Workflow

  1. Write Tyhp code in .tyhp files
  2. Run tyhp lint for type errors
  3. Run tyhp build to compile to PHP
  4. Run or deploy the compiled PHP

For editor diagnostics, run tyhp language_server (or use the Tyhp Language extension / plugin). For debugging .tyhp sources, set build.generateSourcemap to true, run tyhp build, then tyhp xdebug_proxy.

Next Steps

  • Read about types, locals, and non-nullable types
  • Learn about generics, structs, and type aliases
  • Explore extension methods, operator overloading, and parsable lambdas