TypePHP `project.yml` Configuration Guide: Complete Manifest Reference

A TypePHP project is configured via a project.yml manifest file at the repository root that declares the project name, build mode, C++ compiler flags, source directories, and platform-specific resources for the tpc compiler.

The swoole/typephp repository uses project.yml as the central configuration manifest that drives the entire compilation pipeline. This YAML file tells the TypePHP compiler (tpc) how to transform PHP source code into native binaries or libraries, specifying everything from the output filename to Windows-specific version metadata.

Core Configuration Sections in project.yml

The manifest file uses a simple key-value syntax. When the compiler runs, it reads project.yml, collects the specified source files, generates C++ code according to the PHP AST, and invokes the configured C++ compiler with the given flags.

Project Identity and Build Mode

Every project.yml must define the output identifier and compilation target:

• name: The identifier for the compiled binary or library. The binary will be called this name (or name.exe on Windows).
• build-mode: Determines the output type. bin creates an executable, while lib creates a shared library.
• version: The project version string, used for version-info resources on Windows.

According to the swoole/typephp source code, these fields are parsed in src/compiler.php to establish the build target before code generation begins.

C++ Compilation Options

TypePHP transpiles PHP to C++ before compiling to machine code. You control the C++ toolchain via:

• cxx-std: The C++ language standard for generated code (e.g., c++17).
• cxx-flags: A list of additional compiler flags passed to the C++ compiler (e.g., -Wall).

These settings are applied when bin/tpc.php invokes the system compiler after src/gen_stub.php generates the C++ stub files.

Source File Management

The compiler needs to know which PHP files to include and exclude:

• sources: A list of directories or individual files containing PHP source code. Paths are resolved relative to the directory containing project.yml. The swoole/typephp project itself includes ./src and parser files under vendor/nikic/php-parser/.
• ignore: Files or directories excluded from compilation. For example, ./src/Assert.php and ./src/polyfills.php are typically ignored to prevent compilation of test or compatibility code.

The PHP parser library at vendor/nikic/php-parser processes these sources into an AST before src/gen_stub.php generates corresponding C++ code.

Platform-Specific Configuration (Windows)

For Windows targets, project.yml supports additional sections that embed resources directly into the executable:

Resource Section

Configure Windows-specific resources such as icons and version metadata:

resource:
  icon: swoole-logo.ico
  version-info:
    file-version: 1.0.0.0
    product-version: 1.0.0
    company-name: "Acme Corp"
    file-description: "Hello World binary"
    internal-name: "hello"
    legal-copyright: "© 2026 Acme Corp"
    legal-trademarks: "Acme is a trademark of Acme Corp"
    original-filename: "hello.exe"
    product-name: "HelloApp"
    comments: "Demo TypePHP executable"

When built on Windows, the resulting binary embeds the specified icon and version information into the PE headers.

Application Manifest

The optional manifest field specifies a path to an XML application manifest that configures UAC elevation, DPI awareness, and other Windows behaviors:

manifest: app.manifest

This field is commented out by default in the reference implementation but enables full control over Windows application behavior when uncommented and provided with a valid path.

Complete project.yml Examples

Minimal Configuration

For a simple "Hello, World" application:

name: hello
build-mode: bin
version: 1.0.0
cxx-std: c++17
cxx-flags:
  - -Wall
sources:
  - ./src
ignore: []

Typical Project Layout

my-app/
├─ project.yml          ← manifest (as shown above)
├─ src/
│  ├─ main.php          ← entry point
│  └─ utils.php
└─ vendor/
   └─ nikic/php-parser/ … (parser library)

Compilation Workflow

The project.yml configuration drives the following pipeline implemented in src/compiler.php:

1. Parse: bin/tpc.php reads project.yml from the project root.
2. Collect: The compiler gathers PHP files from sources directories, excluding ignore patterns.
3. Generate: src/gen_stub.php creates C++ stub files based on the PHP AST produced by vendor/nikic/php-parser.
4. Compile: The system C++ compiler is invoked with cxx-std and cxx-flags, linking Windows resources if specified.

Run the compilation from the project root:

tpc compile

This command produces an executable named according to the name field (e.g., hello or hello.exe), applying all compiler options and resources defined in the manifest automatically.

Summary

• project.yml lives at the repository root and serves as the central build manifest for TypePHP projects.
• Core fields include name, build-mode (bin or lib), cxx-std (e.g., c++17), and cxx-flags for compiler options.
• Source management uses sources to include directories and ignore to exclude specific files from compilation.
• Windows resources are configured via the resource block for icons and version metadata, plus an optional manifest field for UAC/DPI settings.
• The tpc compiler (bin/tpc.php) parses this file to drive the full compilation pipeline from PHP to native binary.

Frequently Asked Questions

Where does project.yml live in a TypePHP project?

The project.yml file must reside at the root of the repository. The tpc compiler looks for it in the current working directory when you run tpc compile, and all relative paths in sources and ignore are resolved from this file's location.

What are the valid values for build-mode in TypePHP?

The build-mode field accepts two values: bin to create an executable file, or lib to create a shared library. According to the swoole/typephp source in project.yml, setting this to bin produces tpc.exe on Windows or tpc on Unix systems.

How do I exclude files from TypePHP compilation?

Use the ignore section in project.yml to specify files or directories that should be excluded. For example, the TypePHP project itself ignores ./src/Assert.php and ./src/polyfills.php to prevent compilation of assertion and polyfill code that should not be part of the final binary.

Can I configure Windows-specific binary properties in project.yml?

Yes. The resource section allows you to specify an icon file and detailed version information including company-name, legal-copyright, and file-version. Additionally, the manifest field accepts a path to an XML file for configuring UAC elevation and DPI awareness on Windows targets.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}