PhpStorm + Xdebug

This guide shows how to debug a BEAR.Sunday application created from BEAR.Skeleton with Docker, PhpStorm, and Xdebug.

The Docker side provides PHP and Xdebug. PhpStorm still needs one-time IDE settings: a Docker Compose interpreter, a PHP server name, path mapping, and a PHP Script debug configuration.

Required values

The server name is important. It must be the same in Docker and PhpStorm.

Start Docker

Start the application container:

docker compose up -d

Check normal CLI execution before debugging:

docker compose exec -T app php bin/page.php get /

Expected output:

200 OK
Content-Type: application/hal+json

Configure the Docker Compose interpreter

Use the project compose.yaml and the app service.

Configure the PHP server

Use these values:

• Name: BEAR.Skeleton
• Host: localhost
• Port: 8080
• Debugger: Xdebug
• Use path mappings: enabled
• Project root on the host: your local project directory
• Absolute path on the server: /app

Create a PHP Script debug configuration

Create a PHP Script run configuration.

Use these values:

• Name: page get /
• File: bin/page.php
• Arguments: get /
• Interpreter: the Docker Compose interpreter
• Server: BEAR.Skeleton

Debug with the bug button

Set a breakpoint in bin/page.php, then click the bug button for the page get / configuration.

A successful session stops at the breakpoint.

Resume execution. The console should finish with exit code 0.

Xdebug mode policy

Do not fix XDEBUG_MODE=off in Dockerfile or compose.yaml.

Use this default container-side policy:

xdebug.mode=develop
xdebug.start_with_request=trigger
xdebug.client_host=host.docker.internal
xdebug.client_port=9003

With this setup, normal execution does not start a debug session. When you click PhpStorm’s bug button, PhpStorm starts the script with options such as:

-dxdebug.mode=debug -dxdebug.client_port=9003 -dxdebug.client_host=host.docker.internal

This keeps normal CLI execution light while allowing the IDE to enable debugging for the current session.

Troubleshooting

PhpStorm says xdebug.remote_host may be wrong

This warning can be misleading. With Xdebug 3, first check these items:

• XDEBUG_MODE=off is not fixed in Docker.
• The PhpStorm server name is exactly BEAR.Skeleton.
• PHP_IDE_CONFIG=serverName=BEAR.Skeleton is set in Docker.
• The project root is mapped to /app.
• PhpStorm is listening on port 9003.

The breakpoint is not hit

Run this command and check that the application works without the debugger:

docker compose exec -T app php bin/page.php get /

Then check the debug command shown in PhpStorm’s console. It should include -dxdebug.mode=debug.

Normal execution is slow

Xdebug affects performance when debug mode is active. Keep the container default at xdebug.mode=develop and let PhpStorm enable debug only for a debug session.