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 procedure depending on which EasyApache version is installed: EasyApache 3 or EasyApache 4 if you want to use different sets of credentials per website.
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/my/settings/credentials or your environment settings. blackfire.server_id=e0b30241-a25d-4162-9ebb-329f784f1fc7 blackfire.server_token=3ac2260e038f138a5bca515b72c0205117d886777cf6472b14beabb704e06aa1 |
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/my/settings/credentials 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 a case, contact its support and ask for the configuration by pointing at this documentation.
As a cPanel administrator, if you want to provide the Blackfire stack to your users, you need to install the Agent and the Probe.
To install the stack, you first need to create an account on Blackfire.io.
Then follow the installation instructions for RedHat based distributions.
To enable Blackfire for your users, go to the PHP Configuration Editor,
switch to “Advanced Mode” and add blackfire.so
to the extension
field.
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).
Tip
Starting with cPanel 68 and Blackfire probe 1.19.0, the next step is not required anymore. You only need to follow it if you did not upgrade yet.
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 | 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 |
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 soon.
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.