TypePHP Compilation Modes Explained: bin, lib, and ext

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 (lines 44-48) and documents them in 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 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:

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:

# 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:

# Generates libmain.so (Linux)

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

Link against it from C code:

/* 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:

# Generates myext.so, loadable via php.ini

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

Load and use it in 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 file generates the CLI help text that describes the available modes to users, while 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.
• Mode validation and help text are defined in src/Cli/CompletionMetadata.php and 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 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 (lines 44-48) and documented in src/Translator.php (lines 272-274). These files handle validation and CLI help generation respectively.

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