Skip to content

Using Xdebug with PHPStorm and various updates #1923

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Apr 29, 2024
Merged

Using Xdebug with PHPStorm and various updates #1923

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
7f7c01e
Using Xdebug with PHPStorm and various updates
dunglas Mar 18, 2024
b855d27
Update debugging.md
dunglas Apr 29, 2024
03e34cc
Delete .idea/workspace.xml
dunglas Apr 29, 2024
88a36fd
ZTS support
dunglas Apr 29, 2024
dc87021
linter
dunglas Apr 29, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
27 changes: 15 additions & 12 deletions core/performance.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,12 @@

## Enabling the Built-in HTTP Cache Invalidation System

Exposing a hypermedia API has [many advantages](http://blog.theamazingrando.com/in-band-vs-out-of-band.html). One of them
Exposing a hypermedia API has [many advantages](http://blog.theamazingrando.com/in-band-vs-out-of-band.html). One
is the ability to know exactly which resources are included in HTTP responses created by the API. We used this specificity
to make API Platform apps blazing fast.

When the cache mechanism [is enabled](configuration.md), API Platform collects identifiers of every resource included in
a given HTTP response (including lists, embedded documents and subresources) and returns them in a special HTTP header
a given HTTP response (including lists, embedded documents, and subresources) and returns them in a special HTTP header
called [Cache-Tags](https://support.cloudflare.com/hc/en-us/articles/206596608-How-to-Purge-Cache-Using-Cache-Tags-Enterprise-only-).

A caching [reverse proxy](https://en.wikipedia.org/wiki/Reverse_proxy) supporting cache tags (e.g. Varnish, Cloudflare,
Expand All @@ -16,17 +16,17 @@ This means that after the first request, all subsequent requests will not hit th
from the cache.

When a resource is modified, API Platform takes care of purging all responses containing it in the proxy’s
cache. This ensures that the content served will always be fresh, because the cache is purged in real time. Support for
cache. This ensures that the content served will always be fresh because the cache is purged in real-time. Support for
most specific cases such as the invalidation of collections when a document is added or removed or for relationships and
inverse relations is built-in.

### Integrations

#### Built-in Caddy HTTP cache

The API Platform distribution relies on the [Caddy web server](https://caddyserver.com) which provide an official HTTP cache module called [cache-handler](https://github.com/caddyserver/cache-handler), that is based on [Souin](https://github.com/darkweak/souin).
The API Platform distribution relies on the [Caddy web server](https://caddyserver.com) which provides an official HTTP cache module called [cache-handler](https://github.com/caddyserver/cache-handler), that is based on [Souin](https://github.com/darkweak/souin).

The integration using the cache-handler is quite simple. You juste have to update the `api/Dockerfile` to build your caddy instance with the HTTP cache
The integration using the cache handler is quite simple. You just have to update the `api/Dockerfile` to build your caddy instance with the HTTP cache

```diff
# Versions
Expand Down Expand Up @@ -61,7 +61,7 @@ Update your Caddyfile with the following configuration:
}
}
```
This will tell to caddy to use the HTTP cache and activate the tag based invalidation API. You can refer to the [cache-handler documentation](https://github.com/caddyserver/cache-handler) or the [souin website documentation](https://docs.souin.io) to learn how to configure the HTTP cache server.
This will tell to caddy to use the HTTP cache and activate the tag-based invalidation API. You can refer to the [cache-handler documentation](https://github.com/caddyserver/cache-handler) or the [souin website documentation](https://docs.souin.io) to learn how to configure the HTTP cache server.

Setup the HTTP cache invalidation in your API Platform project
```yaml
Expand Down Expand Up @@ -96,6 +96,7 @@ api_platform:
```

## Configuration

Support for reverse proxies other than Varnish or Caddy with the HTTP cache module can be added by implementing the `ApiPlatform\HttpCache\PurgerInterface`.
Three purgers are available, the built-in caddy http cache purger (`api_platform.http_cache.purger.souin`), the http tags (`api_platform.http_cache.purger.varnish.ban`), the surrogate key implementation
(`api_platform.http_cache.purger.varnish.xkey`). You can specify the implementation using the `purger` configuration node,
Expand Down Expand Up @@ -411,7 +412,7 @@ More details are available on the [pagination documentation](pagination.md#parti

Blackfire.io allows you to monitor the performance of your applications. For more information, visit the [Blackfire.io website](https://blackfire.io/).

To configure Blackfire.io follow these simple steps:
To configure Blackfire.io follow these steps:

1. Add the following to your `compose.override.yaml` file:

Expand Down Expand Up @@ -444,12 +445,14 @@ export BLACKFIRE_SERVER_TOKEN=xxxxxxxxxx
3. Install and configure the Blackfire probe in the app container, by adding the following to your `./Dockerfile`:

```dockerfile
RUN version=$(php -r "echo PHP_MAJOR_VERSION.PHP_MINOR_VERSION;") \
&& curl -A "Docker" -o /tmp/blackfire-probe.tar.gz -D - -L -s https://blackfire.io/api/v1/releases/probe/php/alpine/amd64/$version \
RUN version=$(php -r "echo PHP_MAJOR_VERSION.PHP_MINOR_VERSION.(PHP_ZTS ? '-zts' : '');") \
&& architecture=$(uname -m) \
&& curl -A "Docker" -o /tmp/blackfire-probe.tar.gz -D - -L -s https://blackfire.io/api/v1/releases/probe/php/linux/$architecture/$version \
&& mkdir -p /tmp/blackfire \
&& tar zxpf /tmp/blackfire-probe.tar.gz -C /tmp/blackfire \
&& mv /tmp/blackfire/blackfire-*.so $(php -r "echo ini_get('extension_dir');")/blackfire.so \
&& printf "extension=blackfire.so\nblackfire.agent_socket=tcp://blackfire:8307\n" > $PHP_INI_DIR/conf.d/blackfire.ini
&& tar zxpf /tmp/blackfire-probe.tar.gz -C /tmp/blackfire \
&& mv /tmp/blackfire/blackfire-*.so $(php -r "echo ini_get ('extension_dir');")/blackfire.so \
&& printf "extension=blackfire.so\nblackfire.agent_socket=tcp://blackfire:8307\n" > $PHP_INI_DIR/conf.d/blackfire.ini \
&& rm -rf /tmp/blackfire /tmp/blackfire-probe.tar.gz
```

4. Rebuild and restart all your containers
Expand Down
58 changes: 36 additions & 22 deletions distribution/debugging.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,31 +4,43 @@

## Xdebug

The default Docker stack is shipped without a Xdebug stage. It's easy
though to add [Xdebug](https://xdebug.org/) to your project, for development
purposes such as debugging tests or remote API requests.
For development purposes such as debugging tests or remote API requests,
[Xdebug](https://xdebug.org/) is shipped by default with the API Platform distribution.

## Add a Development Stage to the Dockerfile
To enable it, run:

To avoid deploying API Platform to production with an active Xdebug extension,
it's recommended to add a custom stage to the end of the `api/Dockerfile`.
```console
XDEBUG_MODE=debug docker compose up --wait
```

```Dockerfile
# api/Dockerfile
FROM api_platform_php as api_platform_php_dev
## Using Xdebug with PhpStorm

ARG XDEBUG_VERSION=3.1.3
RUN set -eux; \
apk add --no-cache --virtual .build-deps $PHPIZE_DEPS; \
pecl install xdebug-$XDEBUG_VERSION; \
docker-php-ext-enable xdebug; \
apk del .build-deps
```
First, [create a PHP debug remote server configuration](https://www.jetbrains.com/help/phpstorm/creating-a-php-debug-server-configuration.html):

1. In the `Settings/Preferences` dialog, go to `PHP | Servers`
2. Create a new server:
* Name: `api` (or whatever you want to use for the variable `PHP_IDE_CONFIG`)
* Host: `localhost` (or the one defined using the `SERVER_NAME` environment variable)
* Port: `443`
* Debugger: `Xdebug`
* Check `Use path mappings`
* Map the local `api/` directory to the `/app` absolute path on the server

You can now use the debugger!

1. In PhpStorm, open the `Run` menu and click on `Start Listening for PHP Debug Connections`
2. Add the `XDEBUG_SESSION=PHPSTORM` query parameter to the URL of the page you want to debug or use [other available triggers](https://xdebug.org/docs/step_debug#activate_debugger).
Alternatively, you can use [the Xdebug extension](https://xdebug.org/docs/step_debug#browser-extensions) for your preferred web browser.

3. On the command-line, we might need to tell PhpStorm which [path mapping configuration](https://www.jetbrains.com/help/phpstorm/zero-configuration-debugging-cli.html#configure-path-mappings) should be used, set the value of the PHP_IDE_CONFIG environment variable to `serverName=api`, where `api` is the name of the debug server configured higher.

Example:

## Configure Xdebug with Docker Compose Override
```console
XDEBUG_SESSION=1 PHP_IDE_CONFIG="serverName=api" php bin/console ...
```

XDebug is shipped by default with the API Platform distribution.
To enable it, run: `XDEBUG_MODE=debug docker compose up --wait`
## Using Xdebug With VSCode

If you are using VSCode, use the following `launch.json` to debug.
Note that this configuration includes the path mappings for the Docker image.
Expand All @@ -51,8 +63,10 @@ Note that this configuration includes the path mappings for the Docker image.
}
```

Note: On Linux, the `client_host` setting of `host.docker.internal` may not work.
In this case you will need the actual local IP address of your computer.
> [!NOTE]
>
> On Linux, the `client_host` setting of `host.docker.internal` may not work.
> In this case you will need the actual local IP address of your computer.

## Troubleshooting

Expand All @@ -64,6 +78,6 @@ $ docker compose exec php \
php --version

PHP …
with Xdebug v3.1.3, Copyright (c) 2002-2021, by Derick Rethans
with Xdebug v…, Copyright (c) 2002-2021, by Derick Rethans
…
```