2022-10-13 18:05:22 +02:00
# Compile From Sources
2024-08-20 03:51:29 +02:00
This document explains how to create a FrankenPHP binary that will load PHP as a dynamic library.
2023-09-12 22:08:19 +02:00
This is the recommended method.
2025-05-30 12:13:58 +02:00
Alternatively, [fully and mostly static builds ](static.md ) can also be created.
2023-09-12 22:08:19 +02:00
2022-10-13 18:05:22 +02:00
## Install PHP
2024-08-20 03:51:29 +02:00
FrankenPHP is compatible with PHP 8.2 and superior.
2022-10-13 18:05:22 +02:00
2025-05-30 12:13:58 +02:00
### With Homebrew (Linux and Mac)
The easiest way to install a version of libphp compatible with FrankenPHP is to use the ZTS packages provided by [Homebrew PHP ](https://github.com/shivammathur/homebrew-php ).
First, if not already done, install [Homebrew ](https://brew.sh ).
Then, install the ZTS variant of PHP, Brotli (optional, for compression support) and watcher (optional, for file change detection):
``` console
brew install shivammathur/php/php-zts brotli watcher
brew link --overwrite --force shivammathur/php/php-zts
```
### By Compiling PHP
Alternatively, you can compile PHP from sources with the options needed by FrankenPHP by following these steps.
2025-08-29 07:46:40 -03:00
First, [get the PHP sources ](https://www.php.net/downloads.php ) and extract them:
2022-10-13 18:05:22 +02:00
2023-09-20 14:15:41 +02:00
``` console
2023-08-06 15:22:32 +02:00
tar xf php-*
cd php-*/
2022-10-13 18:05:22 +02:00
```
2024-08-20 03:51:29 +02:00
Then, run the `configure` script with the options needed for your platform.
2024-11-12 22:50:53 +01:00
The following `./configure` flags are mandatory, but you can add others, for example, to compile extensions or additional features.
2022-10-13 18:05:22 +02:00
2025-05-30 12:13:58 +02:00
#### Linux
2022-10-13 18:05:22 +02:00
2023-09-20 14:15:41 +02:00
``` console
2022-10-13 18:05:22 +02:00
./configure \
--enable-embed \
--enable-zts \
2023-03-05 15:47:20 +01:00
--disable-zend-signals \
--enable-zend-max-execution-timers
2022-10-13 18:05:22 +02:00
```
2025-05-30 12:13:58 +02:00
#### Mac
2022-10-13 18:05:22 +02:00
2025-05-30 12:13:58 +02:00
Use the [Homebrew ](https://brew.sh/ ) package manager to install the required and optional dependencies:
2022-10-13 18:05:22 +02:00
2023-09-20 14:15:41 +02:00
``` console
2025-05-30 12:13:58 +02:00
brew install libiconv bison brotli re2c pkg-config watcher
2022-10-13 18:05:22 +02:00
echo 'export PATH="/opt/homebrew/opt/bison/bin:$PATH"' >> ~/.zshrc
```
Then run the configure script:
2023-09-20 14:15:41 +02:00
``` console
2022-10-13 18:05:22 +02:00
./configure \
2025-05-30 12:13:58 +02:00
--enable-embed \
2022-10-13 18:05:22 +02:00
--enable-zts \
--disable-zend-signals \
--with-iconv=/opt/homebrew/opt/libiconv/
```
2025-05-30 12:13:58 +02:00
#### Compile PHP
2022-10-13 18:05:22 +02:00
2023-09-20 14:15:41 +02:00
Finally, compile and install PHP:
2022-10-13 18:05:22 +02:00
2023-09-20 14:15:41 +02:00
``` console
2024-08-20 03:51:29 +02:00
make -j"$(getconf _NPROCESSORS_ONLN)"
2023-07-04 14:45:31 +02:00
sudo make install
2022-10-13 18:05:22 +02:00
```
2024-10-24 14:14:47 +02:00
## Install Optional Dependencies
Some FrankenPHP features depend on optional system dependencies that must be installed.
Alternatively, these features can be disabled by passing build tags to the Go compiler.
2025-11-18 09:59:53 +01:00
| Feature | Dependency | Build tag to disable it |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------ | ----------------------- |
| Brotli compression | [Brotli ](https://github.com/google/brotli ) | nobrotli |
| Restart workers on file change | [Watcher C ](https://github.com/e-dant/watcher/tree/release/watcher-c ) | nowatcher |
| [Mercure ](mercure.md ) | [Mercure Go library ](https://pkg.go.dev/github.com/dunglas/mercure ) (automatically installed, AGPL licensed) | nomercure |
2024-10-24 14:14:47 +02:00
2023-11-01 00:06:52 +01:00
## Compile the Go App
2022-10-13 18:05:22 +02:00
2025-05-30 12:13:58 +02:00
You can now build the final binary.
2023-11-01 00:06:52 +01:00
### Using xcaddy
2025-05-30 12:13:58 +02:00
The recommended way is to use [xcaddy ](https://github.com/caddyserver/xcaddy ) to compile FrankenPHP.
`xcaddy` also allows to easily add [custom Caddy modules ](https://caddyserver.com/docs/modules/ ) and FrankenPHP extensions:
2023-11-01 00:06:52 +01:00
``` console
2023-12-14 22:45:09 +01:00
CGO_ENABLED=1 \
2024-10-24 14:14:47 +02:00
XCADDY_GO_BUILD_FLAGS="-ldflags='-w -s' -tags=nobadger,nomysql,nopgx" \
2024-11-12 22:50:53 +01:00
CGO_CFLAGS=$(php-config --includes) \
CGO_LDFLAGS="$(php-config --ldflags) $(php-config --libs)" \
2023-12-14 22:45:09 +01:00
xcaddy build \
2023-11-01 00:06:52 +01:00
--output frankenphp \
--with github.com/dunglas/frankenphp/caddy \
--with github.com/dunglas/mercure/caddy \
2025-11-26 14:19:27 +07:00
--with github.com/dunglas/vulcain/caddy \
--with github.com/dunglas/caddy-cbrotli
2025-05-30 12:13:58 +02:00
# Add extra Caddy modules and FrankenPHP extensions here
2025-11-26 14:19:27 +07:00
# optionally, if you would like to compile from your frankenphp sources:
# --with github.com/dunglas/frankenphp=$(pwd) \
# --with github.com/dunglas/frankenphp/caddy=$(pwd)/caddy
2023-12-01 17:26:21 +01:00
```
2023-12-14 22:45:09 +01:00
> [!TIP]
>
> If you're using musl libc (the default on Alpine Linux) and Symfony,
> you may need to increase the default stack size.
> Otherwise, you may get errors like `PHP Fatal error: Maximum call stack size of 83360 bytes reached during compilation. Try splitting expression`
>
> To do so, change the `XCADDY_GO_BUILD_FLAGS` environment variable to something like
> `XCADDY_GO_BUILD_FLAGS=$'-ldflags "-w -s -extldflags \'-Wl,-z,stack-size=0x80000\'"'`
2024-11-12 22:50:53 +01:00
> (change the stack size value according to your app needs).
2025-05-30 12:13:58 +02:00
### Without xcaddy
Alternatively, it's possible to compile FrankenPHP without `xcaddy` by using the `go` command directly:
``` console
2025-07-01 16:29:55 +08:00
curl -L https://github.com/php/frankenphp/archive/refs/heads/main.tar.gz | tar xz
2025-05-30 12:13:58 +02:00
cd frankenphp-main/caddy/frankenphp
CGO_CFLAGS=$(php-config --includes) CGO_LDFLAGS="$(php-config --ldflags) $(php-config --libs)" go build -tags=nobadger,nomysql,nopgx
```
