Configuration PHP

Configuring the Probe via Environment Variables

The preferred way to configure the PHP probe is via environment variables. That allows you to change the configuration without modifying your code:

  • BLACKFIRE_CLIENT_ID

    Sets the client ID from the Client ID/Client Token credentials pair.

    or to display your Blackfire's credentials.

  • BLACKFIRE_CLIENT_TOKEN

    Sets the client Token from the Client ID/Client Token credentials pair.

    or to display your Blackfire's credentials.

  • BLACKFIRE_LOG_LEVEL

    Sets the verbosity of Probe’s log output. Default value is 1 (error).

    1
    2
    # 1: error, 2: warning, 3: info, 4: debug
    BLACKFIRE_LOG_LEVEL=1
    
  • BLACKFIRE_LOG_FILE

    Sets the output destination of Probe’s log. Default value is empty.

    1
    BLACKFIRE_LOG_FILE="/tmp/probe.log"
    
  • BLACKFIRE_AGENT_SOCKET

    Sets the socket the Probe will contact the Agent on. Possible values can be a unix socket or a TCP address.

    The default value is platform dependent, as detailed below.

    On Linux:

    1
    BLACKFIRE_AGENT_SOCKET="unix:///var/run/blackfire/agent.sock"
    

    On macOS:

    1
    2
    3
    4
    5
    # amd64
    BLACKFIRE_AGENT_SOCKET="unix:///usr/local/var/run/blackfire-agent.sock"
    
    # arm64 (M1)
    BLACKFIRE_AGENT_SOCKET="unix:///opt/homebrew/var/run/blackfire-agent.sock"
    

    On Windows:

    1
    BLACKFIRE_AGENT_SOCKET="tcp://127.0.0.1:8307"
    
  • BLACKFIRE_ENDPOINT

    Sets the API endpoint the profile data will be sent to.

    1
    BLACKFIRE_ENDPOINT="https://blackfire.io"
    
  • BLACKFIRE_APM_ENABLED

    Enables or disables Blackfire Monitoring.

    1
    BLACKFIRE_APM_ENABLED=1
    
  • BLACKFIRE_SERVER_ID / BLACKFIRE_SERVER_TOKEN

    Sets the server id and server token used to authenticate with Blackfire. This is optional, and should be used only if you have a shared agent between multiple environments.

    or to display your Blackfire's credentials.

You can set these environment variables in a project’s local .env file if supported, or in your global shell configuration file (such as ~/.bashrc or ~/.zshrc):

1
2
3
4
export BLACKFIRE_CLIENT_ID=xxx
export BLACKFIRE_CLIENT_TOKEN=yyy
export BLACKFIRE_LOG_LEVEL=4
export BLACKFIRE_LOG_FILE=/tmp/probe.log

Configuring the Probe via the Blackfire CLI Client Configuration File

When environment variables are not set, the probe reads its default configuration from the configuration of the Blackfire CLI client. The location of this file depends on the operating system you use. Read more about the CLI configuration.

Configuring the Probe via the php.ini Configuration File

The PHP probe can also be configured via the php.ini configuration file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
[blackfire]
extension=blackfire.so
; On Windows use the following configuration:
; extension=php_blackfire.dll

; Sets fine-grained configuration for Probe.
; This should be left blank in most cases. For most installs,
; the server credentials should only be set in the agent.
;blackfire.server_id =

; Sets fine-grained configuration for Probe.
; This should be left blank in most cases. For most installs,
; the server credentials should only be set in the agent.
;blackfire.server_token =

; Log verbosity level (4: debug, 3: info, 2: warning, 1: error)
;blackfire.log_level = 1

; Log file (STDERR by default)
;blackfire.log_file = /tmp/blackfire.log

; Sets the socket where the agent is listening.
; Possible value can be a unix socket or a TCP address.
; Defaults to unix:///var/run/blackfire/agent.sock on Linux,
; unix:///usr/local/var/run/blackfire-agent.sock on macOS amd64,
; unix:///opt/homebrew/var/run/blackfire-agent.sock on macOS arm64 (M1),
; and to tcp://127.0.0.1:8307 on Windows.
;blackfire.agent_socket = unix:///var/run/blackfire/agent.sock

