Trigger Xdebug with cookie XDEBUG_SESSION

[andrei-piarainc]

I've used to trigger debugging on demand, using XDEBUG_SESSION cookie that I set in request with browser extension. So I can start and stop debugging mode any time, for any specific request. This approach works fine when I use php artisan serve command to start my Laravel application. But when I switched to Octane with RoadRunner php artisan octane:start or php artisan octane:roadrunner I can not use this anymore. The only way that is working - set env variable XDEBUG_SESSION='1', then Xdebug gets activated. But it activates for the whole roadrunner-worker process, and stays active all the time while process alive, processing all the requests not only specific ones that I wish to debug.

I was unable to activate debugging with a cookie, cookie just seemed to be ignored. I thought it is Octane, who probably filters, blocks or clears request cookies, but I've started RoadRunner directly with rr -c .rr.yaml and result is the same - cookie is ignored. I've noticed that $_COOKIE array is empty when request gets processed in roadrunner-worker, so I've tried to set XDEBUG_SESSION cookie directly in $_COOKIE array as soon as I get control in roadrunner-worker.php file, also I've found a place where worker gets payload of each request in waitRequest() method of HttpWorker.php file and set cookie in $_COOKIE array immediately after getting payload to make sure every request will have it. But this does not help. I've checked in Xdebug source code, that it reads XDEBUG_SESSION from env, url, and $_COOKIE array, so I think extension code just had no chance to run when RoadRunner start processing new request.

So the question is, is it possible to make RoadRunner pass control to Xdebug extension on each request processing, not only on worker startup? Or, maybe there is some easy place in RoadRunner's code where I could add such call for extensions (Xdebug) and make a build of RoadRunner with this feature for myself. Alternatively, could you please suggest some other way to trigger Xdebug on RoadRunner for specific requests using cookie?

Thanks!

[rustatian]

Hey @andrei-piarainc 👋🏻
Could you please post your .rr.yaml file and ./rr --version output?

[andrei-piarainc]

Hi @rustatian
Sure.

Version:

# ./rr --version
rr version 2023.2.1 (build time: 2023-07-27T17:13:10+0000, go1.20.6), OS: linux, arch: amd64

.rr.yaml:

version: '3'
rpc:
    listen: 'tcp://127.0.0.1:6001'
server:
    command: '/usr/bin/php8.2 /var/www/html/vendor/bin/roadrunner-worker'
    relay: pipes
    env:
      - APP_ENV: "local"
      - APP_BASE_PATH: "/var/www/html"
      - LARAVEL_OCTANE: "1"
      - XDEBUG_CONFIG: "client_host=host.docker.internal"
      - XDEBUG_MODE: "develop,debug"
      - LARAVEL_SAIL: "1"
      - SUPERVISOR_GROUP_NAME: "php"
      - SHLVL: "0"
      - HOME: "/root"
      - LC_CTYPE: "C.UTF-8"
      - SHELL_VERBOSITY: "0"
      - PATH: "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
      - WWWUSER: "1000"
      - SUPERVISOR_ENABLED: "1"
      - DEBIAN_FRONTEND: "noninteractive"
      - SUPERVISOR_PROCESS_NAME: "php"
      - PWD: "/var/www/html"
      - TZ: "UTC"
http:
    address: '0.0.0.0:8000'
    middleware:
        - gzip
        - static
    static:
        dir: public
        forbid:
            - .php
            - .htaccess
    pool:
        num_workers: 1
        supervisor:
            max_worker_memory: 100
jobs:
    pool:
        num_workers: 2
        max_worker_memory: 100
    consume: {  }
kv:
    local:
        driver: memory
        config:
            interval: 60
metrics:
    address: '127.0.0.1:2112'

