How to Shrink Webman Phar Files with Gzip Compression – A Step‑by‑Step Guide

Introduction

Webman is a high‑performance PHP framework built on Workerman. Its console plugin can package a project into a single Phar file for deployment, but the default package is uncompressed, resulting in a large file that consumes extra disk space and memory.

Why Enable Gzip Compression

Advantages

Significantly reduces file size, lowering disk usage and memory load.

Improves source‑code security by preventing direct inspection with a text editor.

Disadvantages

May introduce a slight startup delay (typically a few milliseconds).

Production environments must support the compression extension (Gzip is built‑in to PHP, so usually no issue).

Implementation Steps

Test the changes in a fresh project to avoid affecting existing code. The core modifications involve editing files in the vendor directory.

1. Enable Gzip Compression

Edit vendor/webman/console/src/Commands/BuildPharCommand.php around line 49. Replace the original Phar creation code: $phar = new Phar($phar_file, alias: 'webman'); with the following:

$phar = new Phar($phar_file, alias: 'webman');
$phar = $phar->convertToExecutable(Phar::TAR, Phar::GZ); // Enable TAR + GZ format

This converts the Phar to an executable TAR.GZ archive, enabling compression.

2. Fix Composer Class Loader Concurrency Issue

Compressed Phar files can cause file‑read conflicts in a multi‑process environment, leading to class‑loading failures. Apply a file‑lock mechanism by editing vendor/composer/ClassLoader.php and replacing the line include $file; with:

if (str_starts_with($file, 'phar://')) {
    $lockFile = sys_get_temp_dir() . '/phar_' . md5($file) . '.lock';
    $fp = fopen($lockFile, 'c');
    flock($fp, LOCK_EX) && include $file;
    fclose($fp);
    file_exists($lockFile) && @unlink($lockFile);
} else {
    include $file;
}

This ensures exclusive locking when reading Phar files, preventing concurrent conflicts.

3. Handle Binary Files and Process Startup Compatibility

For binary resources, the lock may be ineffective. Add a short delay after forking workers to mitigate race conditions. Edit vendor/workerman/workerman/src/Worker.php and insert after static::forkOneWorkerForLinux($worker);:

php_sapi_name() == 'micro' && usleep(50000); // Delay 50 ms

This adds a 50 ms pause for each process when running under the Micro SAPI (Phar mode).

4. Build and Deploy

Run the build command: php webman build:phar The compressed file is typically created at build/webman.phar.tar.gz. Upload this file to your server.

5. Run and Verify

Start the application on the server: php webman.phar.tar.gz start If no errors appear, the deployment succeeded. Test the service with:

curl http://127.0.0.1:8787/

Effect Comparison

In real tests, an uncompressed Phar can be 30‑40 MB, while enabling Gzip reduces it to 7‑10 MB (about 70‑80% compression). The exact ratio depends on the proportion of code versus already‑compressed assets; projects with mostly code achieve higher compression.

Precautions and Improvement Suggestions

The modifications affect files in the vendor directory; you will need to re‑apply them after dependency upgrades.

The community has submitted related PRs (e.g., for webman‑console); future releases may include built‑in support, eliminating the need for manual changes.

If the project contains many already‑compressed assets such as images, the overall compression ratio will be lower.

Test startup performance in production to ensure any added latency remains acceptable.

References

https://www.php.net/manual/zh/phar.converttoexecutable.php

https://www.php.net/manual/zh/phar.fileformat.comparison.php

Original article: https://www.workerman.net/a/1959 (Workerman community)