GeezerVison

name: FrankenPHP

on:

push:

branches:

- main

pull_request:

jobs:

worker-mode:

runs-on: ubuntu-latest

name: "Worker mode"

timeout-minutes: 20

steps:

- name: Checkout

uses: actions/checkout@v7

- name: Worker-mode regression tests

run: tests/frankenphp/run-worker-tests.sh

env:

HTTP_PORT: 8080

DBGP_PORT: 9003

`xdebug_info()` says `OPcache is bypassed for this request` when this applies, so you can tell this apart from OPcache being off

for some other reason.

The near-zero overhead described above relies on deciding per request whether to compile with debugging information. FrankenPHP

worker mode cannot work that way: one worker serves many requests from code it compiled once, before it can know that a later

request will ask to be debugged. PHP Debugger therefore compiles everything with debugging information for the whole worker

process, and every request pays for the per-statement dispatch that comes with it — including requests with no debugging trigger.

The dispatch bails out immediately when no client is connected, so the cost is small, but it is not the "you don't pay for what

you don't use" behaviour you get on CLI and PHP-FPM.

This applies as soon as the extension is loaded with `mode=debug`, whether or not you ever attach an IDE. Setting the mode off

(`php_debugger.mode=off`, `xdebug.mode=off`, or the `XDEBUG_MODE=off` environment variable) skips the instrumentation entirely, so

a worker you are not planning to debug runs at full speed.

static bool xdebug_frame_belongs_to_call(function_stack_entry *fse, zend_execute_data *execute_data)

