How to Package Webman into a Standalone Linux Binary (x86_64)

Overview

Webman can be packaged into a single binary file, allowing it to run on Linux systems without a PHP runtime.

Note: The packaged binary currently only supports the x86_64 architecture on linux and does not run on macOS. Disable the phar option phar.readonly = 0 in php.ini .

Install Webman

composer create-project workerman/webman webman2024

Install Console Plugin

cd webman2024
composer require webman/console

Configuration

Edit webman2024/config/plugin/webman/console/app.php and set the 'exclude_pattern' to filter out unnecessary files during packaging.

This reduces the final package size.

Build the Binary

/usr/local/php-8.2.14/bin/php webman build:bin

If the build fails with a message about php.ini and phar, ensure the phar.readonly setting is disabled.

Re‑run the build after fixing the configuration.

webman2024$ /usr/local/php-8.2.14/bin/php webman build:bin 8.2
Phar packing...
Files collect complete, begin add file to Phar.
Write requests to the Phar archive, save changes to disk.
Use PHP8.2 ...
Saved webman.bin to /home/www/build/webman2024/build/webman.bin
Build Success!

The binary webman.bin is created in the build directory alongside webman.phar and related files.

.
├── build
│   ├── php8.2.micro.sfx
│   ├── php8.2.micro.sfx.zip
│   ├── webman.bin
│   └── webman.phar

Run the Binary

Upload webman.bin to a Linux server and start it:

$ ./webman.bin start
Workerman[./webman.bin] start in DEBUG mode
... (startup log) ...
Press Ctrl+C to stop. Start success.

Check status:

$ ./webman.bin status
Workerman[./webman.bin] status
... (status details) ...

Packaging Principle

Package the local Webman project into a phar file.

Download the appropriate php8.x.micro.sfx runtime.

Concatenate the php8.x.micro.sfx and the phar to produce a single executable binary.

Important Considerations

Any local PHP version ≥ 7.2 can run the build command, but the resulting binary is always a PHP 8 binary.

Match the local PHP version with the target version to avoid compatibility issues.

The build process downloads PHP 8 source but does not install it locally, leaving the existing PHP environment untouched.

The binary only runs on x86_64 Linux; macOS is not supported.

Environment files are excluded by default; place any required .env alongside webman.bin.

A runtime directory is created next to the binary for logs.

The binary does not read external php.ini; custom settings must be added to /config/plugin/webman/console/app.php under custom_ini.

Manual PHP Binary Example

1. Create tinywan.php:

<?php
echo 'Hello, this is Tinywan awesome app ' . PHP_EOL;

2. Concatenate the runtime and script: cat php8.2.micro.sfx tinywan.php > tinywan 3. Make it executable: chmod 0755 tinywan 4. Run it:

$ ./tinywan
Hello, this is Tinywan awesome app

static-php-cli

static-php-cli builds a standalone PHP binary for Linux, macOS, FreeBSD, and Windows (WSL) that includes popular extensions.

More information: https://github.com/crazywhalecc/static-php-cli/blob/main/README-zh.md