cPanelnew

If your project is hosted on a server infrastructure that uses WHM/cPanel, integration with Blackfire is possible by following this chapter's instructions.

Before starting, check with your provider that the Blackfire stack is installed and enabled on the server. If not, follow the administrator procedure or ask your provider to do so.

Then, follow the user procedure if you want to use different sets of credentials per website.

User Procedure

Follow the procedure depending on which EasyApache version is installed: EasyApache 3 or EasyApache 4.

Caution

If Blackfire is not installed on the server, provide a link to the administrator documentation.

EasyApache 4

To configure Blackfire for EasyApache 4, go to the MultiPHP INI Editor (Home >> Software >> MultiPHP INI Editor), switch to "Editor Mode", select the proper domain and then copy/paste/adapt to your needs the following snippet:

1
2
3
4
5
[blackfire]
; Adapt the following credentials using the ones found on
; https://blackfire.io/dashboard/mine/settings or your environment settings.
blackfire.server_id=e0b30241-a25d-4162-9ebb-329f784f1fc7
blackfire.server_token=3ac2260e038f138a5bca515b72c0205117d886777cf6472b14beabb704e06aa1

EasyApache 3

To configure Blackfire for EasyApache 3, define some environment variables by creating or editing the .htaccess file in the project's document root:

1
2
3
4
5
6
<IfModule mod_env.c>
    # Adapt the following credentials using the one found on
    # https://blackfire.io/dashboard/mine/settings or your environment settings.
    SetEnv BLACKFIRE_SERVER_ID e0b30241-a25d-4162-9ebb-329f784f1fc7
    SetEnv BLACKFIRE_SERVER_TOKEN 3ac2260e038f138a5bca515b72c0205117d886777cf6472b14beabb704e06aa1
</IfModule>

Note

If Blackfire has been installed but not enabled for all users, enable it by creating a custom php.ini configuration file.

Create a php.ini file in your home directory, copy/paste the content of the default PHP configuration (usually found at /usr/local/lib/php.ini) and append the following content:

1
2
3
[blackfire]
; Only required if Blackfire is not loaded for all websites
extension=blackfire.so

Then, adapt .htaccess to use the custom php.ini file by adding the following:

1
2
3
<IfModule mod_suphp.c>
    suPHP_ConfigPath /home/<myuser>/php.ini
</IfModule>

Caution

Some of these steps may not be allowed by your provider. In such case, contact its support and ask for the configuration by pointing at this documentation.

Administrator Procedure

As a cPanel administrator, to provide the Blackfire stack to your users, install the Agent and the Probe.

To install the stack you will first need to create an account on Blackfire.io if you don't have one yet. It takes less than a minute if you already have a GitHub or Google+ account.

Allowing your users to use the Blackfire stack is free of charge and can be done using a free account credentials to register the agent.

However, if you also want to be able to profile your users websites or to provide Blackfire editions out of the box to your users, you may want to have a look at our Hosters edition.

Then follow the installation instructions for RedHat based distributions.

Then, follow the specific procedure for EA3 or EA4.

If you are managing a cluster setup, please refer to our Load Balancer section to learn more about the various options at your disposal.

EasyApache 3

To enable Blackfire for your users, go to the PHP Configuration Editor, switch to "Advanced Mode" and add blackfire.so to the extension field.

EasyApache 4

Blackfire should have been automatically enabled by our Redhat package. You can check by running /opt/cpanel/ea-php56/root/usr/bin/php --ri blackfire (tweak to match the installed PHP versions).

Next, allow your users to add Blackfire settings to their php.ini. Edit /usr/local/cpanel/whostmgr/etc/phpini_directives.yaml and append the following snippet at the end of the 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
33
34
35
blackfire.server_id:
  changeable: PHP_INI_ALL
  default: NULL
  multiple: 0
  note: 'Blackfire probe Server ID'
  section: 'blackfire'
  type: string
blackfire.server_token:
  changeable: PHP_INI_ALL
  default: NULL
  multiple: 0
  note: 'Blackfire probe Server Token'
  section: 'blackfire'
  type: string
blackfire.log_level:
  changeable: PHP_INI_ALL
  default: 1
  multiple: 0
  note: 'Blackfire probe log verbosity level'
  section: 'blackfire'
  type: integer
blackfire.log_file:
  changeable: PHP_INI_ALL
  default: NULL
  multiple: 0
  note: 'Blackfire probe log destination file'
  section: 'blackfire'
  type: string
blackfire.agent_timeout:
  changeable: PHP_INI_ALL
  default: 0.25
  multiple: 0
  note: ''
  section: 'blackfire'
  type: float

Caution

cPanel Updates

Currently, because of a cPanel limitation, this last step must be repeated on every cPanel upgrade.

cPanel is aware of this limitation and we are currently in discussion with their team to smooth this experience in the near future.

Uninstall Blackfire

If you are using EA3, go to the PHP Configuration Editor, switch to "Advanced Mode" and remove blackfire.so from the extension field.

In all cases, remove the installed Blackfire packages.