; Enables Blackfire Monitoring
; Enabled by default since version 1.61.0
;blackfire.apm_enabled = 1

Note

If you don’t know where is your php.ini file located, execute this command: php --ini

Caution

We do not recommend configuring server credentials (server id and server token) via php.ini. For the vast majority of cases, the server credentials should only be set in the agent.

If you do configure server credentials via php.ini, they will be shared amongst all virtual hosts. Read the next section to learn more about how to configure different credentials on a per-host/per-directory basis.

Caution

There is only one use case for configuring server credentials via php.ini.

  1. You must have multiple Blackfire environments, with each server dedicated to one of the environments, and all servers are configured to communicate with the same agent.

Configuring the Probe via the Web Server Configuration

In the previous section, you learned it is possible to configure all websites hosted on a server by setting the blackfire.server_id and blackfire.server_token in php.ini. You also learned that we do not recommend this except under very specific conditions.

Like global-configuration via php.ini, there are specific use cases where it makes sense to configure Blackfire on a vhost-by-vhost basis. If you fit this criterion, the following sections tell you how to better control the server credentials per vhost.

Caution

There are only two use cases for fine-grained configuration. If neither of these use cases describes you, you should not attempt fine-grained probe configuration. For the vast majority of cases, the server credentials should only be set in the agent.

  1. You must have multiple Blackfire environments, multiple virtual hosts on a server, and you want to assign specific Blackfire environments to specific virtual hosts.
  2. You must have one or more Blackfire environments, multiple virtual hosts on a server, and you want to only allow Blackfire profiling on a subset of your virtual hosts.

Caution

We do not recommend that you set some “default” credentials in php.ini as the Agent ones will already be used as the default fallback.

Nginx Configuration Settings

You can override the default credentials of the Probe in the Nginx configuration via the http, server, and location sections. For more information, see Nginx documentation.

1
2
3
4
5
6
location / {
  fastcgi_param PHP_VALUE "
    blackfire.server_id=e0b30241-a25d-4162-9ebb-329f784f1fc7
    blackfire.server_token=3ac2260e038f138a5bca515b72c0205117d886777cf6472b14beabb704e06aa1
";
}

Note

Be warned that you must configure all hosts served by a PHP FPM pool.

Tip

If you want a host to use the default credentials, pass empty values:

1
2
3
4
5
6
location / {
  fastcgi_param PHP_VALUE "
    blackfire.server_id=
    blackfire.server_token=
";
}

Apache Configuration Settings

You can override the default credentials of the Probe in the main Apache virtual-host configuration or by using a .htaccess file.

Use the following example to adjust your configuration, see PHP documentation for more information.

1
2
3
4
5
6
7
8
9
<VirtualHost 192.168.42.43>
    ServerName www.myvhost1.com
    DocumentRoot "/path/to/vhost1/"
    ...
    <IfModule mod_php5.c>
        php_admin_value blackfire.server_id "e0b30241-a25d-4162-9ebb-329f784f1fc7"
        php_admin_value blackfire.server_token "3ac2260e038f138a5bca515b72c0205117d886777cf6472b14beabb704e06aa1"
    </IfModule>
</VirtualHost>

PHP-FPM Pool Configuration Settings

You can override the default credentials of the Probe per PHP-FPM pool. Open the php-fpm.conf and adjust settings given the following example. See the FPM documentation for more information.

1
2
3
4
5
6
7
8
9
[website1]
listen=/tmp/pool-website1.sock
php_admin_value blackfire.server_id "b5f6c549-93c6-4118-a549-cf97f9effd54"
php_admin_value blackfire.server_token "5e5bc139f76c9c45ffbe7463fadaff2eb8d8ce8fcf172941fc881802445abc52"

[website2]
listen=/tmp/pool-website1.sock
php_admin_value blackfire.server_id "e0b30241-a25d-4162-9ebb-329f784f1fc7"
php_admin_value blackfire.server_token "3ac2260e038f138a5bca515b72c0205117d886777cf6472b14beabb704e06aa1"

Note

Please have a look at the detailed documentation about reverse proxies in case your application is behind a cache server, a load balancer, or any other reverse proxy.