# TypePHP Compilation Modes Explained: bin, lib, and ext

> Understand TypePHP compilation modes bin, lib, and ext. Learn how to build standalone executables, shared libraries, or PHP extensions with the -m flag for your projects.

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

---

**TypePHP supports three compilation modes—`bin` for standalone executables, `lib` for shared libraries, and `ext` for PHP extensions—controlled via the `-m` or `--mode` CLI flag.**

TypePHP is a transpiler that compiles PHP source code into native artifacts using the LLVM toolchain. The `-m` or `--mode` option determines the output format, allowing developers to deploy code as native binaries, embed it in other applications, or load it as PHP extensions. Understanding these TypePHP compilation modes is essential for selecting the appropriate build target for your deployment environment.

## The Three Compilation Modes

TypePHP defines three distinct compilation modes in [`src/Cli/CompletionMetadata.php`](https://github.com/swoole/typephp/blob/main/src/Cli/CompletionMetadata.php) (lines 44-48) and documents them in [`src/Translator.php`](https://github.com/swoole/typephp/blob/main/src/Translator.php) (lines 272-274). Each mode produces a different artifact type suitable for specific integration scenarios.

### bin (Standalone Binary)

The **`bin`** mode generates a standalone native executable that can run directly on the target platform (e.g., `./myapp`). This is the **default mode** when `-m` is omitted. The output requires no external PHP interpreter and is ideal for distributing self-contained command-line applications or system services.

### lib (Shared Library)

The **`lib`** mode compiles the source into a shared library (`.so` on Linux, `.dll` on Windows, `.dylib` on macOS). This artifact can be dynamically linked against C/C++ applications or loaded at runtime using `dlopen()`. Use this mode when embedding TypePHP code into existing native projects or exposing functionality to other programming languages via FFI.

### ext (PHP Extension)

The **`ext`** mode creates a loadable PHP extension (`.so` or `.dll`) that integrates directly with the PHP runtime. The generated extension can be enabled via [`php.ini`](https://github.com/swoole/typephp/blob/main/php.ini) using `extension=your_ext.so`, allowing compiled TypePHP functions and classes to be accessed from standard PHP scripts with minimal overhead.

## How to Specify the Compilation Mode

Pass the mode flag to the TypePHP CLI compiler using either the short or long form:

```bash
php cli.php build -m <mode> <source-file>

```

If omitted, the compiler defaults to `bin`. The mode value is validated against the allowed set defined in the completion metadata and passed to the build system, which selects appropriate compiler and linker flags for the target type.

## Usage Examples

### Building a Native Binary

Compile a standalone executable for direct invocation:

```bash

# Generates ./main (executable binary)

php cli.php build -m bin src/main.php

```

### Building a Shared Library

Create a shared library for linking with external applications:

```bash

# Generates libmain.so (Linux)

php cli.php build -m lib src/main.php

```

Link against it from C code:

```c
/* Linking against TypePHP shared library */
int main() {
    extern void entry_point();
    entry_point();   // executes compiled TypePHP code
    return 0;
}

```

### Building a PHP Extension

Generate a loadable PHP extension for use in interpreted scripts:

```bash

# Generates myext.so, loadable via php.ini

php cli.php build -m ext src/main.php

```

Load and use it in PHP:

```php
<?php
// Load the compiled extension
dl('myext.so'); // or add to php.ini: extension=myext.so

// Call into compiled TypePHP code
MyClass::staticMethod();
?>

```

## Implementation Details

The compilation mode option is implemented across two core files in the swoole/typephp repository. The [`src/Translator.php`](https://github.com/swoole/typephp/blob/main/src/Translator.php) file generates the CLI help text that describes the available modes to users, while [`src/Cli/CompletionMetadata.php`](https://github.com/swoole/typephp/blob/main/src/Cli/CompletionMetadata.php) defines the valid enumeration values used for input validation and shell autocompletion. These components ensure that only `bin`, `lib`, or `ext` are accepted as valid mode arguments.

## Summary

- **TypePHP compilation modes** determine the output format of the build process via the `-m` or `--mode` flag.
- **`bin`** (default) produces standalone native executables requiring no PHP runtime.
- **`lib`** generates shared libraries (`.so`, `.dll`, `.dylib`) for embedding in external applications.
- **`ext`** creates PHP extensions loadable by the interpreter through [`php.ini`](https://github.com/swoole/typephp/blob/main/php.ini).
- Mode validation and help text are defined in [`src/Cli/CompletionMetadata.php`](https://github.com/swoole/typephp/blob/main/src/Cli/CompletionMetadata.php) and [`src/Translator.php`](https://github.com/swoole/typephp/blob/main/src/Translator.php).

## Frequently Asked Questions

### What is the default compilation mode in TypePHP?

**The default compilation mode is `bin`** when the `-m` or `--mode` flag is omitted. This generates a standalone native executable that can be executed directly without a PHP interpreter.

### Can I use TypePHP to create a library for my C application?

**Yes, use the `lib` mode** (`-m lib`) to compile TypePHP source code into a standard shared library. The output (`.so`, `.dll`, or `.dylib`) exports entry points that can be linked against C/C++ projects or loaded dynamically via `dlopen()`.

### How do I load compiled TypePHP code into a regular PHP script?

**Build using the `ext` mode** (`-m ext`) to generate a PHP extension, then enable it in your [`php.ini`](https://github.com/swoole/typephp/blob/main/php.ini) file with `extension=your_ext.so`. Once loaded, the compiled classes and functions become available to standard PHP code with no visible difference from native PHP extensions.

### Where are the allowed compilation modes defined in the source code?

**The valid modes are enumerated in [`src/Cli/CompletionMetadata.php`](https://github.com/swoole/typephp/blob/main/src/Cli/CompletionMetadata.php)** (lines 44-48) and documented in **[`src/Translator.php`](https://github.com/swoole/typephp/blob/main/src/Translator.php)** (lines 272-274). These files handle validation and CLI help generation respectively.