{

if (XDEBUG_VECTOR_COUNT(XG_BASE(stack)) == 0 || !fse) {

function_stack_entry *fse = XDEBUG_VECTOR_TAIL(XG_BASE(stack));

zval *return_value = NULL;

if (UNEXPECTED(XG_BASE(observer_can_activate_mid_call)) && !xdebug_frame_belongs_to_call(fse, execute_data)) {

if (!xdebug_frame_belongs_to_call(fse, execute_data)) {

return;

}

fse = XDEBUG_VECTOR_TAIL(XG_BASE(stack));

if (UNEXPECTED(XG_BASE(observer_can_activate_mid_call)) && !xdebug_frame_belongs_to_call(fse, execute_data)) {

if (!xdebug_frame_belongs_to_call(fse, execute_data)) {

return;

}

if (!XG_BASE(observer_active) && !xdebug_frankenphp_in_use()) {

return (zend_observer_fcall_handlers){NULL, NULL};

}

XG_BASE(observer_active) = true;

XG_BASE(opcache_disabled_for_request) = false;

/* Can the observer go from inactive to active while a call is already

XG_BASE(observer_can_activate_mid_call) =

xdebug_frankenphp_in_use() || XINI_DBG(on_demand_debugging_enabled);

{

zend_string *fiber_key = create_key_for_fiber(EG(main_fiber_context));

zend_bool statement_handler_enabled;

zend_bool early_connection;

zend_bool opcache_disabled_for_request;

zend_bool observer_can_activate_mid_call;

/* in-execution checking */

zend_bool in_execution;

if (xdebug_lib_start_with_request() || has_debug_trigger()) {

XG_DBG(context).do_connect_to_client = 1;

XG_BASE(observer_active) = 1;

void xdebug_frankenphp_minit(void)

{

/* Note: at MINIT time on the FrankenPHP SAPI, sapi_module.name is set

/* FrankenPHP's worker loop dispatches through sapi_module.activate and

if (!sapi_module.name || strcmp(sapi_module.name, "frankenphp") != 0) {

return;

}

CG(compiler_options) |= ZEND_COMPILE_EXTENDED_STMT;

}

zend_string *key = zend_string_init(ZEND_STRL("opcache.optimization_level"), 1);

zend_string *value = zend_string_init(ZEND_STRL("0"), 1);

zend_alter_ini_entry(key, value, ZEND_INI_SYSTEM, ZEND_INI_STAGE_STARTUP);

/* ZEND_INI_SYSTEM is the part that matters: the directive is

zend_alter_ini_entry(key, value, ZEND_INI_SYSTEM, ZEND_INI_STAGE_RUNTIME);

zend_string_release(key);

zend_string_release(value);

`run-worker-tests.sh` is the automated check; the rest of this document is the

manual procedure for working on the SAPI hooks by hand with an IDE.

tests/frankenphp/run-worker-tests.sh

Builds the image, runs a worker with `dbgp_listener.py` standing in for an

IDE, and asserts that breakpoints still fire after the worker has served

requests with no debugger attached — without that, a single un-debugged

request stops every later request from breaking. It also checks that the

reported stack includes the calling function, and repeats the trigger on a

fresh worker as a control.

Overrides: `IMAGE`, `HTTP_PORT` (default 8081), `DBGP_PORT` (default 9004,

because an IDE usually holds 9003), `POISON_REQUESTS`, `TRIGGER_REQUESTS`,

`SKIP_BUILD=1` to reuse an image you already built.

The script exits non-zero with the listener transcript on failure. It is run

by `.github/workflows/frankenphp.yml` on every push and pull request, and it

was verified to fail (0/5 breakpoints) against the code from before the worker

-mode fix, so a regression is caught rather than silently passing.

`dbgp_listener.py` can also be pointed at a different breakpoint for ad-hoc

work — `DBGP_BREAKPOINT="-t call -m workload"` exercises the observer's begin

handler instead of the statement handler that serves line breakpoints.

Smoke-tests the SAPI activate/deactivate hooks added in `src/debugger/frankenphp.c`.

If even that doesn't fire, the connection isn't being made — see the

**Troubleshooting** section.

Open `tests/frankenphp/app/index.php` in your IDE and put a breakpoint on

the `$pid = getmypid();` line.

curl -s http://localhost:8080/

Returns immediately. The IDE must not pause. `tail -f /tmp/xdebug.log`

inside the container shows `Trigger value ... not found, so not activating`.

curl -s -b 'XDEBUG_SESSION=PHPSTORM' http://localhost:8080/

PhpStorm pauses on the breakpoint. Resume (F9) — request completes.

for i in 1 2 3; do

curl -s -b 'XDEBUG_SESSION=PHPSTORM' http://localhost:8080/

The `pid=` field in every response stays the same (one worker process), but

the IDE pauses on **every** request. This proves the per-request

`sapi_module.activate` reset is working — without it, only the first

request would be debuggable.

The script already covers the basics: a request without a trigger must not

pause, a request with one must, and repeated debug requests against the same

worker must all pause. What is left needs either a real IDE or a clean

shutdown, so it stays a hand check.

This is the scenario that caught the original bug:

Open `tests/frankenphp/app/index.php` in your IDE, then:

1. Set a breakpoint on **line 4** (`$pid = getmypid();`).

2. `curl -b 'XDEBUG_SESSION=PHPSTORM' http://localhost:8080/` → pauses on

PhpStorm pauses on line 5.

**Without the poll, the IDE's queued `breakpoint_set` is silently

ignored and the new breakpoint is never honored** — exactly the

symptom this PR fixes.

ignored and the new breakpoint is never honored.**

docker exec $(docker ps -qf ancestor=php-debugger-frankenphp) \

import os

import socket

import sys

import threading

import time

HOST = "0.0.0.0"

PORT = 9003

PORT = int(os.environ.get("DBGP_PORT", "9003"))

BREAKPOINT = os.environ.get("DBGP_BREAKPOINT", "-t line -f file:///app/lib.php -n 4")

def read_packet(sock):

"""Read one DBGp packet: length\\0xml\\0."""

print(f"<<< init: {init}", flush=True)

txn = 1

send(conn, f"breakpoint_set -i {txn} -t line -f file:///app/lib.php -n 4")

send(conn, f"breakpoint_set -i {txn} {BREAKPOINT}")

txn += 1

resp = read_packet(conn)

print(f"<<< {resp}", flush=True)

print(f"<<< {resp}", flush=True)

if "status=\"break\"" in resp:

print(f"!!! BREAKPOINT HIT in [{label}]", flush=True)

# The stack is built by the observer handlers, which are a

# separate mechanism from the statement handler that fires the

# breakpoint. Ask for it so a regression in either shows up.

send(conn, f"stack_get -i {txn}")

txn += 1

stack = read_packet(conn)

print(f"<<< {stack}", flush=True)

if stack and 'where="workload"' in stack:

print(f"!!! STACK OK in [{label}]", flush=True)

send(conn, f"run -i {txn}")

txn += 1

elif "status=\"stopping\"" in resp or "status=\"stopped\"" in resp: