frankenphp/docs/compile.md

Compile From Sources

This document explain how to create a FrankenPHP build that will load PHP as a dynamic library. This is the recommended method.

Alternatively, creating static builds is also possible.

Install PHP

FrankenPHP is compatible with the PHP 8.2 and superior.

First, get the sources of PHP and extract them:

tar xf php-*
cd php-*/

Then, configure PHP for your platform:

Linux

./configure \
    --enable-embed \
    --enable-zts \
    --disable-zend-signals \
    --enable-zend-max-execution-timers

Finally, compile and install PHP:

make -j$(nproc)
sudo make install

Mac

Use the Homebrew package manager to install libiconv, bison, re2c and pkg-config:

brew install libiconv bison re2c pkg-config
echo 'export PATH="/opt/homebrew/opt/bison/bin:$PATH"' >> ~/.zshrc

Then run the configure script:

./configure \
    --enable-embed=static \
    --enable-zts \
    --disable-zend-signals \
    --disable-opcache-jit \
    --enable-static \
    --enable-shared=no \
    --with-iconv=/opt/homebrew/opt/libiconv/

These flags are required, but you can add other flags (e.g. extra extensions) if needed.

Finally, compile and install PHP:

make -j$(sysctl -n hw.logicalcpu)
sudo make install

Compile the Go App

You can now use the Go library and compile our Caddy build:

curl -L https://github.com/dunglas/frankenphp/archive/refs/heads/main.tar.gz | tar xz
cd frankenphp-main/caddy/frankenphp
CGO_CFLAGS=$(php-config --includes) CGO_LDFLAGS="$(php-config --ldflags) $(php-config --libs)" go build

Using xcaddy

Alternatively, use xcaddy to compile FrankenPHP with custom Caddy modules:

CGO_ENABLED=1 \
XCADDY_GO_BUILD_FLAGS="-ldflags '-w -s'" \
xcaddy build \
    --output frankenphp \
    --with github.com/dunglas/frankenphp/caddy \
    --with github.com/dunglas/mercure/caddy \
    --with github.com/dunglas/vulcain/caddy
    # Add extra Caddy modules here

[!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\'"' (change the value of the stack size according to your app needs).