Also some values got overwritten by command in supervisord.conf of Laravel Sail docker image:
(I've just checked what Octane normally sends to RoadRunner and tried to do similar)

[program:php]
# command=/usr/bin/php -d variables_order=EGPCS /var/www/html/artisan serve --host=0.0.0.0 --port=80
# command=/usr/bin/php -d variables_order=EGPCS /var/www/html/artisan octane:start --workers=1 --server=roadrunner --host=0.0.0.0 --rpc-port=6001 --port=80
command=/var/www/html/rr -c /var/www/html/.rr.yaml -o version=3 -o http.address=0.0.0.0:80 -o server.command='/usr/bin/php8.2 /var/www/html/vendor/bin/roadrunner-worker' -o http.pool.num_workers=1 -o http.pool.max_jobs=500 -o rpc.listen=tcp://0.0.0.0:6001 -o http.pool.supervisor.exec_ttl=300s -o http.static.dir=/var/www/html/public -o http.middleware=static -o logs.mode=production -o logs.level=debug -o logs.output=stdout -o logs.encoding=json serve
user=sail
environment=LARAVEL_SAIL="1"
stdout_logfile=/dev/stdout
stdout_logfile_maxbytes=0
stderr_logfile=/dev/stderr
stderr_logfile_maxbytes=0

In Sail docker-compose.yml I have:

laravel.test:
    build:
        context: ./docker/8.2
        dockerfile: Dockerfile
        args:
            WWWGROUP: '${WWWGROUP}'
    image: sail-8.2/app
    extra_hosts:
        - 'host.docker.internal:host-gateway'
    ports:
        - '${APP_PORT:-80}:80'
        - '${VITE_PORT:-5173}:${VITE_PORT:-5173}'
    environment:
        WWWUSER: '${WWWUSER}'
        LARAVEL_SAIL: 1
        XDEBUG_MODE: '${SAIL_XDEBUG_MODE:-off}'
        XDEBUG_CONFIG: '${SAIL_XDEBUG_CONFIG:-client_host=host.docker.internal}'
        # XDEBUG_SESSION: '1'
        PHP_IDE_CONFIG: 'serverName=laravel.test'
        IGNITION_LOCAL_SITES_PATH: '${PWD}'
    volumes:
        - '.:/var/www/html'
    networks:
        - sail
    depends_on:
        - mysql
        - redis
        - minio

In .env:

SAIL_XDEBUG_MODE="develop,debug"
SAIL_XDEBUG_CONFIG="client_host=host.docker.internal"

[rustatian]

Ok, thanks 👍🏻
As far as I can see, you don't have the debug:true option in your configuration. You can read more about it here: https://roadrunner.dev/docs/php-debugging/current/en
Also, I'm not sure if it's possible to set this option in Octane's configuration options, since RR support in Octane is very limited.

[andrei-piarainc]

Thanks, I've already tried set debug:true in .rr.yaml config, like this:

http:
   pool:
      debug: true

It works, even with Octane (if I set XDEBUG_SESSION: '1' in env). But it does something different - it starts creating new worker for each request. Which may be helpful in some cases, but what I'm trying to achieve - triggering debug mode for only particular requests that I wish to debug, not for all requests.

Also application may behave very different in RR debug:true mode, because it gets bootstrapped on each request, and when going back into production with debug:false some structures will stay in memory between requests etc. means that some issues that are not reproducible in debug mode may affect app in production and vice versa.

[rustatian]

it starts creating new worker for each request.

Yes, you're right. This is done because you might be actively changing the code as you develop, and on each request you'll get the latest version of your changes inside the worker. I'm not quite sure about XDEBUG, but I think you're talking about conditional breakpoints, which is an xdebug feature, not the application you're trying to debug.

Also application may behave very different in RR debug:true mode, because it gets bootstrapped on each request, and when going back into production with debug:false some structures will stay in memory between requests etc. means that some issues that are not reproducible in debug mode may affect app in production and vice versa.

In debug mode, the worker is destroyed after sending a response to the user. So it's not possible to keep a state between requests in this mode.

[andrei-piarainc]

I'm not quite sure about XDEBUG, but I think you're talking about conditional breakpoints, which is an xdebug feature, not the application you're trying to debug.

This is not really about conditional breakpoints feature, it's about activating/deactivating the whole debug session. Xdebug is PHP extension, as far as I know it gets registered in PHP-engine as Zend extension and as a regular PHP extension (module) as well. Being registered as Zend extension makes PHP engine to call some extension's methods ("hooks") in appropriate moments. E.g. PHP-engine gives control to extension (calls it) during loading of new application script. And during this call Xdebug checks for env variable XDEBUG_SESSION and activates debugger if variable is present. That part is working OK with RoadRunner. But also, built-in PHP server calls extension's methods when start processing new request. During this call Xdebug have a chance to check for XDEBUG_SESSION cookie or request parameter, and activate debug session if cookie/parameter is present. That part is not working with RoadRunner. Unlike built-in PHP server, RR does not calls extensions on receiving new requests, at least I have not found a way to make RR do it.

When I enable Xdebug log in php.ini

[xdebug]
xdebug.log = /tmp/xdebug.log
xdebug.log_level = 7

I get following results. For built-in PHP server:

[16] Log opened at 2023-08-02 15:39:10.892191
[16] [Config] INFO: Trigger value for 'XDEBUG_TRIGGER' not found, falling back to 'XDEBUG_SESSION'
[16] [Config] INFO: Trigger value for 'XDEBUG_SESSION' not found, so not activating
[19] Log opened at 2023-08-02 15:40:03.776428
[19] [Config] INFO: Trigger value for 'XDEBUG_TRIGGER' not found, falling back to 'XDEBUG_SESSION'
[19] [Config] INFO: Trigger value for 'XDEBUG_SESSION' not found, so not activating
[19] [Config] INFO: Trigger value for 'XDEBUG_TRIGGER' not found, falling back to 'XDEBUG_SESSION'
[19] [Config] INFO: Trigger value for 'XDEBUG_SESSION' not found, so not activating
[19] Log closed at 2023-08-02 15:40:11.510332

[19] Log opened at 2023-08-02 15:40:11.607690
[19] [Config] INFO: Trigger value for 'XDEBUG_TRIGGER' not found, falling back to 'XDEBUG_SESSION'
[19] [Config] INFO: Trigger value for 'XDEBUG_SESSION' not found, so not activating
[19] Log closed at 2023-08-02 15:40:11.622306

[19] Log opened at 2023-08-02 15:40:11.632064
[19] [Config] INFO: Trigger value for 'XDEBUG_TRIGGER' not found, falling back to 'XDEBUG_SESSION'
[19] [Config] INFO: Trigger value for 'XDEBUG_SESSION' not found, so not activating
[19] Log closed at 2023-08-02 15:40:11.634878

[19] Log opened at 2023-08-02 15:40:11.771718
[19] [Config] INFO: Trigger value for 'XDEBUG_TRIGGER' not found, falling back to 'XDEBUG_SESSION'
[19] [Config] INFO: Trigger value for 'XDEBUG_SESSION' not found, so not activating
[19] Log closed at 2023-08-02 15:40:11.773287

First record appeared after application start (Xdebug extension was called by PHP-engine on script load). Consequent records appeared after each request I've sent to server (actually just refreshing the page in browser). I've not set XDEBUG_SESSION env variable and XDEBUG_SESSION cookie this time, so Xdebug just checks and exits.

For RoadRunner:

[25] Log opened at 2023-08-02 14:59:17.670961
[25] [Config] INFO: Trigger value for 'XDEBUG_TRIGGER' not found, falling back to 'XDEBUG_SESSION'
[25] [Config] INFO: Trigger value for 'XDEBUG_SESSION' not found, so not activating
[24] Log opened at 2023-08-02 14:59:17.671236
[24] [Config] INFO: Trigger value for 'XDEBUG_TRIGGER' not found, falling back to 'XDEBUG_SESSION'
[24] [Config] INFO: Trigger value for 'XDEBUG_SESSION' not found, so not activating
[29] Log opened at 2023-08-02 14:59:18.633299
[29] [Config] INFO: Trigger value for 'XDEBUG_TRIGGER' not found, falling back to 'XDEBUG_SESSION'
[29] [Config] INFO: Trigger value for 'XDEBUG_SESSION' not found, so not activating

Here we can see only three records, Xdebug was called by PHP-engine on loading of each roadrunner-worker script (I had one http- and two job-workers). And there is no record on requests which I've sent (refreshing the same browser page), which means that Xdebug extension was not called by RR.

As a bottom line, it starts looking more like feature-request for RoadRunner, if I do not miss something in configuration of course ;) It would be nice if RR called extensions (registered in PHP-engine) on each new request, like built-in PHP server does. And that way become more like drop-in replacement for it. I'm not sure if there is a demand for that, probably only debuggers and profilers may need it.

Talking about Xdebug, this feature will allow not only activate debug session for particular requests, but also activate/deactivate profiling and function tracing, depending on cookie value. Like described here:
https://xdebug.org/docs/step_debug#manual-init
https://xdebug.org/docs/profiler
https://xdebug.org/docs/trace

Better explanation of PHP extensions is here:
https://www.phpinternalsbook.com/php7/extensions_design/zend_extensions.html

[rustatian]

Nice, thanks for the detailed description @andrei-piarainc 👍🏻

Currently it is not possible to call some PHP internal things from Golang. I don't like the idea of integrating CGO into the RR engine, as this would require significant effort to support all platforms supported by RR.

However, I know about the php-src internals and am working on a SAPI-RR integration, but in Rust, which is a lower level language compared to Golang. This will allow us to create a bridge to the PHP engine and call any methods we want 😃

[nickchomey]

For what it's worth, i would require the same functionality (remote/browser trigger of xdebug) in order to use roadrunner. So, I greatly look forward to the rust sapi version!