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

> Learn how to configure your TypePHP project using the project.yml manifest. This guide covers essential settings like build mode, compiler flags, and source directories for efficient development.

- Repository: [Swoole Project/typephp](https://github.com/swoole/typephp)
- Tags: api-reference
- Published: 2026-08-30

---

**A TypePHP project is configured via a [`project.yml`](https://github.com/swoole/typephp/blob/main/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`](https://github.com/swoole/typephp/blob/main/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`](https://github.com/swoole/typephp/blob/main/project.yml)

The manifest file uses a simple key-value syntax. When the compiler runs, it reads [`project.yml`](https://github.com/swoole/typephp/blob/main/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`](https://github.com/swoole/typephp/blob/main/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`](https://github.com/swoole/typephp/blob/main/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`](https://github.com/swoole/typephp/blob/main/bin/tpc.php) invokes the system compiler after [`src/gen_stub.php`](https://github.com/swoole/typephp/blob/main/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`](https://github.com/swoole/typephp/blob/main/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`](https://github.com/swoole/typephp/blob/main/./src/Assert.php) and [`./src/polyfills.php`](https://github.com/swoole/typephp/blob/main/./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`](https://github.com/swoole/typephp/blob/main/src/gen_stub.php) generates corresponding C++ code.

## Platform-Specific Configuration (Windows)

For Windows targets, [`project.yml`](https://github.com/swoole/typephp/blob/main/project.yml) supports additional sections that embed resources directly into the executable:

### Resource Section

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

```yaml
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:

```yaml
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`](https://github.com/swoole/typephp/blob/main/project.yml) Examples

### Minimal Configuration

For a simple "Hello, World" application:

```yaml
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`](https://github.com/swoole/typephp/blob/main/project.yml) configuration drives the following pipeline implemented in [`src/compiler.php`](https://github.com/swoole/typephp/blob/main/src/compiler.php):

1. **Parse**: [`bin/tpc.php`](https://github.com/swoole/typephp/blob/main/bin/tpc.php) reads [`project.yml`](https://github.com/swoole/typephp/blob/main/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`](https://github.com/swoole/typephp/blob/main/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:

```bash
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`](https://github.com/swoole/typephp/blob/main/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`](https://github.com/swoole/typephp/blob/main/bin/tpc.php)) parses this file to drive the full compilation pipeline from PHP to native binary.

## Frequently Asked Questions

### Where does [`project.yml`](https://github.com/swoole/typephp/blob/main/project.yml) live in a TypePHP project?

The [`project.yml`](https://github.com/swoole/typephp/blob/main/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`](https://github.com/swoole/typephp/blob/main/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`](https://github.com/swoole/typephp/blob/main/project.yml) to specify files or directories that should be excluded. For example, the TypePHP project itself ignores [`./src/Assert.php`](https://github.com/swoole/typephp/blob/main/./src/Assert.php) and [`./src/polyfills.php`](https://github.com/swoole/typephp/blob/main/./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`](https://github.com/swoole/typephp/blob/main/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.