Powered by
Known Issues

Known Issues

# Fibers

Calling PHP functions and language constructs that themselves call cgo in Fibers is known to cause crashes.

This issue is being worked on by the Go project.

In the meantime, one solution is not to use constructs (like echo) and functions (like header()) that delegate to Go from inside Fibers.

This code will likely crash because it uses echo in the Fiber:

$fiber = new Fiber(function() {
    echo 'In the Fiber'.PHP_EOL;
    echo 'Still inside'.PHP_EOL;
});
$fiber->start();

Instead, return the value from the Fiber and use it outside:

$fiber = new Fiber(function() {
    Fiber::suspend('In the Fiber'.PHP_EOL));
    Fiber::suspend('Still inside'.PHP_EOL));
});
echo $fiber->start();
echo $fiber->resume();
$fiber->resume();

# Unsupported PHP Extensions

The following extensions are known not to be compatible with FrankenPHP:

NameReasonAlternatives
imapNot thread-safejavanile/php-imap2, webklex/php-imap

# Buggy PHP Extensions

The following extensions have known bugs and unexpected behaviors when used with FrankenPHP:

NameProblem
XDebugXDebug may crash, or hang. This problem is being tracked by XDebug.
Datadog PHP TracerThe Datadog tracer can cause crashes. This has been reported to DataDog.
TidewaysIn worker mode, the Tideways extension prevents worker scripts to finish properly or consumes 100% of the CPU. This has been reported to Tideways.

# get_browser

The get_browser() function seems to perform badly after a while. A workaround is to cache (e.g. with APCu) the results per User Agent, as they are static.

# Standalone Binary and Alpine-based Docker Images

The standalone binary and Alpine-based docker images (dunglas/frankenphp:*-alpine) use musl libc instead of glibc and friends, to keep a smaller binary size. This may lead to some compatibility issues. In particular, the glob flag GLOB_BRACE is not available

# Using https://127.0.0.1 with Docker

By default, FrankenPHP generates a TLS certificate for localhost. It’s the easiest and recommended option for local development.

If you really want to use 127.0.0.1 as a host instead, it’s possible to configure it to generate a certificate for it by setting the server name to 127.0.0.1.

Unfortunately, this is not enough when using Docker because of its networking system. You will get a TLS error similar to curl: (35) LibreSSL/3.3.6: error:1404B438:SSL routines:ST_CONNECT:tlsv1 alert internal error.

If you’re using Linux, a solution is to use the host networking driver:

docker run \
    -e SERVER_NAME="127.0.0.1" \
    -v $PWD:/app/public \
    --network host \
    dunglas/frankenphp

The host networking driver isn’t supported on Mac and Windows. On these platforms, you will have to guess the IP address of the container and include it in the server names.

Run the docker network inspect bridge and look at the Containers key to identify the last currently assigned IP address under the IPv4Address key, and increment it by one. If no container is running, the first assigned IP address is usually 172.17.0.2.

Then, include this in the SERVER_NAME environment variable:

docker run \
    -e SERVER_NAME="127.0.0.1, 172.17.0.3" \
    -v $PWD:/app/public \
    -p 80:80 -p 443:443 -p 443:443/udp \
    dunglas/frankenphp

Caution

Be sure to replace 172.17.0.3 with the IP that will be assigned to your container.

You should now be able to access https://127.0.0.1 from the host machine.

If that’s not the case, start FrankenPHP in debug mode to try to figure out the problem:

docker run \
    -e CADDY_GLOBAL_OPTIONS="debug"
    -e SERVER_NAME="127.0.0.1" \
    -v $PWD:/app/public \
    -p 80:80 -p 443:443 -p 443:443/udp \
    dunglas/frankenphp

# Composer Scripts Referencing @php

Composer scripts may want to execute a PHP binary for some tasks, e.g. in a Laravel project to run @php artisan package:discover --ansi. This currently fails for two reasons:

  • Composer does not know how to call the FrankenPHP binary;
  • Composer may add PHP settings using the -d flag in the command, which FrankenPHP does not yet support.

As a workaround, we can create a shell script in /usr/local/bin/php which strips the unsupported parameters and then calls FrankenPHP:

#!/bin/sh

# iterate over $@. if the current argument is -d, remove the argument and the next one
for i in "$@"
do
    if [ "$i" = "-d" ]; then
        shift
        shift
    fi
done

/usr/local/bin/frankenphp php-cli "$@"
Edit this page