crazywhalecc/static-php-cli
1
0
Fork 0
mirror of https://github.com/crazywhalecc/static-php-cli.git synced 2026-07-08 01:15:37 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge docs into static-php-cli repo (#492)

Browse Source 
* Move docs to here

* Move docs to here

* Modify old docs links
This commit is contained in:
Jerry Ma
2024-07-01 10:29:31 +08:00
committed by GitHub
parent eb00e0012f
commit b31539f0f4
51 changed files with 5172 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

63
docs/en/contributing/index.md Normal file
View File

@@ -0,0 +1,63 @@
# Contributing
Thank you for being here, this project welcomes your contributions!
## Contribution Guide
If you have code or documentation to contribute, here's what you need to know first.
1. What type of code are you contributing? (new extensions, bug fixes, security issues, project framework optimizations, documentation)
2. If you contribute new files or new snippets, is your code checked by `php-cs-fixer` and `phpstan`?
3. Have you fully read the [Developer Guide](../develop/) before contributing code?
If you can answer the above questions and have made changes to the code,
you can initiate a Pull Request in the project GitHub repository in time.
After the code review is completed, the code can be modified according to the suggestion, or directly merged into the main branch.
## Contribution Type
The main purpose of this project is to compile statically linked PHP binaries,
and the command line processing function is written based on `symfony/console`.
Before development, if you are not familiar with it,
Check out the [symfony/console documentation](https://symfony.com/doc/current/components/console.html) first.
### Security Update
Because this project is basically a PHP project running locally, generally speaking, there will be no remote attacks.
But if you find such a problem, please **DO NOT submit a PR or Issue in the GitHub repository,
You need to contact the project maintainer (crazywhalecc) via [mail](mailto:admin@zhamao.me).
### Fix Bugs
Fixing bugs generally does not involve modification of the project structure and framework,
so if you can locate the wrong code and fix it directly, please submit a PR directly.
### New Extensions
For adding a new extension,
you need to understand some basic structure of the project and how to add a new extension according to the existing logic.
It will be covered in detail in the next section on this page.
In general, you will need:
1. Evaluate whether the extension can be compiled inline into PHP.
2. Evaluate whether the extension's dependent libraries (if any) can be compiled statically.
3. Write library compile commands on different platforms.
4. Verify that the extension and its dependencies are compatible with existing extensions and dependencies.
5. Verify that the extension works normally in `cli`, `micro`, `fpm`, `embed` SAPIs.
6. Write documentation and add your extension.
### Project Framework Optimization
If you are already familiar with the working principle of `symfony/console`,
and at the same time want to make some modifications or optimizations to the framework of the project,
please understand the following things first:
1. Adding extensions does not belong to project framework optimization,
but if you find that you have to optimize the framework when adding new extensions,
you need to modify the framework itself before adding extensions.
2. For some large-scale logical modifications (such as those involving LibraryBase, Extension objects, etc.),
it is recommended to submit an Issue or Draft PR for discussion first.
3. In the early stage of the project, it was a pure private development project, and there were some Chinese comments in the code.
After internationalizing your project you can submit a PR to translate these comments into English.
4. Please do not submit more useless code fragments in the code,
such as a large number of unused variables, methods, classes, and code that has been rewritten many times.

70
docs/en/develop/doctor-module.md Normal file
View File

@@ -0,0 +1,70 @@
# Doctor module
The Doctor module is a relatively independent module used to check the system environment, which can be entered with the command `bin/spc doctor`, and the entry command class is in `DoctorCommand.php`.
The Doctor module is a checklist with a series of check items and automatic repair items.
These items are stored in the `src/SPC/doctor/item/` directory,
And two Attributes are used as check item tags and auto-fix item tags: `#[AsCheckItem]` and `#[AsFixItem]`.
Take the existing check item `if necessary tools are installed`,
which is used to check whether the packages necessary for compilation are installed in the macOS system.
The following is its source code:
```php
use SPC\doctor\AsCheckItem;
use SPC\doctor\AsFixItem;
use SPC\doctor\CheckResult;
#[AsCheckItem('if necessary tools are installed', limit_os: 'Darwin', level: 997)]
public function checkCliTools(): ?CheckResult
{
$missing = [];
foreach (self::REQUIRED_COMMANDS as $cmd) {
if ($this->findCommand($cmd) === null) {
$missing[] = $cmd;
}
}
if (!empty($missing)) {
return CheckResult::fail('missing system commands: ' . implode(', ', $missing), 'build-tools', [$missing]);
}
return CheckResult::ok();
}
```
The first parameter of the attribute is the name of the check item,
and the following `limit_os` parameter restricts the check item to be triggered only under the specified system,
and `level` is the priority of executing the check item, the larger the number, the higher the priority higher.
The `$this->findCommand()` method used in it is the method of `SPC\builder\traits\UnixSystemUtilTrait`,
the purpose is to find the location of the system command, and return NULL if it cannot be found.
Each check item method should return a `SPC\doctor\CheckResult`:
- When returning `CheckResult::fail()`, the first parameter is used to output the error prompt of the terminal,
and the second parameter is the name of the repair item when this check item can be automatically repaired.
- When `CheckResult::ok()` is returned, the check passed. You can also pass a parameter to return the check result, for example: `CheckResult::ok('OS supported')`.
- When returning `CheckResult::fail()`, if the third parameter is included, the array of the third parameter will be used as the parameter of `AsFixItem`.
The following is the method for automatically repairing items corresponding to this check item:
```php
#[AsFixItem('build-tools')]
public function fixBuildTools(array $missing): bool
{
foreach ($missing as $cmd) {
try {
shell(true)->exec('brew install ' . escapeshellarg($cmd));
} catch (RuntimeException) {
return false;
}
}
return true;
}
```
`#[AsFixItem()]` first parameter is the name of the fix item, and this method must return True or False.
When False is returned, the automatic repair failed and manual handling is required.
In the code here, `shell()->exec()` is the method of executing commands of the project,
which is used to replace `exec()` and `system()`, and also provides debugging, obtaining execution status,
entering directories, etc. characteristic.

35
docs/en/develop/index.md Normal file
View File

@@ -0,0 +1,35 @@
# Start Developing
Developing this project requires the installation and deployment of a PHP environment,
as well as some extensions and Composer commonly used in PHP projects.
The development environment and running environment of the project are almost exactly the same.
You can refer to the **Manual Build** section to install system PHP or use the pre-built static PHP of this project as the environment.
I will not go into details here.
Regardless of its purpose, this project itself is actually a `php-cli` program. You can edit and develop it as a normal PHP project.
At the same time, you need to understand the Shell languages of different systems.
The current purpose of this project is to compile statically compiled independent PHP,
but the main part also includes compiling static versions of many dependent libraries,
so you can reuse this set of compilation logic to build independent binary versions of other programs, such as Nginx, etc.
## Environment preparation
A PHP environment is required to develop this project. You can use the PHP that comes with the system,
or you can use the static PHP built by this project.
Regardless of which PHP you use, in your development environment you need to install these extensions:
```
curl,dom,filter,mbstring,openssl,pcntl,phar,posix,sodium,tokenizer,xml,xmlwriter
```
The static-php-cli project itself does not require so many extensions, but during the development process,
you will use tools such as Composer and PHPUnit, which require these extensions.
> For micro self-executing binaries built by static-php-cli itself, only `pcntl,posix,mbstring,tokenizer,phar` is required.
## Start development
Continuing down to see the project structure documentation, you can learn how `static-php-cli` works.

316
docs/en/develop/source-module.md Normal file
View File

@@ -0,0 +1,316 @@
# Source module
The download source module of static-php-cli is a major module.
It includes dependent libraries, external extensions, PHP source code download methods and file decompression methods.
The download configuration file mainly involves the `source.json` and `pkg.json` file, which records the download method of all downloadable sources.
The main commands involved in the download function are `bin/spc download` and `bin/spc extract`.
The `download` command is a downloader that downloads sources according to the configuration file,
and the `extract` command is an extractor that extract sources from downloaded files.
Generally speaking, downloading sources may be slow because these sources come from various official websites, GitHub,
and other different locations.
At the same time, they also occupy a large space, so you can download the sources once and reuse them.
The configuration file of the downloader is `source.json`, which contains the download methods of all sources.
You can add the source download methods you need, or modify the existing source download methods.
The download configuration structure of each source is as follows.
The following is the source download configuration corresponding to the `libevent` extension:
```json
{
"libevent": {
"type": "ghrel",
"repo": "libevent/libevent",
"match": "libevent.+\\.tar\\.gz",
"license": {
"type": "file",
"path": "LICENSE"
}
}
}
```
The most important field here is `type`. Currently, the types it supports are:
- `url`: Directly use URL to download, for example: `https://download.libsodium.org/libsodium/releases/libsodium-1.0.18.tar.gz`.
- `ghrel`: Use the GitHub Release API to download, download the artifacts uploaded from the latest version released by maintainers.
- `ghtar`: Use the GitHub Release API to download.
Different from `ghrel`, `ghtar` is downloaded from the `source code (tar.gz)` in the latest Release of the project.
- `ghtagtar`: Use GitHub Release API to download.
Compared with `ghtar`, `ghtagtar` can find the latest one from the `tags` list and download the source code in `tar.gz` format
(because some projects only use `tag` release version).
- `bitbuckettag`: Download using BitBucket API, basically the same as `ghtagtar`, except this one applies to BitBucket.
- `git`: Clone the project directly from a Git address to download sources, applicable to any public Git repository.
- `filelist`: Use a crawler to crawl the Web download site that provides file index,
and get the latest version of the file name and download it.
- `custom`: If none of the above download methods are satisfactory, you can write `custom`,
create a new class under `src/SPC/store/source/`, extends `CustomSourceBase`, and write the download script yourself.
## source.json Common parameters
Each source file in source.json has the following params:
- `license`: the open source license of the source code, see **Open Source License** section below
- `type`: must be one of the types mentioned above
- `path` (optional): release the source code to the specified directory instead of `source/{name}`
::: tip
The `path` parameter in `source.json` can specify a relative or absolute path. When specified as a relative path, the path is based on `source/`.
:::
## Download type - url
URL type sources refer to downloading files directly from the URL.
The parameters included are:
- `url`: The download address of the file, such as `https://example.com/file.tgz`
- `filename` (optional): The file name saved to the local area. If not specified, the file name of the url will be used.
Example (download the imagick extension and extract it to the extension storage path of the php source code):
```json
{
"ext-imagick": {
"type": "url",
"url": "https://pecl.php.net/get/imagick",
"path": "php-src/ext/imagick",
"filename": "imagick.tgz",
"license": {
"type": "file",
"path": "LICENSE"
}
}
}
```
## Download type - ghrel
ghrel will download files from Assets uploaded in GitHub Release.
First use the GitHub Release API to get the latest version, and then download the corresponding files according to the regular matching method.
The parameters included are:
- `repo`: GitHub repository name
- `match`: regular expression matching Assets files
- `prefer-stable`: Whether to download stable versions first (default is `false`)
Example (download the libsodium library, matching the libsodium-x.y.tar.gz file in Release):
```json
{
"libsodium": {
"type": "ghrel",
"repo": "jedisct1/libsodium",
"match": "libsodium-\\d+(\\.\\d+)*\\.tar\\.gz",
"license": {
"type": "file",
"path": "LICENSE"
}
}
}
```
## Download type - ghtar
ghtar will download the file from the GitHub Release Tag.
Unlike `ghrel`, `ghtar` will download the `source code (tar.gz)` from the latest Release of the project.
The parameters included are:
- `repo`: GitHub repository name
- `prefer-stable`: Whether to download stable versions first (default is `false`)
Example (brotli library):
```json
{
"brotli": {
"type": "ghtar",
"repo": "google/brotli",
"license": {
"type": "file",
"path": "LICENSE"
}
}
}
```
## Download type - ghtagtar
Use the GitHub Release API to download.
Compared with `ghtar`, `ghtagtar` can find the latest one from the `tags` list and download the source code in `tar.gz` format
(because some projects only use the `tag` version).
The parameters included are:
- `repo`: GitHub repository name
- `prefer-stable`: Whether to download stable versions first (default is `false`)
Example (gmp library):
```json
{
"gmp": {
"type": "ghtagtar",
"repo": "alisw/GMP",
"license": {
"type": "text",
"text": "EXAMPLE LICENSE"
}
}
}
```
## Download Type - bitbuckettag
Download using BitBucket API, basically the same as `ghtagtar`, except this one works with BitBucket.
The parameters included are:
- `repo`: BitBucket repository name
## Download type - git
Clone the project directly from a Git address to download sources, applicable to any public Git repository.
The parameters included are:
- `url`: Git link (HTTPS only)
- `rev`: branch name
```json
{
"imap": {
"type": "git",
"url": "https://github.com/static-php/imap.git",
"rev": "master",
"license": {
"type": "file",
"path": "LICENSE"
}
}
}
```
## Download type - filelist
Use a crawler to crawl a web download site that provides a file index and get the latest version of the file name and download it.
Note that this method is only applicable to static sites with page index functions such as mirror sites and GNU official websites.
The parameters included are:
- `url`: The URL of the page to crawl the latest version of the file
- `regex`: regular expression matching file names and download links
Example (download the libiconv library from the GNU official website):
```json
{
"libiconv": {
"type": "filelist",
"url": "https://ftp.gnu.org/gnu/libiconv/",
"regex": "/href=\"(?<file>libiconv-(?<version>[^\"]+)\\.tar\\.gz)\"/",
"license": {
"type": "file",
"path": "COPYING"
}
}
}
```
## Download type - custom
If the above downloading methods are not satisfactory, you can write `custom`,
create a new class under `src/SPC/store/source/`, extends `CustomSourceBase`, and write the download script yourself.
I won’t go into details here, you can look at `src/SPC/store/source/PhpSource.php` or `src/SPC/store/source/PostgreSQLSource.php` as examples.
## pkg.json General parameters
pkg.json stores non-source-code files, such as precompiled tools musl-toolchain and UPX. It includes:
- `type`: The same type as `source.json` and different kinds of parameters.
- `extract` (optional): The path to decompress after downloading, the default is `pkgroot/{pkg_name}`.
- `extract-files` (optional): Extract only the specified files to the specified location after downloading.
It should be noted that `pkg.json` does not involve compilation, modification and distribution of source code,
so there is no `license` open source license field.
And you cannot use the `extract` and `extract-files` parameters at the same time.
Example (download nasm locally and extract only program files to PHP SDK):
```json
{
"nasm-x86_64-win": {
"type": "url",
"url": "https://www.nasm.us/pub/nasm/releasebuilds/2.16.01/win64/nasm-2.16.01-win64.zip",
"extract-files": {
"nasm-2.16.01/nasm.exe": "{php_sdk_path}/bin/nasm.exe",
"nasm-2.16.01/ndisasm.exe": "{php_sdk_path}/bin/ndisasm.exe"
}
}
}
```
The key name in `extract-files` is the file in the source folder, and the key value is the storage path. The storage path can use the following variables:
- `{php_sdk_path}`: (Windows only) PHP SDK path
- `{pkg_root_path}`: `pkgroot/`
- `{working_dir}`: current working directory
- `{download_path}`: download directory
- `{source_path}`: source code decompression directory
When `extract-files` does not use variables and is a relative path, the directory of the relative path is `{working_dir}`.
## Open source license
For `source.json`, each source file should contain an open source license.
The `license` field stores the open source license information.
Each `license` contains the following parameters:
- `type`: `file` or `text`
- `path`: the license file in the source code directory (required when `type` is `file`)
- `text`: License text (required when `type` is `text`)
Example (yaml extension source code with LICENSE file):
```json
{
"yaml": {
"type": "git",
"path": "php-src/ext/yaml",
"rev": "php7",
"url": "https://github.com/php/pecl-file_formats-yaml",
"license": {
"type": "file",
"path": "LICENSE"
}
}
}
```
When an open source project has multiple licenses, multiple files can be specified:
```json
{
"libuv": {
"type": "ghtar",
"repo": "libuv/libuv",
"license": [
{
"type": "file",
"path": "LICENSE"
},
{
"type": "file",
"path": "LICENSE-extra"
}
]
}
}
```

180
docs/en/develop/structure.md Normal file
View File

@@ -0,0 +1,180 @@
# Introduction to project structure
static-php-cli mainly contains three logical components: sources, dependent libraries, and extensions.
These components contains 4 configuration files: `source.json`, `pkg.json`, `lib.json`, and `ext.json`.
A complete process for building standalone static PHP is:
1. Use the source download module `Downloader` to download specified or all source codes.
These sources include PHP source code, dependent library source code, and extension source code.
2. Use the source decompression module `SourceExtractor` to decompress the downloaded sources to the compilation directory.
3. Use the dependency tool to calculate the dependent extensions and dependent libraries of the currently added extension,
and then compile each library that needs to be compiled in the order of dependencies.
4. After building each dependent library using `Builder` under the corresponding operating system, install it to the `buildroot` directory.
5. If external extensions are included (the source code does not contain extensions within PHP),
copy the external extensions to the `source/php-src/ext/` directory.
6. Use `Builder` to build the PHP source code and build target to the `buildroot` directory.
The project is mainly divided into several folders:
- `bin/`: used to store program entry files, including `bin/spc`, `bin/spc-alpine-docker`, `bin/setup-runtime`.
- `config/`: Contains all the extensions and dependent libraries supported by the project,
as well as the download link and download methods of these sources. It is divided into files: `lib.json`, `ext.json`, `source.json`, `pkg.json` .
- `src/`: The core code of the project, including the entire framework and commands for compiling various extensions and libraries.
- `vendor/`: The directory that Composer depends on, you do not need to make any modifications to it.
The operating principle is to start a `ConsoleApplication` of `symfony/console`, and then parse the commands entered by the user in the terminal.
## Basic command line structure
`bin/spc` is an entry file, including the Unix common `#!/usr/bin/env php`,
which is used to allow the system to automatically execute with the PHP interpreter installed on the system.
After the project executes `new ConsoleApplication()`, the framework will automatically register them as commands.
The project does not directly use the Command registration method and command execution method recommended by Symfony. Here are small changes:
1. Each command uses the `#[AsCommand()]` Attribute to register the name and description.
2. Abstract `execute()` so that all commands are based on `BaseCommand` (which is based on `Symfony\Component\Console\Command\Command`),
and the execution code of each command itself is written in the `handle()` method .
3. Added variable `$no_motd` to `BaseCommand`, which is used to display the Figlet greeting when the command is executed.
4. `BaseCommand` saves `InputInterface` and `OutputInterface` as member variables. You can use `$this->input` and `$this->output` within the command class.
## Basic source code structure
The source code of the project is located in the `src/SPC` directory,
supports automatic loading of the PSR-4 standard, and contains the following subdirectories and classes:
- `src/SPC/builder/`: The core compilation command code used to build libraries,
PHP and related extensions under different operating systems, and also includes some compilation system tool methods.
- `src/SPC/command/`: All commands of the project are here.
- `src/SPC/doctor/`: Doctor module, which is a relatively independent module used to check the system environment.
It can be entered using the command `bin/spc doctor`.
- `src/SPC/exception/`: exception class.
- `src/SPC/store/`: Classes related to storage, files and sources are all here.
- `src/SPC/util/`: Some reusable tool methods are here.
- `src/SPC/ConsoleApplication.php`: command line program entry file.
If you have read the source code, you may find that there is also a `src/globals/` directory,
which is used to store some global variables, global methods,
and non-PSR-4 standard PHP source code that is relied upon during the build process, such as extension sanity check code etc.
## Phar application directory issue
Like other php-cli projects, spc itself has additional considerations for paths.
Because spc can run in multiple modes such as `php-cli directly`, `micro SAPI`, `php-cli with Phar`, `vendor with Phar`, etc.,
there are ambiguities in various root directories. A complete explanation is given here.
This problem is generally common in the base class path selection problem of accessing files in PHP projects, especially when used with `micro.sfx`.
Note that this may only be useful for you when developing Phar projects or PHP frameworks.
> Next, we will treat `static-php-cli` (that is, spc) as a normal `php` command line program. You can understand spc as any of your own php-cli applications for reference.
There are three basic constant theoretical values below. We recommend that you introduce these three constants when writing PHP projects:
- `WORKING_DIR`: the working directory when executing PHP scripts
- `SOURCE_ROOT_DIR` or `ROOT_DIR`: the root directory of the project folder, generally the directory where `composer.json` is located
- `FRAMEWORK_ROOT_DIR`: the root directory of the framework used, which may be used by self-developed frameworks. Generally, the framework directory is read-only
You can define these constants in your framework entry or cli applications to facilitate the use of paths in your project.
The following are PHP built-in constant values, which have been defined inside the PHP interpreter:
- `__DIR__`: the directory where the file of the currently executed script is located
- `__FILE__`: the file path of the currently executed script
### Git project mode (source)
Git project mode refers to a framework or program itself stored in plain text in the current folder, and running through `php path/to/entry.php`.
Assume that your project is stored in the `/home/example/static-php-cli/` directory, or your project is the framework itself,
which contains project files such as `composer.json`:
```
composer.json
src/App/MyCommand.app
vendor/*
bin/entry.php
```
We assume that the above constants are obtained from `src/App/MyCommand.php`:
| Constant | Value |
|----------------------|------------------------------------------------------|
| `WORKING_DIR` | `/home/example/static-php-cli` |
| `SOURCE_ROOT_DIR` | `/home/example/static-php-cli` |
| `FRAMEWORK_ROOT_DIR` | `/home/example/static-php-cli` |
| `__DIR__` | `/home/example/static-php-cli/src/App` |
| `__FILE__` | `/home/example/static-php-cli/src/App/MyCommand.php` |
In this case, the values of `WORKING_DIR`, `SOURCE_ROOT_DIR`, and `FRAMEWORK_ROOT_DIR` are exactly the same: `/home/example/static-php-cli`.
The source code of the framework and the source code of the application are both in the current path.
### Vendor library mode (vendor)
The vendor library mode generally means that your project is a framework or is installed into the project as a composer dependency by other applications,
and the storage location is in the `vendor/author/XXX` directory.
Suppose your project is `crazywhalecc/static-php-cli`, and you or others install this project in another project using `composer require`.
We assume that static-php-cli contains all files except the `vendor` directory with the same `Git mode`, and get the constant value from `src/App/MyCommand`,
Directory constant should be:
| Constant | Value |
|----------------------|--------------------------------------------------------------------------------------|
| `WORKING_DIR` | `/home/example/another-app` |
| `SOURCE_ROOT_DIR` | `/home/example/another-app` |
| `FRAMEWORK_ROOT_DIR` | `/home/example/another-app/vendor/crazywhalecc/static-php-cli` |
| `__DIR__` | `/home/example/another-app/vendor/crazywhalecc/static-php-cli/src/App` |
| `__FILE__` | `/home/example/another-app/vendor/crazywhalecc/static-php-cli/src/App/MyCommand.php` |
Here `SOURCE_ROOT_DIR` refers to the root directory of the project using `static-php-cli`.
### Git project Phar mode (source-phar)
Git project Phar mode refers to the mode of packaging the project directory of the Git project mode into a `phar` file. We assume that `/home/example/static-php-cli` will be packaged into a Phar file, and the directory has the following files:
```
composer.json
src/App/MyCommand.app
vendor/*
bin/entry.php
```
When packaged into `app.phar` and stored in the `/home/example/static-php-cli` directory, `app.phar` is executed at this time. Assuming that the `src/App/MyCommand` code is executed, the constant is obtained in the file:
| Constant | Value |
|----------------------|----------------------------------------------------------------------|
| `WORKING_DIR` | `/home/example/static-php-cli` |
| `SOURCE_ROOT_DIR` | `phar:///home/example/static-php-cli/app.phar/` |
| `FRAMEWORK_ROOT_DIR` | `phar:///home/example/static-php-cli/app.phar/` |
| `__DIR__` | `phar:///home/example/static-php-cli/app.phar/src/App` |
| `__FILE__` | `phar:///home/example/static-php-cli/app.phar/src/App/MyCommand.php` |
Because the `phar://` protocol is required to read files in the phar itself, the project root directory and the framework directory will be different from `WORKING_DIR`.
### Vendor Library Phar Mode (vendor-phar)
Vendor Library Phar Mode means that your project is installed as a framework in other projects and stored in the `vendor` directory.
We assume that your project directory structure is as follows:
```
composer.json # Composer configuration file of the current project
box.json # Configuration file for packaging Phar
another-app.php # Entry file of another project
vendor/crazywhalecc/static-php-cli/* # Your project is used as a dependent library
```
When packaging these files under the directory `/home/example/another-app/` into `app.phar`, the value of the following constant for your project should be:
| Constant | Value |
|----------------------|------------------------------------------------------------------------------------------------------|
| `WORKING_DIR` | `/home/example/another-app` |
| `SOURCE_ROOT_DIR` | `phar:///home/example/another-app/app.phar/` |
| `FRAMEWORK_ROOT_DIR` | `phar:///home/example/another-app/app.phar/vendor/crazywhalecc/static-php-cli` |
| `__DIR__` | `phar:///home/example/another-app/app.phar/vendor/crazywhalecc/static-php-cli/src/App` |
| `__FILE__` | `phar:///home/example/another-app/app.phar/vendor/crazywhalecc/static-php-cli/src/App/MyCommand.php` |

242
docs/en/develop/system-build-tools.md Normal file
View File

@@ -0,0 +1,242 @@
# Compilation Tools
static-php-cli uses many system compilation tools when building static PHP. These tools mainly include:
- `autoconf`: used to generate `configure` scripts.
- `make`: used to execute `Makefile`.
- `cmake`: used to execute `CMakeLists.txt`.
- `pkg-config`: Used to find the installation path of dependent libraries.
- `gcc`: used to compile C/C++ projects under Linux.
- `clang`: used to compile C/C++ projects under macOS.
For Linux and macOS operating systems,
these tools can usually be installed through the package manager, which is written in the doctor module.
Theoretically we can also compile and download these tools manually,
but this will increase the complexity of compilation, so we do not recommend this.
## Linux Compilation Tools
For Linux systems, different distributions have different installation methods for compilation tools.
And for static compilation, the package management of some distributions cannot install libraries and tools for pure static compilation.
Therefore, for the Linux platform and its different distributions,
we currently provide a variety of compilation environment preparations.
### Glibc Environment
The glibc environment refers to the underlying `libc` library of the system
(that is, the C standard library that all programs written in C language are dynamically linked to) uses `glibc`,
which is the default environment for most distributions.
For example: Ubuntu, Debian, CentOS, RHEL, openSUSE, Arch Linux, etc.
In the glibc environment, the package management and compiler we use point to glibc by default,
and glibc cannot be statically linked well.
One of the reasons it cannot be statically linked is that its network library `nss` cannot be compiled statically.
For the glibc environment, in static-php-cli and spc in 2.0-RC8 and later, you can choose two ways to build static PHP:
1. Use Docker to build, you can use `bin/spc-alpine-docker` to build, it will build an Alpine Linux docker image.
2. Use `bin/spc doctor --auto-fix` to install the `musl-wrapper` and `musl-cross-make` packages, and then build directly.
([Related source code](https://github.com/crazywhalecc/static-php-cli/blob/main/src/SPC/doctor/item/LinuxMuslCheck.php))
Generally speaking, the build results in these two environments are consistent, and you can choose according to actual needs.
In the doctor module, static-php-cli will first detect the current Linux distribution.
If the current distribution is a glibc environment, you will be prompted to install the musl-wrapper and musl-cross-make packages.
The process of installing `musl-wrapper` in the glibc environment is as follows:
1. Download the specific version of [musl-wrapper source code](https://musl.libc.org/releases/) from the musl official website.
2. Use `gcc` installed from the package management to compile the musl-wrapper source code and generate `musl-libc` and other libraries: `./configure --disable-gcc-wrapper && make -j && sudo make install`.
3. The musl-wrapper related libraries will be installed in the `/usr/local/musl` directory.
The process of installing `musl-cross-make` in the glibc environment is as follows:
1. Download the precompiled [musl-cross-make](https://dl.static-php.dev/static-php-cli/deps/musl-toolchain/) compressed package from dl.static-php.dev .
2. Unzip to the `/usr/local/musl` directory.
::: tip
In the glibc environment, static compilation can be achieved by directly installing musl-wrapper,
but musl-wrapper only contains `musl-gcc` and not `musl-g++`, which means that C++ code cannot be compiled.
So we need musl-cross-make to provide `musl-g++`.
The reason why the musl-cross-make package cannot be compiled directly locally is that
its compilation environment requirements are relatively high (requires more than 36GB of memory, compiled under Alpine Linux),
so we provide precompiled binary packages that can be used for all Linux distributions.
At the same time, the package management of some distributions provides musl-wrapper,
but musl-cross-make needs to match the corresponding musl-wrapper version,
so we do not use package management to install musl-wrapper.
Compiling musl-cross-make will be introduced in the **musl-cross-make Toolchain Compilation** section of this chapter.
:::
### Musl Environment
The musl environment refers to the system's underlying `libc` library that uses `musl`,
which is a lightweight C standard library that can be well statically linked.
For the currently popular Linux distributions, Alpine Linux uses the musl environment,
so static-php-cli can directly build static PHP under Alpine Linux.
You only need to install basic compilation tools (such as `gcc`, `cmake`, etc.) directly from the package management.
For other distributions, if your distribution uses the musl environment,
you can also use static-php-cli to build static PHP directly after installing the necessary compilation tools.
::: tip
In the musl environment, static-php-cli will automatically skip the installation of musl-wrapper and musl-cross-make.
:::
### Docker Environment
The Docker environment refers to using Docker containers to build static PHP. You can use `bin/spc-alpine-docker` to build.
Before executing this command, you need to install Docker first, and then execute `bin/spc-alpine-docker` in the project root directory.
After executing `bin/spc-alpine-docker`, static-php-cli will automatically download the Alpine Linux image and then build a `cwcc-spc-x86_64` or `cwcc-spc-aarch64` image.
Then all build process is performed within this image, which is equivalent to compiling in Alpine Linux.
## musl-cross-make Toolchain Compilation
In Linux, although you do not need to manually compile the musl-cross-make tool,
if you want to understand its compilation process, you can refer here.
Another important reason is that this may not be compiled using automated tools such as CI and Actions,
because the existing CI service compilation environment does not meet the compilation requirements of musl-cross-make,
and the configuration that meets the requirements is too expensive.
The compilation process of musl-cross-make is as follows:
Prepare an Alpine Linux environment (either directly installed or using Docker).
The compilation process requires more than **36GB** of memory,
so you need to compile on a machine with larger memory.
Without this much memory, compilation may fail.
Then write the following content into the `config.mak` file:
```makefile
STAT = -static --static
FLAG = -g0 -Os -Wno-error
ifneq ($(NATIVE),)
COMMON_CONFIG += CC="$(HOST)-gcc ${STAT}" CXX="$(HOST)-g++ ${STAT}"
else
COMMON_CONFIG += CC="gcc ${STAT}" CXX="g++ ${STAT}"
endif
COMMON_CONFIG += CFLAGS="${FLAG}" CXXFLAGS="${FLAG}" LDFLAGS="${STAT}"
BINUTILS_CONFIG += --enable-gold=yes --enable-gprofng=no
GCC_CONFIG += --enable-static-pie --disable-cet --enable-default-pie
#--enable-default-pie
CONFIG_SUB_REV = 888c8e3d5f7b
GCC_VER = 13.2.0
BINUTILS_VER = 2.40
MUSL_VER = 1.2.4
GMP_VER = 6.2.1
MPC_VER = 1.2.1
MPFR_VER = 4.2.0
LINUX_VER = 6.1.36
```
And also you need to add `gcc-13.2.0.tar.xz.sha1` file, contents here:
```
5f95b6d042fb37d45c6cbebfc91decfbc4fb493c gcc-13.2.0.tar.xz
```
If you are using Docker to build, create a new `Dockerfile` file and write the following content:
```dockerfile
FROM alpine:edge
RUN apk add --no-cache \
gcc g++ git make curl perl \
rsync patch wget libtool \
texinfo autoconf automake \
bison tar xz bzip2 zlib \
file binutils flex \
linux-headers libintl \
gettext gettext-dev icu-libs pkgconf \
pkgconfig icu-dev bash \
ccache libarchive-tools zip
WORKDIR /opt
RUN git clone https://git.zv.io/toolchains/musl-cross-make.git
WORKDIR /opt/musl-cross-make
COPY config.mak /opt/musl-cross-make
COPY gcc-13.2.0.tar.xz.sha1 /opt/musl-cross-make/hashes
RUN make TARGET=x86_64-linux-musl -j || :
RUN sed -i 's/poison calloc/poison/g' ./gcc-13.2.0/gcc/system.h
RUN make TARGET=x86_64-linux-musl -j
RUN make TARGET=x86_64-linux-musl install -j
RUN tar cvzf x86_64-musl-toolchain.tgz output/*
```
If you are using Alpine Linux in a non-Docker environment, you can directly execute the commands in the Dockerfile, for example:
```bash
apk add --no-cache \
gcc g++ git make curl perl \
rsync patch wget libtool \
texinfo autoconf automake \
bison tar xz bzip2 zlib \
file binutils flex \
linux-headers libintl \
gettext gettext-dev icu-libs pkgconf \
pkgconfig icu-dev bash \
ccache libarchive-tools zip
git clone https://git.zv.io/toolchains/musl-cross-make.git
# Copy config.mak to the working directory of musl-cross-make.
# You need to replace /path/to/config.mak with your config.mak file path.
cp /path/to/config.mak musl-cross-make/
cp /path/to/gcc-13.2.0.tar.xz.sha1 musl-cross-make/hashes
make TARGET=x86_64-linux-musl -j || :
sed -i 's/poison calloc/poison/g' ./gcc-13.2.0/gcc/system.h
make TARGET=x86_64-linux-musl -j
make TARGET=x86_64-linux-musl install -j
tar cvzf x86_64-musl-toolchain.tgz output/*
```
::: tip
All the above scripts are suitable for x86_64 architecture Linux.
If you need to build musl-cross-make for the ARM environment, just replace all `x86_64` above with `aarch64`.
:::
This compilation process may fail due to insufficient memory, network problems, etc.
You can try a few more times, or use a machine with larger memory to compile.
If you encounter problems or you have better improvement solutions, go to [Discussion](https://github.com/crazywhalecc/static-php-cli-hosted/issues/1).
## macOS Environment
For macOS systems, the main compilation tool we use is `clang`,
which is the default compiler for macOS systems and is also the compiler of Xcode.
Compiling under macOS mainly relies on Xcode or Xcode Command Line Tools.
You can download Xcode from the App Store,
or execute `xcode-select --install` in the terminal to install Xcode Command Line Tools.
In addition, in the `doctor` environment check module, static-php-cli will check whether Homebrew,
compilation tools, etc. are installed on the macOS system.
If not, you will be prompted to install them. I will not go into details here.
## FreeBSD Environment
FreeBSD is also a Unix system, and its compilation tools are similar to macOS.
You can directly use the package management `pkg` to install `clang` and other compilation tools through the `doctor` command.
## pkg-config Compilation (*nix only)
If you observe the compilation log when using static-php-cli to build static PHP, you will find that no matter what is compiled,
`pkg-config` will be compiled first. This is because `pkg-config` is a library used to find dependencies.
In earlier versions of static-php-cli, we directly used the `pkg-config` tool installed by package management,
but this would cause some problems, such as:
- Even if `PKG_CONFIG_PATH` is specified, `pkg-config` will try to find dependent packages from the system path.
- Since `pkg-config` will look for dependent packages from the system path,
if a dependent package with the same name exists in the system, compilation may fail.
In order to avoid the above problems, we compile `pkg-config` into `buildroot/bin` in user mode and use it.
We use parameters such as `--without-sysroot` to avoid looking for dependent packages from the system path.

74
docs/en/faq/index.md Normal file
View File

@@ -0,0 +1,74 @@
# FAQ
Here will be some questions that you may encounter easily. There are currently many, but I need to take time to organize them.
## Can statically compiled PHP install extensions?
Because the principle of installing extensions in PHP under the traditional architecture is to install new extensions using `.so` type dynamic link libraries,
and statically linked PHP compiled using this project cannot **directly** install new extensions using dynamic link libraries.
For the macOS platform, almost all binary files under macOS cannot be linked purely statically,
and almost all binary files will link macOS system libraries: `/usr/lib/libresolv.9.dylib` and `/usr/lib/libSystem.B.dylib`.
So under macOS system, statically compiled php binary files can be used under certain compilation conditions,
and dynamic link extensions can be used at the same time:
1. Using the `--no-strip` parameter will not strip information such as debugging symbols from the binary file for use with external Zend extensions such as `Xdebug`.
2. If you want to compile some Zend extensions, use Homebrew, MacPorts, source code compilation, and install a normal version of PHP on your operating system.
3. Use the `phpize && ./configure && make` command to compile the extensions you want to use.
4. Copy the extension file `xxxx.so` to the outside, use the statically compiled PHP binary, for example to use the Xdebug extension: `cd buildroot/bin/ && ./php -d "zend_extension=/path/to/xdebug.so"`.
```bash
# build statically linked php-cli but not stripped
bin/spc build ffi --build-cli --no-strip
```
For the Linux platform, the current compilation result is a purely statically linked binary file,
and new extensions cannot be installed using a dynamic link library.
## Can it support Oracle database extension?
Some extensions that rely on closed source libraries, such as `oci8`, `sourceguardian`, etc.,
they do not provide purely statically compiled dependent library files (`.a`), only dynamic dependent library files (`.so`).
These extensions cannot be compiled into static-php-cli from source, so this project may never support them.
However, in theory, you can access and use such extensions under macOS according to the above questions.
If you have a need for such extensions, or most people have needs for these closed-source extensions,
see the discussion on [standalone-php-cli](https://github.com/crazywhalecc/static-php-cli/discussions/58). Welcome to leave a message.
## Does it support Windows?
The project currently supports Windows, but the number of supported extensions is small. Windows support is not perfect. There are mainly the following problems:
1. The compilation process of Windows is different from that of *nix, and the toolchain used is also different. The compilation tools used to compile the dependent libraries of each extension are almost completely different.
2. The demand for the Windows version will also be advanced based on the needs of all people who use this project. If many people need it, I will support related extensions as soon as possible.
## Can I protect my source code with micro?
You can't. micro.sfx is essentially combining php and php code into one file,
there is no process of compiling or encrypting the PHP code.
First of all, php-src is the official interpreter of PHP code, and there is no PHP compiler compatible with mainstream branches on the market.
I saw on the Internet that there is a project called BPC (Binary PHP Compiler?) that can compile PHP into binary,
but there are many restrictions.
The direction of encrypting and protecting the code is not the same as compiling.
After compiling, the code can also be obtained through reverse engineering and other methods.
The real protection is still carried out by means of packing and encrypting the code.
Therefore, this project (static-php-cli) and related projects (lwmbs, swoole-cli) all provide a convenient compilation tool for php-src source code.
The phpmicro referenced by this project and related projects is only a package of PHP's sapi interface, not a compilation tool for PHP code.
The compiler for PHP code is a completely different project, so the extra cases are not taken into account.
If you are interested in encryption, you can consider using existing encryption technologies,
such as Swoole Compiler, Source Guardian, etc.
## Unable to use ssl
When using curl, pgsql, etc. to request an HTTPS website or establish an SSL connection, there may be an `error:80000002:system library::No such file or directory` error.
This error is caused by statically compiled PHP without specifying `openssl.cafile` via `php.ini`.
You can solve this problem by specifying `php.ini` before using PHP and adding `openssl.cafile=/path/to/your-cert.pem` in the INI.
For Linux systems, you can download the [cacert.pem](https://curl.se/docs/caextract.html) file from the curl official website, or you can use the certificate file that comes with the system.
For the certificate locations of different distros, please refer to [Golang docs](https://go.dev/src/crypto/x509/root_linux.go).
> INI configuration `openssl.cafile` cannot be set dynamically using the `ini_set()` function, because `openssl.cafile` is a `PHP_INI_SYSTEM` type configuration and can only be set in the `php.ini` file.

29
docs/en/guide/action-build.md Normal file
View File

@@ -0,0 +1,29 @@
# GitHub Action Build
Action Build refers to compiling directly using GitHub Action.
If you don't want to compile it yourself, you can download the artifact from the existing Action in this project,
or you can download it from a self-hosted server：[Enter](https://dl.static-php.dev/static-php-cli/common/).
> Self-hosted binaries are also built from Actions: [repo](https://github.com/static-php/static-php-cli-hosted).
> The extensions included are: bcmath,bz2,calendar,ctype,curl,dom,exif,fileinfo,filter,ftp,gd,gmp,iconv,xml,mbstring,mbregex,mysqlnd,openssl,
> pcntl,pdo,pdo_mysql,pdo_sqlite,phar,posix,redis,session,simplexml,soap,sockets,sqlite3,tokenizer,xmlwriter,xmlreader,zlib,zip
## Build Guide
Using GitHub Action makes it easy to build a statically compiled PHP and phpmicro,
while also defining the extensions to compile.
1. Fork project.
2. Go to the Actions of the project and select `CI`.
3. Select `Run workflow`, fill in the PHP version you want to compile, the target type, and the list of extensions. (extensions comma separated, e.g. `bcmath,curl,mbstring`)
4. After waiting for about a period of time, enter the corresponding task and get `Artifacts`.
If you enable `debug`, all logs will be output at build time, including compiled logs, for troubleshooting.
> If you need to build in other environments, you can use [manual build](./manual-build).
## Extensions
You can go to [extensions](./extensions) check here to see if all the extensions you need currently support.
and then go to [command generator](./cli-generator) select the extension you need to compile, copy the extensions string to `extensions` option.

221
docs/en/guide/build-on-windows.md Normal file
View File

@@ -0,0 +1,221 @@
# Build on Windows
Because the Windows system is an NT kernel, the compilation tools and operating system interfaces
used by Unix-like operating systems are almost completely different,
so the build process on Windows will be slightly different from that of Unix systems.
## GitHub Actions Build
Building the Windows version of static-php from Actions is now supported.
Like Linux and macOS, you need to Fork the static-php-cli repository to your GitHub account first,
then you can enter [Extension List](./extensions) to select the extension to be compiled,
and then go to your own `CI on Windows` select the PHP version, fill in the extension list (comma separated), and click Run.
If you're going to develop or build locally, please read on.
## Requirements
The tools required to build static PHP on Windows are the same as PHP's official Windows build tools.
You can read [Official Documentation](https://wiki.php.net/internals/windows/stepbystepbuild_sdk_2).
To sum up, you need the following environment and tools:
- Windows 10/11 (requires build 17063 or later)
- Visual Studio 2019/2022 (recommended 2022)
- C++ desktop development for Visual Studio
- Git for Windows
- [php-sdk-binary-tools](https://github.com/php/php-sdk-binary-tools) (can be installed automatically using doctor)
- strawberry-perl (can be installed automatically using doctor)
- nasm (can be installed automatically using doctor)
::: tip
The construction of static-php-cli on Windows refers to using MSVC to build PHP and is not based on MinGW, Cygwin, WSL and other environments.
If you prefer to use WSL, please refer to the chapter on Building on Linux.
:::
After installing Visual Studio and selecting the C++ desktop development workload,
you may download about 8GB of compilation tools, and the download speed depends on your network conditions.
### Install Git
Git for Windows can be downloaded and installed from [here](https://git-scm.com/download/win) `Standalone Installer 64-bit` version,
installed in the default location (`C:\Program Files\Git\`).
If you don't want to download and install manually,
you can also use Visual Studio Installer and check Git in the **Individual component** tab.
### Prepare static-php-cli
Downloading the static-php-cli project is very simple, just use git clone.
It is recommended to place the project in `C:\spc-build\` or a similar directory.
It is best **not to have spaces in the path**.
```shell
mkdir "C:\spc-build"
cd C:\spc-build
git clone https://github.com/crazywhalecc/static-php-cli.git
cd static-php-cli
```
It is a bit strange that static-php-cli itself requires a PHP environment,
but now you can quickly install the PHP environment through a script.
Generally, your computer will not have the Windows version of PHP installed,
so we recommend that you use `bin/setup-runtime` directly after downloading static-php-cli to install PHP and Composer in the current directory.
```shell
# Install PHP and Composer to the ./runtime/ directory
bin/setup-runtime
# After installation, if you need to use PHP and Composer in global commands,
# use the following command to add the runtime/ directory to PATH
bin/setup-runtime -action add-path
# Delete the runtime/ directory in PATH
bin/setup-runtime -action remove-path
```
### Install other Tools (automatic)
For `php-sdk-binary-tools`, `strawberry-perl`, and `nasm`,
we recommend that you directly use the command `bin/spc doctor` to check and install them.
If doctor successfully installs automatically, please **skip** the steps below to manually install the above tools.
But if the automatic installation fails, please refer to the manual installation method below.
### Install php-sdk-binary-tools (manual)
```shell
cd C:\spc-build\static-php-cli
git clone https://github.com/php/php-sdk-binary-tools.git
```
> You can also set the global variable `PHP_SDK_PATH` in Windows settings and
> clone the project to the path corresponding to the variable.
> Under normal circumstances, you don't need to change it.
### Install strawberry-perl (manual)
> If you don't need to compile the openssl extension, you don't need to install perl.
1. Download the latest version of strawberry-perl from [GitHub](https://github.com/StrawberryPerl/Perl-Dist-Strawberry/releases/).
2. Install to the `C:\spc-build\static-php-cli\pkgroot\perl\` directory.
> You can download the `-portable` version and extract it directly to the above directory.
> The last `perl.exe` should be located at `C:\spc-build\static-php-cli\pkgroot\perl\perl\bin\perl.exe`.
### Install nasm (manual)
> If you don't need to compile openssl extension, you don't need to install nasm.
1. Download the nasm tool (x64) from [official website](https://www.nasm.us/pub/nasm/releasebuilds/).
2. Place `nasm.exe` and `ndisasm.exe` in the `C:\spc-build\static-php-cli\php-sdk-binary-tools\bin\` directory.
## Download required sources
Same as [Manual build - Download](./manual-build.html#command-download)
## Build PHP
Use the build command to start building the static php binary.
Before executing the `bin/spc build` command, be sure to use the `download` command to download sources.
It is recommended to use `doctor` to check the environment.
### Build SAPI
You need to go to [Extension List](./extensions) or [Command Generator](./cli-generator) to select the extension you want to add,
and then use the command `bin/spc build` to compile.
You need to specify targets, choose from the following parameters (at least one):
- `--build-cli`: Build a cli sapi (command line interface, which can execute PHP code on the command line)
- `--build-micro`: Build a micro sapi (used to build a standalone executable binary containing PHP code)
```shell
# Compile PHP with bcmath,openssl,zlib extensions, the compilation target is cli
bin/spc build "bcmath,openssl,zlib" --build-cli
# Compile PHP with phar,curl,posix,pcntl,tokenizer extensions, compile target is micro and cli
bin/spc build "bcmath,openssl,zlib" --build-micro --build-cli
```
::: warning
In Windows, it is best to use double quotes to wrap parameters containing commas, such as `"bcmath,openssl,mbstring"`.
:::
### Debug
If you encounter problems during the compilation process, or want to view each executing shell command,
you can use `--debug` to enable debug mode and view all terminal logs:
```shell
bin/spc build "openssl" --build-cli --debug
```
### Build Options
During the compilation process, in some special cases,
the compiler and the content of the compilation directory need to be intervened.
You can try to use the following commands:
- `--with-clean`: clean up old make files before compiling PHP
- `--enable-zts`: Make compiled PHP thread-safe version (default is NTS version)
- `--with-libs=XXX,YYY`: Compile the specified dependent library before compiling PHP, and activate some extension optional functions
- `-I xxx=yyy`: Hard compile INI options into PHP before compiling (support multiple options, alias is `--with-hardcoded-ini`)
- `--with-micro-fake-cli`: When compiling micro, let micro's `PHP_SAPI` pretend to be `cli` (for compatibility with some programs that check `PHP_SAPI`)
- `--disable-opcache-jit`: Disable opcache jit (enabled by default)
- `--without-micro-ext-test`: After building micro.sfx, do not test the running results of different extensions in micro.sfx
- `--with-suggested-exts`: Add `ext-suggests` as dependencies when compiling
- `--with-suggested-libs`: Add `lib-suggests` as dependencies when compiling
- `--with-upx-pack`: Use UPX to reduce the size of the binary file after compilation (you need to use `bin/spc install-pkg upx` to install upx first)
- `--with-micro-logo=XXX.ico`: Customize the icon of the `exe` executable file after customizing the micro build (in the format of `.ico`)
Here is a simple example where we preset a larger `memory_limit` and disable the `system` function:
```shell
bin/spc build "bcmath,openssl" --build-cli -I "memory_limit=4G" -I "disable_functions=system"
```
Another example: Customize our hello-world.exe program logo:
```shell
bin/spc build "ffi,bcmath" --build-micro --with-micro-logo=mylogo.ico --debug
bin/spc micro:combine hello.php
# Then we got `my-app.exe` with custom logo!
my-app.exe
```
## Use php.exe
After php.exe is compiled, it is located in the `buildroot\bin\` directory. You can copy it to any location for use.
```shell
.\php -v
```
## Use micro.sfx
> phpmicro is a SelF-extracted eXecutable SAPI module,
> provided by [phpmicro](https://github.com/dixyes/phpmicro) project.
> But this project is using a [fork](https://github.com/static-php/phpmicro) of phpmicro, because we need to add some features to it.
> It can put php runtime and your source code together.
The final compilation result will output a file named `./micro.sfx`,
which needs to be used with your PHP source code like `code.php`.
This file will be located in the path `buildroot/bin/micro.sfx`.
Prepare your project source code, which can be a single PHP file or a Phar file, for use.
> If you want to combine phar files, you must add `phar` extension when compiling!
```shell
# code.php "<?php echo 'Hello world' . PHP_EOL;"
bin/spc micro:combine code.php -O my-app.exe
# Run it!!! Copy it to another computer!!!
./my-app.exe
```
If you package a PHAR file, just replace `code.php` with the phar file path.
You can use [box-project/box](https://github.com/box-project/box) to package your CLI project as Phar,
It is then combined with phpmicro to produce a standalone executable binary.
For more details on the `micro:combine` command, refer to [command](./manual-build) on Unix systems.

12
docs/en/guide/cli-generator.md Normal file
View File

@@ -0,0 +1,12 @@
<script setup lang="ts">
import CliGenerator from "../../.vitepress/components/CliGenerator.vue";
</script>
# CLI Build Command Generator
::: tip
The extensions selected below may contain extensions that are not supported by the selected operating system,
which may cause compilation to fail. Please check [Supported Extensions](./extensions) first.
:::
<cli-generator lang="en" />

173
docs/en/guide/env-vars.md Normal file
View File

@@ -0,0 +1,173 @@
---
aside: false
---
# Environment variables
All environment variables mentioned in the list on this page have default values unless otherwise noted.
You can override the default values by setting these environment variables.
Generally, you don't need to modify any of the following environment variables as they are already set to optimal values.
However, if you have special needs, you can set these environment variables to meet your needs
(for example, you need to debug PHP performance under different compilation parameters).
If you want to use custom environment variables, you can use the `export` command in the terminal or set the environment variables directly before the command, for example:
```shell
# export first
export SPC_CONCURRENCY=4
bin/spc build mbstring,pcntl --build-cli
# or direct use
SPC_CONCURRENCY=4 bin/spc build mbstring,pcntl --build-cli
```
## General environment variables
General environment variables can be used by all build targets.
| var name | default value | comment |
|------------------------------|---------------------------|-------------------------------------------------|
| `BUILD_ROOT_PATH` | `{pwd}/buildroot` | The root directory of the build target |
| `BUILD_LIB_PATH` | `{pwd}/buildroot/lib` | The root directory of compilation libraries |
| `BUILD_INCLUDE_PATH` | `{pwd}/buildroot/include` | Header file directory for compiling libraries |
| `BUILD_BIN_PATH` | `{pwd}/buildroot/bin` | Compiled binary file directory |
| `PKG_ROOT_PATH` | `{pwd}/pkgroot` | Directory where precompiled tools are installed |
| `SOURCE_PATH` | `{pwd}/source` | The source code extract directory |
| `DOWNLOAD_PATH` | `{pwd}/downloads` | Downloaded file directory |
| `SPC_CONCURRENCY` | Depends on CPU cores | Number of parallel compilations |
| `SPC_SKIP_PHP_VERSION_CHECK` | empty | Skip PHP version check when set to `yes` |
## OS specific variables
These environment variables are system-specific and will only take effect on a specific OS.
### Windows
| var name | default value | comment |
|----------------|------------------------------|---------------------------|
| `PHP_SDK_PATH` | `{pwd}\php-sdk-binary-tools` | PHP SDK tools path |
| `UPX_EXEC` | `$PKG_ROOT_PATH\bin\upx.exe` | UPX compression tool path |
### macOS
| var name | default value | comment |
|--------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------|
| `CC` | `clang` | C Compiler |
| `CXX` | `clang++` | C++ Compiler |
| `SPC_DEFAULT_C_FLAGS` | `--target=arm64-apple-darwin` or `--target=x86_64-apple-darwin` | Default C flags (not the same as `CFLAGS`) |
| `SPC_DEFAULT_CXX_FLAGS` | `--target=arm64-apple-darwin` or `--target=x86_64-apple-darwin` | Default C flags (not the same as `CPPFLAGS`) |
| `SPC_CMD_PREFIX_PHP_BUILDCONF` | `./buildconf --force` | PHP `buildconf` command prefix |
| `SPC_CMD_PREFIX_PHP_CONFIGURE` | `./configure --prefix= --with-valgrind=no --enable-shared=no --enable-static=yes --disable-all --disable-cgi --disable-phpdbg` | PHP `configure` command prefix |
| `SPC_CMD_PREFIX_PHP_MAKE` | `make -j$SPC_CONCURRENCY` | PHP `make` command prefix |
| `SPC_CMD_VAR_PHP_CONFIGURE_CFLAGS` | `$SPC_DEFAULT_C_FLAGS -Werror=unknown-warning-option` | `CFLAGS` variable of PHP `configure` command |
| `SPC_CMD_VAR_PHP_CONFIGURE_CPPFLAGS` | `-I$BUILD_INCLUDE_PATH` | `CPPFLAGS` variable of PHP `configure` command |
| `SPC_CMD_VAR_PHP_CONFIGURE_LDFLAGS` | `-L$BUILD_LIB_PATH` | `LDFLAGS` variable of PHP `configure` command |
| `SPC_CMD_VAR_PHP_MAKE_EXTRA_CFLAGS` | `-g0 -Os` or `-g -O0` (the latter when using `--no-strip`) | `EXTRA_CFLAGS` variable of PHP `make` command |
| `SPC_CMD_VAR_PHP_MAKE_EXTRA_LIBS` | `-lresolv` | Extra `EXTRA_LIBS` variables for PHP `make` command |
### Linux
| var name | default value | comment |
|----------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| `UPX_EXEC` | `$PKG_ROOT_PATH/bin/upx` | UPX compression tool path |
| `GNU_ARCH` | `x86_64` or `aarch64` | CPU architecture |
| `CC` | Alpine: `gcc`, Other: `$GNU_ARCH-linux-musl-gcc` | C Compiler |
| `CXX` | Alpine: `g++`, Other: `$GNU_ARCH-linux-musl-g++` | C++ Compiler |
| `AR` | Alpine: `ar`, Other: `$GNU_ARCH-linux-musl-ar` | Static library tools |
| `LD` | `ld.gold` | Linker |
| `PATH` | `/usr/local/musl/bin:/usr/local/musl/$GNU_ARCH-linux-musl/bin:$PATH` | System PATH |
| `SPC_DEFAULT_C_FLAGS` | empty | Default C flags |
| `SPC_DEFAULT_CXX_FLAGS` | empty | Default C++ flags |
| `SPC_CMD_PREFIX_PHP_BUILDCONF` | `./buildconf --force` | PHP `buildconf` command prefix |
| `SPC_CMD_PREFIX_PHP_CONFIGURE` | `LD_LIBRARY_PATH={ld_lib_path} ./configure --prefix= --with-valgrind=no --enable-shared=no --enable-static=yes --disable-all --disable-cgi --disable-phpdbg` | PHP `configure` command prefix |
| `SPC_CMD_PREFIX_PHP_MAKE` | `make -j$SPC_CONCURRENCY` | PHP `make` command prefix |
| `SPC_CMD_VAR_PHP_CONFIGURE_CFLAGS` | `$SPC_DEFAULT_C_FLAGS` | `CFLAGS` variable of PHP `configure` command |
| `SPC_CMD_VAR_PHP_CONFIGURE_CPPFLAGS` | `-I$BUILD_INCLUDE_PATH` | `CPPFLAGS` variable of PHP `configure` command |
| `SPC_CMD_VAR_PHP_CONFIGURE_LDFLAGS` | `-L$BUILD_LIB_PATH` | `LDFLAGS` variable of PHP `configure` command |
| `SPC_CMD_VAR_PHP_CONFIGURE_LIBS` | `-ldl -lpthread` | `LIBS` variable of PHP `configure` command |
| `SPC_CMD_VAR_PHP_MAKE_EXTRA_CFLAGS` | `-g0 -Os -fno-ident -fPIE` or `-g -O0 -fno-ident -fPIE` (the latter when using `--no-strip`) | `EXTRA_CFLAGS` variable of PHP `make` command |
| `SPC_CMD_VAR_PHP_MAKE_EXTRA_LIBS` | empty | Extra `EXTRA_LIBS` variables for PHP `make` command |
| `SPC_CMD_VAR_PHP_MAKE_EXTRA_LDFLAGS_PROGRAM` | `-all-static` (when using `clang`: `-Xcompiler -fuse-ld=lld -all-static`) | Additional `LDFLAGS` variable for `make` command |
| `SPC_NO_MUSL_PATH` | empty | Whether to not insert the PATH of the musl toolchain (not inserted when the value is `yes`) |
> `{ld_lib_path}` value is `/usr/local/musl/$GNU_ARCH-linux-musl/lib`。
### FreeBSD
Due to the small number of users of the FreeBSD system, we do not provide environment variables for the FreeBSD system for the time being.
### Unix
For Unix systems such as macOS, Linux, FreeBSD, etc., the following environment variables are common.
| var name | default value | comment |
|-------------------|------------------------------|----------------------------|
| `PATH` | `$BUILD_BIN_PATH:$PATH` | System PATH |
| `PKG_CONFIG_PATH` | `$BUILD_LIB_PATH/pkgconfig` | pkg-config search path |
| `PKG_CONFIG` | `$BUILD_BIN_PATH/pkg-config` | pkg-config executable path |
## Library Environment variables (Unix only)
Starting from 2.2.0, static-php-cli supports custom environment variables for all compilation dependent library commands of macOS, Linux, FreeBSD and other Unix systems.
In this way, you can adjust the behavior of compiling dependent libraries through environment variables at any time.
For example, you can set the optimization parameters for compiling the xxx library through `xxx_CFLAGS=-O0`.
Of course, not every library supports the injection of environment variables.
We currently provide three wildcard environment variables with the suffixes:
- `_CFLAGS`: CFLAGS for the compiler
- `_LDFLAGS`: LDFLAGS for the linker
- `_LIBS`: LIBS for the linker
The prefix is the name of the dependent library, and the specific name of the library is subject to `lib.json`.
Among them, the library name with `-` needs to replace `-` with `_`.
Here is an example of an optimization option that replaces the openssl library compilation:
```shell
openssl_CFLAGS="-O0"
```
The library name uses the same name listed in `lib.json` and is case-sensitive.
::: tip
When no relevant environment variables are specified, except for the following variables, the remaining values are empty by default:
| var name | var default value |
|-----------------------|-------------------------------------------------------------------------------------------------|
| `pkg_config_CFLAGS` | macOS: `$SPC_DEFAULT_C_FLAGS -Wimplicit-function-declaration -Wno-int-conversion`, Other: empty |
| `pkg_config_LDFLAGS` | Linux: `--static`, Other: empty |
| `imagemagick_LDFLAGS` | Linux: `-static`, Other: empty |
| `imagemagick_LIBS` | macOS: `-liconv`, Other: empty |
| `ldap_LDFLAGS` | `-L$BUILD_LIB_PATH` |
| `openssl_CFLAGS` | Linux: `$SPC_DEFAULT_C_FLAGS`, Other: empty |
| others... | empty |
:::
The following table is a list of library names that support customizing the above three variables:
| lib name |
|-------------|
| brotli |
| bzip |
| curl |
| freetype |
| gettext |
| gmp |
| imagemagick |
| ldap |
| libargon2 |
| libavif |
| libcares |
| libevent |
| openssl |
::: tip
Because adapting custom environment variables to each library is a particularly tedious task,
and in most cases you do not need custom environment variables for these libraries,
so we currently only support custom environment variables for some libraries.
If the library you need to customize environment variables is not listed above,
you can submit your request through [GitHub Issue](https://github.com/crazywhalecc/static-php-cli/issues).
:::

146
docs/en/guide/extension-notes.md Normal file
View File

@@ -0,0 +1,146 @@
# Extension Notes
Because it is a static compilation, extensions will not compile 100% perfectly,
and different extensions have different requirements for PHP and the environment,
which will be listed one by one here.
## curl
When using curl to request HTTPS, there may be an `error:80000002:system library::No such file or directory` error.
For details on the solution, see [FAQ - Unable to use ssl](../faq/#unable-to-use-ssl).
## phpmicro
1. Only PHP >= 8.0 is supported.
## swoole
1. swoole >= 5.0 Only PHP >= 8.0 is supported.
2. swoole Currently, curl hooks are not supported for PHP 8.0.x (which may be fixed in the future).
3. When compiling, if only `swoole` extension is included, the supported Swoole database coroutine hook will not be fully enabled.
If you need to use it, please add the corresponding `swoole-hook-xxx` extension.
4. The `zend_mm_heap corrupted` problem may occur in swoole under some extension combinations. The cause has not yet been found.
## swoole-hook-pgsql
swoole-hook-pgsql is not an extension, it's a Hook feature of Swoole.
If you use `swoole,swoole-hook-pgsql`, you will enable Swoole's PostgreSQL client and the coroutine mode of the `pdo_pgsql` extension.
swoole-hook-pgsql conflicts with the `pdo_pgsql` extension. If you want to use Swoole and `pdo_pgsql`, please delete the pdo_pgsql extension and enable `swoole` and `swoole-hook-pgsql`.
This extension contains an implementation of the coroutine environment for `pdo_pgsql`.
On macOS systems, `pdo_pgsql` may not be able to connect to the postgresql server normally, please use it with caution.
## swoole-hook-mysql
swoole-hook-mysql is not an extension, it's a Hook feature of Swoole.
If you use `swoole,swoole-hook-mysql`, you will enable the coroutine mode of Swoole's `mysqlnd` and `pdo_mysql`.
## swoole-hook-sqlite
swoole-hook-sqlite is not an extension, it's a Hook feature of Swoole.
If you use `swoole,swoole-hook-sqlite`, you will enable the coroutine mode of Swoole's `pdo_sqlite` (Swoole must be 5.1 or above).
swoole-hook-sqlite conflicts with the `pdo_sqlite` extension. If you want to use Swoole and `pdo_sqlite`, please delete the pdo_sqlite extension and enable `swoole` and `swoole-hook-sqlite`.
This extension contains an implementation of the coroutine environment for `pdo_sqlite`.
## swow
1. Only PHP version >= 8.0 is supported.
## imap
1. Kerberos is not supported
2. ext-imap is not thread safe due to the underlying c-client. It's not possible to use it in --enable-zts builds.
3. Because the extension may be dropped from php, we recommend you look for an alternative implementation, such as [Webklex/php-imap](https://github.com/Webklex/php-imap)
## gd
1. gd Extension relies on more additional Graphics library. By default,
using `bin/spc build gd` directly will not support some Graphics library, such as `libjpeg`, `libavif`, etc.
Currently, it supports four libraries: `freetype,libjpeg,libavif,libwebp`.
Therefore, the following command can be used to introduce them into the gd library:
```bash
bin/spc build gd --with-libs=freetype,libjpeg,libavif,libwebp --build-cli
```
## mcrypt
1. Currently not supported, and this extension will not be supported in the future. [#32](https://github.com/crazywhalecc/static-php-cli/issues/32)
## oci8
1. oci8 is an extension of the Oracle database, because the library on which the extension provided by Oracle does not provide a statically compiled version (`.a`) or source code,
and this extension cannot be compiled into php by static linking, so it cannot be supported.
## xdebug
1. Xdebug is a Zend extension. The functions of Xdebug depend on PHP's Zend engine and underlying code.
If you want to statically compile it into PHP, you may need a huge amount of patch code, which is not feasible.
2. The macOS platform can compile an xdebug extension under PHP compiled on the same platform,
extract the `xdebug.so` file, and then use the `--no-strip` parameter in static-php-cli to retain the debug symbol table and add the `ffi` extension.
The compiled `./php` binary can be configured and run by specifying the INI, eg `./php -d 'zend_extension=/path/to/xdebug.so' your-code.php`.
## xml
1. xml includes xml, xmlreader, xmlwriter, xsl, dom, simplexml, etc.
When adding xml extensions, it is best to enable these extensions at the same time.
2. libxml is included in xml extension. Enabling xml is equivalent to enabling libxml.
## glfw
1. glfw depends on OpenGL, and linux environment also needs X11, which cannot be linked statically.
2. macOS platform, we can compile and link system builtin OpenGL and related libraries dynamically.
## rar
1. The rar extension currently has a problem when compiling phpmicro with the `common` extension collection in the macOS x86_64 environment.
## pgsql
~~pgsql ssl connection is not compatible with openssl 3.2.0. See:~~
- ~~<https://github.com/Homebrew/homebrew-core/issues/155651>~~
- ~~<https://github.com/Homebrew/homebrew-core/pull/155699>~~
- ~~<https://github.com/postgres/postgres/commit/c82207a548db47623a2bfa2447babdaa630302b9>~~
pgsql 16.2 has fixed this bug, now it's working.
When pgsql uses SSL connection, there may be `error:80000002:system library::No such file or directory` error,
For details on the solution, see [FAQ - Unable to use ssl](../faq/#unable-to-use-ssl).
## openssl
When using openssl-based extensions (such as curl, pgsql and other network libraries),
there may be an `error:80000002:system library::No such file or directory` error.
For details on the solution, see [FAQ - Unable to use ssl](../faq/#unable-to-use-ssl).
## password-argon2
1. password-argon2 is not a standard extension, it is an additional algorithm for the `password_hash` function.
2. On Linux systems, `password-argon2` dependency `libargon2` conflicts with the `libsodium` library.
## ffi
1. Linux not supported yet: Due to limitations of the Linux system, although the ffi extension can be compiled successfully, it cannot be used to load other `so` extensions.
The prerequisite for Linux to support loading `so` extensions is dynamic compilation, but dynamic compilation conflicts with the purpose of this project.
2. macOS supports the ffi extension, but errors will occur when some kernels do not contain debugging symbols.
3. Windows x64 supports the ffi extension.
## xhprof
The xhprof extension consists of three parts: `xhprof_extension`, `xhprof_html`, `xhprof_libs`.
Only `xhprof_extension` is included in the compiled binary.
If you need to use xhprof,
please download the source code from [pecl.php.net/package/xhprof](http://pecl.php.net/package/xhprof) and specify the `xhprof_libs` and `xhprof_html` paths for use.
## event
If you enable event extension on macOS, the `openpty` will be disabled due to issue:
- [static-php-cli#335](https://github.com/crazywhalecc/static-php-cli/issues/335)
## parallel
Parallel is only supported on PHP 8.0 ZTS and above.

27
docs/en/guide/extensions.md Normal file
View File

@@ -0,0 +1,27 @@
# Extensions
> - `yes`: supported
> - _blank_: not supported yet, or WIP
> - `no` with issue link: confirmed to be unavailable due to issue
> - `partial` with issue link: supported but not perfect due to issue
<!--@include: ../../extensions.md-->
::: tip
If an extension you need is missing, you can create a [Feature Request](https://github.com/crazywhalecc/static-php-cli/issues).
Some extensions or libraries that the extension depends on will have some optional features.
For example, the gd library optionally supports libwebp, freetype, etc.
If you only use `bin/spc build gd --build-cli` they will not be included (static-php-cli defaults to the minimum dependency principle).
You can use `--with-libs=` to add these libraries when compiling.
When the dependent libraries of this compilation include them, gd will automatically use them to enable these features.
(For example: `bin/spc build gd --with-libs=libwebp,freetype --build-cli`)
Alternatively you can use `--with-suggested-exts` and `--with-suggested-libs` to enable all optional dependencies of these extensions and libraries.
(For example: `bin/spc build gd --with-suggested-libs --build-cli`)
If you don't know whether an extension has optional features,
you can check the [spc configuration file](https://github.com/crazywhalecc/static-php-cli/tree/main/config)
or use the command `bin/spc dev:extensions` (library dependency is `lib-suggests`, extension dependency is `ext-suggests`).
:::

43
docs/en/guide/index.md Normal file
View File

@@ -0,0 +1,43 @@
# Guide
Static php cli is a tool used to build statically compiled PHP binaries,
currently supporting Linux and macOS systems.
In the guide section, you will learn how to use static php cli to build standalone PHP programs.
- [GitHub Action Build](./action-build)
- [Manual Build](./manual-build)
- [Supported Extensions](./extensions)
::: tip
If you are a native English speaker, some corrections to the documentation are welcome.
:::
## Compilation Environment
The following is the architecture support situation, where :gear: represents support for GitHub Action build,
:computer: represents support for local manual build, and empty represents temporarily not supported.
| | x86_64 | aarch64 |
|---------|-------------------|-------------------|
| macOS | :gear: :computer: | :gear: :computer: |
| Linux | :gear: :computer: | :gear: :computer: |
| Windows | :gear: :computer: | |
| FreeBSD | :computer: | :computer: |
Among them, Linux is currently only tested on Ubuntu, Debian, and Alpine distributions,
and other distributions have not been tested, which cannot guarantee successful compilation.
For untested distributions, local compilation can be done using methods such as Docker to avoid environmental issues.
There are two architectures for macOS: `x86_64` and `Arm`, but binaries compiled on one architecture cannot be directly used on the other architecture.
Rosetta 2 cannot guarantee that programs compiled with `Arm` architecture can fully run on `x86_64` environment.
Windows currently only supports the x86_64 architecture, and does not support 32-bit x86 or arm64 architecture.
## Supported PHP Version
Currently, static php cli supports PHP versions 8.0 to 8.3, and theoretically supports PHP 7.4 and earlier versions.
Simply select the earlier version when downloading.
However, due to some extensions and special components that have stopped supporting earlier versions of PHP,
static-php-cli will not explicitly support earlier versions.
We recommend that you compile the latest PHP version possible for a better experience.

525
docs/en/guide/manual-build.md Normal file
View File

@@ -0,0 +1,525 @@
# Build (Linux, macOS, FreeBSD)
This section covers the build process for Linux, macOS, and FreeBSD. If you want to build on Windows,
also need to read [Build on Windows](./build-on-windows).
### Build locally (using SPC binary) (recommended)
This project provides a binary file of static-php-cli.
You can directly download the binary file of the corresponding platform and then use it to build static PHP.
Currently, the platforms supported by `spc` binary are Linux and macOS.
Here's how to download from self-hosted server:
```bash
# Download from self-hosted nightly builds (sync with main branch)
# For Linux x86_64
curl -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-x86_64
# For Linux aarch64
curl -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-linux-aarch64
# macOS x86_64 (Intel)
curl -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-macos-x86_64
# macOS aarch64 (Apple)
curl -o spc https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-macos-aarch64
# Windows (x86_64, win10 build 17063 or later)
curl.exe -o spc.exe https://dl.static-php.dev/static-php-cli/spc-bin/nightly/spc-windows-x64.exe
# Add execute perm (Linux and macOS only)
chmod +x ./spc
# Run (Linux and macOS)
./spc --version
# Run (Windows powershell)
.\spc.exe --version
```
> If you are using the packaged `spc` binary, you will need to replace the leading `bin/spc` with `./spc` in all the commands below.
### Build locally (using source code)
If you have problems using the spc binary, or if you need to modify the static-php-cli source code, download static-php-cli from the source code.
Currently, it supports building on macOS and Linux.
macOS supports the latest version of the operating system and two architectures,
while Linux supports Debian and derivative distributions, as well as Alpine Linux.
Because this project itself is developed using PHP,
it is also necessary to install PHP on the system during compilation.
This project also provides static binary PHP suitable for this project,
which can be selected and used according to actual situations.
```bash
# clone repo
git clone https://github.com/crazywhalecc/static-php-cli.git --depth=1
cd static-php-cli
# You need to install the PHP environment first before running Composer and this project. The installation method can be referred to below.
composer update
```
### Use System PHP
Below are some example commands for installing PHP and Composer in the system.
It is recommended to search for the specific installation method yourself or ask the AI search engine to obtain the answer,
which will not be elaborated here.
```bash
# [macOS], need install Homebrew first. See https://brew.sh/
# Remember change your composer executable path. For M1/M2 Chip mac, "/opt/homebrew/bin/", for Intel mac, "/usr/local/bin/". Or add it to your own path.
brew install php wget
wget https://getcomposer.org/download/latest-stable/composer.phar -O /path/to/your/bin/composer && chmod +x /path/to/your/bin/composer
# [Debian], you need to make sure your php version >= 8.1 and composer >= 2.0
sudo apt install php-cli composer php-tokenizer
# [Alpine]
apk add bash file wget xz php81 php81-common php81-pcntl php81-tokenizer php81-phar php81-posix php81-xml composer
```
::: tip
Currently, some versions of Ubuntu install older PHP versions,
so no installation commands are provided. If necessary, it is recommended to add software sources such as ppa first,
and then install the latest version of PHP and tokenizer, XML, and phar extensions.
Older versions of Debian may have an older (<= 7.4) version of PHP installed by default, it is recommended to upgrade Debian first.
:::
### Use Docker
If you don't want to install PHP and Composer runtime environment on your system, you can use the built-in Docker environment build script.
```bash
# To use directly, replace `bin/spc` with `bin/spc-alpine-docker` in all used commands
bin/spc-alpine-docker
```
The first time the command is executed, `docker build` will be used to build a Docker image.
The default built Docker image is the `x86_64` architecture, and the image name is `cwcc-spc-x86_64`.
If you want to build `aarch64` static-php-cli in `x86_64` environment,
you can use qemu to emulate the arm image to run Docker, but the speed will be very slow.
Use command: `SPC_USE_ARCH=aarch64 bin/spc-alpine-docker`.
If it prompts that sudo is required to run after running,
execute the following command once to grant static-php-cli permission to execute sudo:
```bash
export SPC_USE_SUDO=yes
```
### Use Precompiled Static PHP Binaries
If you don't want to use Docker and install PHP in the system,
you can directly download the php binary cli program compiled by this project itself. The usage process is as follows:
Deploy the environment using the command, the command will download a static php-cli binary from [self-hosted server](https://dl.static-php.dev/static-php-cli/).
Next, it will automatically download Composer from [getcomposer](https://getcomposer.org/download/latest-stable/composer.phar) or [Aliyun mirror](https://mirrors.aliyun.com/composer/composer.phar).
::: tip
Using precompiled static PHP binaries is currently only supported on Linux and macOS.
The FreeBSD environment is currently not supported due to the lack of an automated build environment.
:::
```bash
bin/setup-runtime
# For users with special network environments such as mainland China, you can use mirror sites (aliyun) to speed up the download speed
bin/setup-runtime --mirror china
```
This script will download two files in total: `bin/php` and `bin/composer`. After the download is complete, there are two ways to use it:
1. Add the `bin/` directory to the PATH: `export PATH="/path/to/your/static-php-cli/bin:$PATH"`, after adding the path,
it is equivalent to installing PHP in the system, you can directly Use commands such as `composer`, `php -v`, or directly use `bin/spc`.
2. Direct call, such as executing static-php-cli command: `bin/php bin/spc --help`, executing Composer: `bin/php bin/composer update`.
## Command - download
Use the command `bin/spc download` to download the source code required for compilation,
including php-src and the source code of various dependent libraries.
```bash
# Download all dependencies
bin/spc download --all
# Download all dependent packages, and specify the main version of PHP to download, optional: 7.3, 7.4, 8.0, 8.1, 8.2, 8.3
bin/spc download --all --with-php=8.2
# Show download progress bar while downloading (curl)
bin/spc download --all --debug
# Delete old download data
bin/spc download --clean
# Download specified dependencies
bin/spc download php-src,micro,zstd,ext-zstd
# Download only extensions and libraries to be compiled (use extensions, including suggested libraries)
bin/spc download --for-extensions=openssl,swoole,zip,pcntl,zstd
# Download only the extensions and dependent libraries to be compiled (use extensions, excluding suggested libraries)
bin/spc download --for-extensions=openssl,swoole,zip,pcntl --without-suggestions
# Download only libraries to be compiled (use libraries, including suggested libraries and required libraries, can use --for-extensions together)
bin/spc download --for-libs=liblz4,libevent --for-extensions=pcntl,rar,xml
# Download only libraries to be compiled (use libraries, excluding suggested libraries)
bin/spc download --for-libs=liblz4,libevent --without-suggestions
# When downloading sources, ignore some source caches (always force download, e.g. switching PHP version)
bin/spc download --for-extensions=curl,pcntl,xml --ignore-cache-sources=php-src --with-php=8.3
# Set retry times (default is 0)
bin/spc download --all --retry=2
```
If the network in your area is not good, or the speed of downloading the dependency package is too slow,
you can download `download.zip` which is packaged regularly every week from GitHub Action,
and use the command to directly use the zip archive as a dependency.
Dependent packages can be downloaded locally from [Action](https://github.com/static-php/static-php-cli-hosted/actions/workflows/download-cache.yml).
Enter Action and select the latest Workflow that has been successfully run, and download `download-files-x.y`.
```bash
bin/spc download --from-zip=/path/to/your/download.zip
```
If a source cannot be downloaded all the time, or you need to download some specific version of the package,
such as downloading the beta version of PHP, the old version of the library, etc.,
you can use the parameter `-U` or `--custom-url` to rewrite the download link,
Make the downloader force the link you specify to download packages from this source.
The method of use is `{source-name}:{url}`, which can rewrite the download URLs of multiple libraries at the same time.
Also, it is available when downloading with the `--for-extensions` option.
```bash
# Specifying to download a beta version of PHP8.3
bin/spc download --all -U "php-src:https://downloads.php.net/~eric/php-8.3.0beta1.tar.gz"
# Specifying to download an older version of the curl library
bin/spc download --all -U "curl:https://curl.se/download/curl-7.88.1.tar.gz"
```
## Command - doctor
If you can run `bin/spc` normally but cannot compile static PHP or dependent libraries normally,
you can run `bin/spc doctor` first to check whether the system itself lacks dependencies.
```bash
# Quick check
bin/spc doctor
# Quickly check and fix when it can be automatically repaired (use package management to install dependent packages, only support the above-mentioned operating systems and distributions)
bin/spc doctor --auto-fix
```
## Command - build
Use the build command to start building the static php binary.
Before executing the `bin/spc build` command, be sure to use the `download` command to download sources.
It is recommended to use `doctor` to check the environment.
### Basic build
You need to go to [Extension List](./extensions) or [Command Generator](./cli-generator) to select the extension you want to add,
and then use the command `bin/spc build` to compile.
You need to specify a compilation target, choose from the following parameters:
- `--build-cli`: Build a cli sapi (command line interface, which can execute PHP code on the command line)
- `--build-fpm`: Build a fpm sapi (php-fpm, used in conjunction with other traditional fpm architecture software such as nginx)
- `--build-micro`: Build a micro sapi (used to build a standalone executable binary containing PHP code)
- `--build-embed`: Build an embed sapi (used to embed into other C language programs)
- `--build-all`: build all above sapi
```bash
# Compile PHP with bcmath,curl,openssl,ftp,posix,pcntl extensions, the compilation target is cli
bin/spc build bcmath,curl,openssl,ftp,posix,pcntl --build-cli
# Compile PHP with phar,curl,posix,pcntl,tokenizer extensions, compile target is micro
bin/spc build phar,curl,posix,pcntl,tokenizer --build-micro
```
::: tip
If you need to repeatedly build and debug, you can delete the `buildroot/` and `source/` directories so that you can re-extract and build all you need from the downloaded source code package:
```shell
# remove
rm -rf buildroot source
# build again
bin/spc build bcmath,curl,openssl,ftp,posix,pcntl --build-cli
```
:::
::: tip
If you want to build multiple versions of PHP and don't want to build other dependent libraries repeatedly each time,
you can use `switch-php-version` to quickly switch to another version and compile after compiling one version:
```shell
# switch to 8.3
bin/spc switch-php-version 8.3
# build
bin/spc build bcmath,curl,openssl,ftp,posix,pcntl --build-cli
# switch to 8.0
bin/spc switch-php-version 8.0
# build
bin/spc build bcmath,curl,openssl,ftp,posix,pcntl --build-cli
```
:::
### Debug
If you encounter problems during the compilation process, or want to view each executing shell command,
you can use `--debug` to enable debug mode and view all terminal logs:
```bash
bin/spc build mysqlnd,pdo_mysql --build-all --debug
```
### Build Options
During the compilation process, in some special cases,
the compiler and the content of the compilation directory need to be intervened.
You can try to use the following commands:
- `--cc=XXX`: Specifies the execution command of the C language compiler (Linux default `musl-gcc` or `gcc`, macOS default `clang`)
- `--cxx=XXX`: Specifies the execution command of the C++ language compiler (Linux defaults to `g++`, macOS defaults to `clang++`)
- `--with-clean`: clean up old make files before compiling PHP
- `--enable-zts`: Make compiled PHP thread-safe version (default is NTS version)
- `--no-strip`: Do not run `strip` after compiling the PHP library to trim the binary file to reduce its size (the macOS binary file without trim can use dynamically linked third-party extensions)
- `--with-libs=XXX,YYY`: Compile the specified dependent library before compiling PHP, and activate some extended optional functions (such as libavif of the gd library, etc.)
- `-I xxx=yyy`: Hard compile INI options into PHP before compiling (support multiple options, alias is `--with-hardcoded-ini`)
- `--with-micro-fake-cli`: When compiling micro, let micro's `PHP_SAPI` pretend to be `cli` (for compatibility with some programs that check `PHP_SAPI`)
- `--disable-opcache-jit`: Disable opcache jit (enabled by default)
- `-P xxx.php`: Inject external scripts during static-php-cli compilation (see **Inject external scripts** below for details)
- `--without-micro-ext-test`: After building micro.sfx, do not test the running results of different extensions in micro.sfx
- `--with-suggested-exts`: Add `ext-suggests` as dependencies when compiling
- `--with-suggested-libs`: Add `lib-suggests` as dependencies when compiling
- `--with-upx-pack`: Use UPX to reduce the size of the binary file after compilation (you need to use `bin/spc install-pkg upx` to install upx first)
For hardcoding INI options, it works for cli, micro, embed sapi. Here is a simple example where we preset a larger `memory_limit` and disable the `system` function:
```bash
bin/spc build bcmath,pcntl,posix --build-all -I "memory_limit=4G" -I "disable_functions=system"
```
## Command - micro:combine
Use the `micro:combine` command to build the compiled `micro.sfx` and your code (`.php` or `.phar` file) into an executable binary.
You can also use this command to directly build a micro binary injected with ini configuration.
::: tip
Injecting ini configuration refers to adding a special structure after micro.sfx to save ini configuration items before combining micro.sfx with PHP source code.
micro.sfx can identify the INI file header through a special byte, and the micro can be started with INI through the INI file header.
The original wiki of this feature is in [phpmicro - Wiki](https://github.com/easysoft/phpmicro/wiki/INI-settings), and this feature may change in the future.
:::
The following is the general usage, directly packaging the php source code into a file:
```bash
# Before doing the packaging process, you should use `build --build-micro` to compile micro.sfx
echo "<?php echo 'hello';" > a.php
bin/spc micro:combine a.php
# Just use it
./my-app
```
You can use the following options to specify the file name to be output, and you can also specify micro.sfx in other paths for packaging.
```bash
# specify the output filename
bin/spc micro:combine a.php --output=custom-bin
# Use absolute path
bin/spc micro:combine a.php -O /tmp/my-custom-app
# Specify micro.sfx in other locations for packaging
bin/spc micro:combine a.app --with-micro=/path/to/your/micro.sfx
```
If you want to inject ini configuration items, you can use the following parameters to add ini to the executable file from a file or command line option.
```bash
# Specified using command-line options (-I is shorthand for --with-ini-set)
bin/spc micro:combine a.php -I "a=b" -I "foo=bar"
# Use ini file specification (-N is shorthand for --with-ini-file)
bin/spc micro:combine a.php -N /path/to/your/custom.ini
```
::: warning
Note, please do not directly use the PHP source code or the `php.ini` file in the system-installed PHP,
it is best to manually write an ini configuration file that you need, for example:
```ini
; custom.ini
curl.cainfo=/path/to/your/cafile.pem
memory_limit=1G
```
The ini injection of this command is achieved by appending a special structure after micro.sfx,
which is different from the function of inserting hard-coded INI during compilation.
:::
If you want to package phar, just replace `a.php` with the packaged phar file.
But please note that micro.sfx under phar needs extra attention to the path problem, see [Developing - Phar directory issue](../develop/structure#phar-application-directory-issue).
## Command - extract
Use the command `bin/spc extract` to unpack and copy the source code required for compilation,
including php-src and the source code of various dependent libraries (you need to specify the name of the library to be unpacked).
For example, after we have downloaded sources, we want to distribute and execute the build process,
manually unpack and copy the package to a specified location, and we can use commands.
```bash
# Unzip the downloaded compressed package of php-src and libxml2, and store the decompressed source code in the source directory
bin/spc extract php-src,libxml2
```
## Dev Command - dev
Debug commands refer to a collection of commands that can assist in outputting some information
when you use static-php-cli to build PHP or modify and enhance the static-php-cli project itself.
- `dev:extensions`: output all currently supported extension names, or output the specified extension information
- `dev:php-version`: output the currently compiled PHP version (by reading `php_version.h`)
- `dev:sort-config`: Sort the list of configuration files in the `config/` directory in alphabetical order
- `dev:lib-ver <lib-name>`: Read the version from the source code of the dependency library (only available for specific dependency libraries)
- `dev:ext-ver <ext-name>`: Read the corresponding version from the source code of the extension (only available for specific extensions)
```bash
# output all extensions information
bin/spc dev:extensions
# Output the meta information of the specified extension
bin/spc dev:extensions mongodb,curl,openssl
# Output the specified columns
# Available column name: lib-depends, lib-suggests, ext-depends, ext-suggests, unix-only, type
bin/spc dev:extensions --columns=lib-depends,type,ext-depends
# Output the currently compiled PHP version
# You need to decompress the downloaded PHP source code to the source directory first
# You can use `bin/spc extract php-src` to decompress the source code separately
bin/spc dev:php-version
# Sort the configuration files in the config/ directory in alphabetical order (e.g. ext.json)
bin/spc dev:sort-config ext
```
## Command - install-pkg
Use the command `bin/spc install-pkg` to download some precompiled or closed source tools and install them into the `pkgroot` directory.
When `bin/spc doctor` automatically repairs the Windows environment, tools such as nasm and perl will be downloaded, and the installation process of `install-pkg` will also be used.
Here is an example of installing the tool:
- Download and install UPX (Linux and Windows only): `bin/spc install-pkg upx`
## Command - del-download
In some cases, you need to delete single or multiple specified download source files and re-download them, such as switching PHP versions.
The `bin/spc del-download` command is provided after the `2.1.0-beta.4` version. Specified source files can be deleted.
Deletes downloaded source files containing precompiled packages and source code named as keys in `source.json` or `pkg.json`. Here are some examples:
- Delete the old PHP source code and switch to download the 8.3 version: `bin/spc del-download php-src && bin/spc download php-src --with-php=8.3`
- Delete the download file of redis extension: `bin/spc del-download redis`
- Delete the downloaded musl-toolchain x86_64: `bin/spc del-download musl-toolchain-x86_64-linux`
## Inject External Script
Injecting external scripts refers to inserting one or more scripts during the static-php-cli compilation process
to more flexibly support parameter modifications and source code patches in different environments.
Under normal circumstances, this function mainly solves the problem that the patch cannot be modified
by modifying the static-php-cli code when compiling with `spc` binary.
There is another situation: your project directly depends on the `crazywhalecc/static-php-cli` repository and is synchronized with main branch,
but some proprietary modifications are required, and these feature are not suitable for merging into the main branch.
In view of the above situation, in the official version 2.0.0, static-php-cli has added multiple event trigger points.
You can write an external `xx.php` script and pass it in through the command line parameter `-P` and execute.
When writing to inject external scripts, the methods you will use are `builder()` and `patch_point()`.
Among them, `patch_point()` obtains the name of the current event, and `builder()` obtains the BuilderBase object.
Because the incoming patch point does not distinguish between events,
you must write the code you want to execute in `if(patch_point() === 'your_event_name')`,
otherwise it will be executed repeatedly in other events.
The following are the supported `patch_point` event names and corresponding locations:
| Event name | Event description |
|------------------------------|----------------------------------------------------------------------------------------------------|
| before-libs-extract | Triggered before the dependent libraries extracted |
| after-libs-extract | Triggered after the compiled dependent libraries extracted |
| before-php-extract | Triggered before PHP source code extracted |
| after-php-extract | Triggered after PHP source code extracted |
| before-micro-extract | Triggered before phpmicro extract |
| after-micro-extract | Triggered after phpmicro extracted |
| before-exts-extract | Triggered before the extension (to be compiled) extracted to the PHP source directory |
| after-exts-extract | Triggered after the extension extracted to the PHP source directory |
| before-library[*name*]-build | Triggered before the library named `name` is compiled (such as `before-library[postgresql]-build`) |
| after-library[*name*]-build | Triggered after the library named `name` is compiled |
| before-php-buildconf | Triggered before compiling PHP command `./buildconf` |
| before-php-configure | Triggered before compiling PHP command `./configure` |
| before-php-make | Triggered before compiling PHP command `make` |
| before-sanity-check | Triggered after compiling PHP but before running extended checks |
The following is a simple example of temporarily modifying the PHP source code.
Enable the CLI function to search for the `php.ini` configuration in the current working directory:
```php
// a.php
<?php
// patch it before `./buildconf` executed
if (patch_point() === 'before-php-buildconf') {
\SPC\store\FileSystem::replaceFileStr(
SOURCE_PATH . '/php-src/sapi/cli/php_cli.c',
'sapi_module->php_ini_ignore_cwd = 1;',
'sapi_module->php_ini_ignore_cwd = 0;'
);
}
```
```bash
bin/spc build mbstring --build-cli -P a.php
# Write in ./
echo 'memory_limit=8G' > ./php.ini
```
```
$ buildroot/bin/php -i | grep Loaded
Loaded Configuration File => /Users/jerry/project/git-project/static-php-cli/php.ini
$ buildroot/bin/php -i | grep memory
memory_limit => 8G => 8G
```
For the objects, methods and interfaces supported by static-php-cli, you can read the source code. Most methods and objects have corresponding comments.
Commonly used objects and functions using the `-P` function are:
- `SPC\store\FileSystem`: file management class
- `::replaceFileStr(string $filename, string $search, $replace)`: Replace file string content
- `::replaceFileStr(string $filename, string $pattern, $replace)`: Regularly replace file content
- `::replaceFileUser(string $filename, $callback)`: User-defined function replaces file content
- `::copyDir(string $from, string $to)`: Recursively copy a directory to another location
- `::convertPath(string $path)`: Convert the path delimiter to the current system delimiter
- `::scanDirFiles(string $dir, bool $recursive = true, bool|string $relative = false, bool $include_dir = false)`: Traverse directory files
- `SPC\builder\BuilderBase`: Build object
- `->getPatchPoint()`: Get the current injection point name
- `->getOption(string $key, $default = null)`: Get command line and compile-time options
- `->getPHPVersionID()`: Get the currently compiled PHP version ID
- `->getPHPVersion()`: Get the currently compiled PHP version number
- `->setOption(string $key, $value)`: Set options
- `->setOptionIfNotExists(string $key, $value)`: Set option if option does not exist
::: tip
static-php-cli has many open methods, which cannot be listed in the docs,
but as long as it is a `public function` and is not marked as `@internal`, it theoretically can be called.
:::

33
docs/en/guide/troubleshooting.md Normal file
View File

@@ -0,0 +1,33 @@
# Troubleshooting
Various failures may be encountered in the process of using static-php-cli,
here will describe how to check the errors by yourself and report Issue.
## Download Failure
Problems with downloading resources are one of the most common problems with spc.
The main reason is that the addresses used for SPC download resources are generally the official website of the corresponding project or GitHub, etc.,
and these websites may occasionally go down and block IP addresses.
Currently, version 2.0.0 has not added an automatic retry mechanism, so after encountering a download failure,
you can try to call the download command multiple times. If you confirm that the address is indeed inaccessible,
you can submit an Issue or PR to update the url or download type.
## Doctor Can't Fix Something
In most cases, the doctor module can automatically repair and install missing system environments,
but there are also special circumstances where the automatic repair function cannot be used normally.
Due to system limitations (for example, software such as Visual Studio cannot be automatically installed under Windows),
the automatic repair function cannot be used for some projects.
When encountering a function that cannot be automatically repaired,
if you encounter the words `Some check items can not be fixed`,
it means that it cannot be automatically repaired.
Please submit an issue according to the method displayed on the terminal or repair the environment yourself.
## Compile Error
When you encounter a compilation error, if the `--debug` log is not enabled, please enable the debug log first,
and then determine the command that reported the error.
The error terminal output is very important for fixing compilation errors.
When submitting an issue, please upload the last error fragment of the terminal log (or the entire terminal log output),
and include the `spc` command and parameters used.

21
docs/en/index.md Normal file
View File

@@ -0,0 +1,21 @@
---
# https://vitepress.dev/reference/default-theme-home-page
layout: home
hero:
name: "static-php-cli"
tagline: "Build standalone PHP binary on Linux, macOS, FreeBSD, Windows, with PHP project together, with popular extensions included."
actions:
- theme: brand
text: Guide
link: ./guide/
features:
- title: Static CLI Binary
details: You can easily compile a standalone php binary for general use. Including CLI, FPM sapi.
- title: Micro Self-Extracted Executable
details: You can compile a self-extracted executable and build with your php source code.
- title: Dependency Management
details: static-php-cli comes with dependency management and supports installation of different types of PHP extensions.
---