Add Documentation for Profiling Code in FrankenPHP to Enhance Developer Experience

Describe you feature request

Hello,

As a new user of FrankenPHP, I’ve encountered some performance discrepancies compared to my previous classic Nginx/PHP stack. The source of these differences isn’t immediately apparent, so I attempted to profile the execution to pinpoint potential bottlenecks.

In the past, I’ve used php-spx, which is straightforward to set up and provides a fantastic web UI for navigating flamegraphs.

However, I wasn’t able to make the SPX web UI available in my FrankenPHP setup, even though profiling through CI works correctly. This limitation seems to stem from a specific requirement in php-spx (@NoiseByNorthwest friendly ping FYI) :

N.B.: http://localhost/ must be served by a PHP script through standard web server features like directory index or URL rewriting. The PHP script will, however, not be executed—SPX intercepts and disables its execution to serve its content instead.

Here’s my current FrankenPHP's Docker configuration modifications for reproducing the issue:

# Development FrankenPHP image
FROM frankenphp_base AS frankenphp_dev

ENV APP_ENV=dev XDEBUG_MODE=off

RUN mv "$PHP_INI_DIR/php.ini-development" "$PHP_INI_DIR/php.ini"

RUN set -eux; \
    install-php-extensions \
        xdebug \
    ;

COPY --link .docker/conf.d/20-app.dev.ini $PHP_INI_DIR/app.conf.d/

RUN apt-get update && apt-get install -y zlib1g-dev \
    && git clone --depth=1 https://github.com/NoiseByNorthwest/php-spx.git /usr/lib/php-spx \
    && cd /usr/lib/php-spx \
    && phpize \
    && ./configure \
    && make \
    && make install \
    && rm -rf /var/lib/apt/lists/*

CMD [ "frankenphp", "run", "--config", "/etc/caddy/Caddyfile", "--watch" ]

For example, running SPX_ENABLED=1 SPX_FP_LIVE=1 php bin/console inside the container produces this output:

Given these challenges, I wanted to ask the community:

1. What’s the recommended approach for profiling PHP applications with FrankenPHP?
2. Are there any known workarounds or alternative tools for integrating SPX’s web UI in this context?

If a preferred method exists, I’d suggest documenting it in the official guides to help new users troubleshoot migration and performance optimization issues more effectively. A tool that supports both PHP and underlying Go/PHP source traces would be ideal.

While paid tools like Blackfire or Tideways are excellent, I believe showcasing an open-source solution in the documentation would greatly benefit the community.

Thanks for this great project and your insigths on this topic !

Start with the Dockerfile configuration and the php bin/console profiling command shown in the issue, then review FrankenPHP’s official guides for profiling options. Determine which PHP and Go profiling workflows are supported and whether the SPX web UI has a documented workaround. Done means the guides explain a reproducible profiling setup, alternatives, and the relevant limitations.