PHP Probe PHP

PHP Probe Global Configuration

Here is a typical configuration for the PHP probe that you can use as a template in your 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
[blackfire]
extension=blackfire.so
; On Windows use the following configuration:
; extension=php_blackfire.dll


; 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,
; and to tcp://127.0.0.1:8307 on Windows.
;blackfire.agent_socket = unix:///var/run/blackfire/agent.sock

blackfire.agent_timeout = 0.25

; 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 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 =

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 individual server dedicated to one of the environments, and all servers are configured to communicate with the same agent.

Probe Fine-Grained 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 criteria, 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 describe 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 to the detailed documentation about reverse proxies in case your application is behind a cache server, a load balancer or any other reverse proxy.

Content Security Policy

The browser extension injects a toolbar in the profiled webpage and uses an <iframe> to communicate with the PHP extension.

In case the web page declares a Content Security Policy regarding frames usage, the communication may be broken and you would be informed in the toolbar.

In this case, you can declare Blackfire domain as trusted by adding the blackfire.io domain in your application's headers:

1
Content-Security-Policy: frame-src 'self' blackfire.io