Debugging
You can use RoadRunner scripts with xDebug extension. In order to enable configure your IDE to accept remote connections.
XDebug for RoadRunner installed on your system

To activate xDebug make sure to set the xdebug.mode=debug
in your php.ini
.
To enable xDebug in your application make sure to set ENV variable XDEBUG_SESSION
:
rpc:
listen: tcp://127.0.0.1:6001
server:
command: "php worker.php"
env:
- XDEBUG_SESSION: 1
http:
address: "0.0.0.0:8080"
pool:
num_workers: 1
debug: true
Please, keep in mind this guide: xdebug3.
You should be able to use breakpoints and view state at this point.
PhpStorm notes
export PHP_IDE_CONFIG="serverName=octane-app.test"
export XDEBUG_SESSION="mode=debug start_with_request=yes client_host=127.0.0.1 client_port=9003 idekey=PHPSTORM"
php -dvariables_order=EGPCS artisan octane:start --max-requests=250 --server=roadrunner --port=8000 --rpc-port=6001 --watch --workers=1
XDebug for RoadRunner installed on Docker
First, create a docker-compose.yml
file in your project root, or copy the environment
and extra_hosts
sections into your existing docker-compose.yml
:
services:
api:
build:
context: ./
dockerfile: Dockerfile
container_name: projectName-api
command: rr serve -c .rr.yaml
tty: true
ports:
- "8080:8080"
volumes:
- ./api:/app
networks:
- default
environment:
- PHP_IDE_CONFIG=serverName=docker
extra_hosts:
- "host.docker.internal:host-gateway"
Next, create a .rr.yaml
file in your project root or copy the following content:
rpc:
listen: 'tcp://127.0.0.1:6001'
http:
address: '0.0.0.0:8080'
middleware:
- gzip
- static
static:
dir: public
forbid:
- .php
- .htaccess
pool:
debug: true
num_workers: 1
supervisor:
max_worker_memory: 100
server:
command: 'php app.php'
relay: pipes
env:
- XDEBUG_SESSION: 1
metrics:
address: '127.0.0.1:2112'
Next create a Dockerfile
file in your project root or copy the following content:
FROM ghcr.io/roadrunner-server/roadrunner:2025.1.1 AS roadrunner
FROM php:8.4-cli-alpine3.21
# change version to latest if you want to use the latest version of xDebug, see https://xdebug.org
ENV XDEBUG_VERSION=3.4.4
RUN apk add --no-cache autoconf g++ make postgresql-dev coreutils --update linux-headers \
&& pecl install xdebug-$XDEBUG_VERSION \
&& rm -rf /tmp/pear \
&& docker-php-ext-configure pgsql --with-pgsql=/usr/local/pgsql \
&& docker-php-ext-install pdo_pgsql sockets \
&& docker-php-ext-enable xdebug \
&& apk del linux-headers make g++ autoconf
RUN mv $PHP_INI_DIR/php.ini-development $PHP_INI_DIR/php.ini
COPY xdebug.ini /usr/local/etc/php/conf.d/xdebug.ini
RUN curl -sS https://getcomposer.org/installer | php \
&& mv composer.phar /usr/local/bin/composer \
&& chmod +x /usr/local/bin/composer
RUN addgroup -g 1000 app && adduser -u 1000 -G app -s /bin/sh -D app
WORKDIR /app
COPY --from=roadrunner /usr/bin/rr /usr/local/bin/rr
RUN chown app:app /usr/local/bin/rr && chmod +x /usr/local/bin/rr
USER app
Important: make sure to change the XDEBUG_VERSION
to the version you want to use, see xdebug.org, and note that the example container is run as the app
user.
Next create a xdebug.ini
file in your project root or copy the following content:
xdebug.mode=develop,debug
xdebug.start_with_request=yes
xdebug.discover_client_host=0
xdebug.client_host=host.docker.internal
xdebug.client_port=9003
xdebug.log=/dev/stdout
xdebug.log_level=0
Next, you need to change the settings in your IDE so it can accept remote connections. For example, in PhpStorm you can do it by going to PHP > Debug
and set the following options:

Next, you need to create a Server entry in your IDE. For example, in PhpStorm you can do it by going to PHP > Servers
and set the following options:

Also, please check the Docker
settings in your IDE. For example, in PhpStorm you can do it by going to Build, Execution, Deployment > Docker
and set the following options:

Jobs debugging
Prerequisites
XDebug 3 installed and properly configured.
Number of jobs workers set to
1
withjobs.pool.num_workers
configuration option in.rr.yaml
.
Debug process
If you have any active XDebug listener while starting RoadRunner with XDebug enabled — disable it. This will prevent false-positive debug session.
Once RoadRunner starts all workers, enable XDebug listener and reset jobs workers with:
./rr reset jobs
Now you should see debug session started:
Step over to some place where job task is being resolved with
$consumer->waitTask()
.As soon as you reach it, debugger stops but session will still be active.
Trigger task consumption with either an HTTP request or a console command (depending on how your application works). and continue to debug job worker as usual within active session started before.
You can continue to debug jobs as long as debug session active.
If connections session broken or timed out, you can repeat instruction above to reestablish connection by resetting jobs workers.
Last updated
Was this helpful?