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.

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:

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

Finally, compile and install PHP:

make -j$(nproc)
sudo make install

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

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 x
cd frankenphp-main/caddy/frankenphp
CGO_CFLAGS=$(php-config --includes) CGO_LDFLAGS="$(php-config --ldflags) $(php-config --libs)" go build

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).