1. Documentation
  2. Blackfire for PHP
  3. Integrations
  4. PHP Probe with Docker

PHP Probe with Docker PHP

Enabling the PHP Probe

To be able to use Blackfire, add the probe to your Docker PHP image. Here is an example of a Dockerfile based on the official Docker PHP image:

Caution

Choose the snippet corresponding to the base system you are using (Linux or Alpine).

FROM php:8.2-fpm

RUN version=$(php -r "echo PHP_MAJOR_VERSION.PHP_MINOR_VERSION;") \
    && 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 \
    && rm -rf /tmp/blackfire /tmp/blackfire-probe.tar.gz

# Please note that the Blackfire Probe is dependent on the session module.
# If it isn't present in your install, you will need to enable it yourself.
FROM php:8.2-fpm-alpine

RUN version=$(php -r "echo PHP_MAJOR_VERSION.PHP_MINOR_VERSION;") \
    && architecture=$(uname -m) \
    && curl -A "Docker" -o /tmp/blackfire-probe.tar.gz -D - -L -s https://blackfire.io/api/v1/releases/probe/php/alpine/$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 \
    && rm -rf /tmp/blackfire /tmp/blackfire-probe.tar.gz

# Please note that the Blackfire Probe is dependent on the session module.
# If it isn't present in your install, you will need to enable it yourself.

Note

Base image

This example targets official PHP Docker images. If you are using a custom image, you probably need to adapt it.

A common mistake while adapting it for custom images is the lack of PHP_INI_DIR. In such case you can get it by using php -i | grep "additional .ini".

An alternative solution is to proceed with the regular Blackfire installation using the package manager available with your base image OS.

Caution

If you are using a zts (Zend Thread Safety) version of PHP, please add -zts to the version name.

Build your container as usual:

1
docker build -t php-blackfire .

Note

Upgrading

To upgrade the Probe, rebuild your PHP container and relaunch it (you might need to use the --no-cache option to force the download of the latest Probe version).

Docker Compose

If you use docker compose, you can connect your PHP container and the agent using the following snippet:

or to display your Blackfire's credentials.

version: '3'
services:
  app:
    build: .
    ports:
      - "8080:80"

  blackfire:
    image: blackfire/blackfire:2
    environment:
        # Exposes BLACKFIRE_SERVER_* environment variables from the host:
        BLACKFIRE_SERVER_ID: <YOUR_BLACKFIRE_SERVER_ID>
        BLACKFIRE_SERVER_TOKEN: <YOUR_BLACKFIRE_SERVER_TOKEN>

        # Exposes BLACKFIRE_CLIENT_* environment variables
        # allowing the client to communicate with Blackfire's API:
        BLACKFIRE_CLIENT_ID: <YOUR_BLACKFIRE_CLIENT_ID>
        BLACKFIRE_CLIENT_TOKEN: <YOUR_BLACKFIRE_CLIENT_TOKEN>

Using the Client for CLI Profiling

When profiling command line scripts, the process is slightly different than for HTTP requests. You execute blackfire run which in the end runs an embedded agent and wraps your PHP script with the required environment variables. Therefore, in this configuration, you do not need to (and cannot) use the blackfire/blackfire image. Instead, you need to fetch and use the blackfire client binary inside your PHP container.

Here is an example of a Dockerfile based on the official Docker PHP image that retrieves the client at build time:

1
2
3
4
5
6
7
FROM php:8.2-fpm

RUN mkdir -p /tmp/blackfire \
    && architecture=$(uname -m) \
    && curl -A "Docker" -L https://blackfire.io/api/v1/releases/cli/linux/$architecture | tar zxp -C /tmp/blackfire \
    && mv /tmp/blackfire/blackfire /usr/bin/blackfire \
    && rm -Rf /tmp/blackfire

Build your container as usual:

1
docker build -t php-blackfire .

With exposed BLACKFIRE_CLIENT_ID and BLACKFIRE_CLIENT_TOKEN environment variables, you can now directly execute blackfire run php myscript.php within your PHP container.

Warning

CLI profiling relies on BLACKFIRE_CLIENT_ID and BLACKFIRE_CLIENT_TOKEN, your personal credentials. Only the user whose credentials are used can access those profiles from /my/profiles.

Please consider adding the --env=<ENV_UUID> parameter to send the profile to a shared environment and permit collaboration.

Debugging the PHP Probe

By default, the Probe is quiet and does not produce logs. To debug issues, pass -e BLACKFIRE_LOG_LEVEL=4 to the docker run command, and tail the logs via Docker:

1
docker logs -f PHP_CONTAINER_ID

Installing the Agent

To install the Blackfire Agent using Docker, please refer to the dedicated documentation page.