mirror of
https://github.com/crazywhalecc/static-php-cli.git
synced 2026-07-04 23:35:40 +08:00
57 lines
3.7 KiB
Markdown
57 lines
3.7 KiB
Markdown
# Guide
|
|
|
|
::: warning
|
|
You are reading the documentation for StaticPHP v3. The v2 version will be deprecated after the stable release of v3.
|
|
The 3.0 version is currently in the alpha stage, and you can view the v2 documentation [here](https://static-php.github.io/v2-docs/).
|
|
:::
|
|
|
|
## What is StaticPHP?
|
|
|
|
StaticPHP is a build tool that compiles the PHP interpreter together with any extensions you need into a single self-contained binary. The target system doesn't need PHP or any runtime libraries installed — just copy the binary and run it. Builds target Linux, macOS, and Windows.
|
|
|
|
StaticPHP isn't limited to PHP. Built on the same infrastructure, it can also compile standalone static binaries for common tools like `curl`, `pkg-config`, and `htop` — no dependencies required on the target machine. Support for more tools (including `openssl` and other frequently-used CLI utilities) is planned.
|
|
|
|
## Why bother with a static PHP binary?
|
|
|
|
A typical PHP installation is tightly coupled to the system: you install PHP, then extensions, then spend time dealing with version mismatches across distros. A static binary sidesteps all of that — what you get is a single executable that runs on any machine of the same architecture, no setup required.
|
|
|
|
Common use cases:
|
|
|
|
- **Distributing CLI tools** — Ship tools like Composer, PHPStan, or your own CLI as a single file. Users don't need PHP installed.
|
|
- **Leaner containers** — Replace a bloated `php:8.x` base image with a minimal image (or even `FROM scratch`) carrying just a static binary.
|
|
- **Server applications** — Build a static binary with FPM or FrankenPHP baked in. Deployment becomes a file copy, with no dependency on the host environment.
|
|
|
|
## phpmicro: ship PHP and your code as one file
|
|
|
|
[phpmicro](https://micro.static-php.dev) is a third-party PHP SAPI that StaticPHP supports out of the box. It merges the PHP interpreter with your `.php` source or `.phar` archive into a single self-extracting executable (`.sfx`).
|
|
|
|
```
|
|
micro.sfx + your-app.phar = your-app # one file, zero dependencies
|
|
```
|
|
|
|
This is ideal for distributing PHP-based CLI tools: the end user just gets an ordinary executable with no idea PHP is involved.
|
|
|
|
## Improving how you ship and deploy PHP projects
|
|
|
|
**Drop the heavy Docker base image**
|
|
|
|
The official `php:8.x` image can be hundreds of megabytes, most of which is just the PHP runtime. Swap it for a static PHP binary with a minimal base image — or `FROM scratch` — and you can get container sizes down to single-digit megabytes with noticeably faster startup times.
|
|
|
|
**Ship PHP CLI tools like native binaries**
|
|
|
|
Build your CLI with [symfony/console](https://symfony.com/doc/current/components/console.html) or [Laravel Zero](https://laravel-zero.com), bundle it into a `.phar` with [Box](https://github.com/box-project/box), then merge it with phpmicro. The result is a single distributable executable — the same experience users expect from Go or Rust tools, with no PHP runtime required on their end.
|
|
|
|
**Single-file web apps with FrankenPHP**
|
|
|
|
[FrankenPHP](https://frankenphp.dev) is a modern PHP app server with built-in HTTP/2, HTTP/3, and automatic HTTPS. StaticPHP can compile FrankenPHP together with your chosen extensions into one binary. The result is a complete web server in a single file — no Nginx, no PHP-FPM, just deploy and run.
|
|
|
|
## Community
|
|
|
|
Join our [Discord server](https://discord.gg/xf6Rd4pEAk) to ask questions, share your builds, and connect with other StaticPHP users.
|
|
|
|
## Next steps
|
|
|
|
- [Installation](./installation) — Get the StaticPHP build tool
|
|
- [First Build](./first-build) — Full walkthrough: from downloading sources to a working executable
|
|
- [CLI Reference](./cli-reference) — Every command and option, in one place
|