Add Documentation for Profiling Code in FrankenPHP to Enhance Developer Experience

[tigitz]

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 !

[withinboredom]

I just use xdebug's profiling tools (which works fine), I've never heard of spx before.

I have no idea how spx works, but it looks like an extension. Perhaps it needs to be modified to hook into the frankenphp sapi, or the frankenphp sapi is missing a call that is present in other sapis, and thus it is missing a hook.

[tigitz]

@withinboredom Thanks for your input! I’ll explore this hook idea.

About your use of Xdebug’s profiling, do you typically use XDEBUG_MODE=profile and open the output with KCachegrind? Have you also managed to generate flamegraphs from it? Just curious.

Once I’ve dug deeper, I’ll document my findings and share the necessary Docker setup as a contribution.

[NoiseByNorthwest]

@tigitz see NoiseByNorthwest/php-spx#258

The only known issue is a crash while serving web UI via FrankenPHP, I could investigate it if someone provides an easy to use (docker-based) reproducer.

It is also possible, as a workaround, to use a web UI served by a standard PHP setup (fpm or even the builtin server) as long as it is configured to use the same data directory than your FrankenPHP setup.

[tigitz]

@NoiseByNorthwest Thank you! I'll follow up on the issue you linked regarding the FrankenPHP/php-spx integration.

I'll keep this issue open to document profiling in FrankenPHP.