Manual installation of the PHP agent

The default Sqreen installer may not suport more advanced needs, or custom PHP setups. This guide outlines the steps to manually install and confgure the PHP agent.

Prerequisites

The php command (or the phpinfo() function) helps you to gather the following:

  1. the PHP version (5.3, 5.4, 5.5, 5.6, 7.0, ...)
  2. PHP binary extensions directory
  3. Is PHP is using ZTS (Zend Thread Safety) or not
  4. PHP configuration directory

For example:

$ php -i | grep 'PHP Version'
PHP Version => 5.6.30

$ php -i | grep extension_dir
extension_dir => /usr/local/Cellar/php56/5.6.30_6/lib/php/extensions/no-debug-non-zts-20131226 => /usr/local/Cellar/php56/5.6.30_6/lib/php/extensions/no-debug-non-zts-20131226

$ php -i | grep 'additional .ini files'
Scan this dir for additional .ini files => /usr/local/etc/php/5.6/conf.d

$ php -i | grep ZTS
# If nothing is returned, then ZTS is not enabled

Setting name Returned value Configuration value to use
PHP version PHP Version => 5.6.30 5.6
PHP binary extensions directory extension_dir => /usr/lib/php/extensions/no-debug-non-zts-20131226 => /usr/lib/php/extensions/no-debug-non-zts-20131226 /usr/lib/php/extensions/no-debug-non-zts-20131226
ZTS nothing! ZTS is not enabled.
PHP configuration directory Scan this dir for additional .ini files => /usr/local/etc/php/5.6/conf.d /usr/local/etc/php/5.6/conf.d

Retrieve Sqreen extension files

The Sqreen agent is available as a package for most Linux distributions, and from static repositories.

Download it manually or use the following commands to download and extract the agent files:

curl https://download.sqreen.io/php/sqreen-php-extension/linux/sqreen-php-extension-latest-linux.tar.gz -o sqreen-php-extension.tar.gz

tar xf sqreen-php-extension.tar.gz

Setup

Copy for non ZTS builds

If your PHP installation doesn't use ZTS, copy the binary extension to the PHP binary extensions directory:

cp /usr/lib/sqreen/extensions/{PHP_VERSION}/sqreen.so /{PHP_BINARY_EXTENSION_DIR}

Copy for ZTS builds

If your PHP installation does use ZTS, use the following command instead:

cp /usr/lib/sqreen/extensions/{PHP_VERSION}-zts/sqreen.so {PHP_BINARY_EXTENSION_DIR}

Configuration

Copy the sample configuration sqreen.ini file to the correct location:

cp /usr/lib/sqreen/conf/sqreen.ini {PHP_CONFIG_DIR}

Edit the sqreen.ini file to set your Sqreen token. You can find the token in your Sqreen dashboard.

sqreen.token = 'your token value'

It's important for Sqreen to load after other extensions (such as database drivers). Sqreen needs this to protect your code using other drivers. We found that 50 is a good value.

priority = 50

What about other modules?

Modules such as New Relic or Blackfire also perform instrumentation. You should require Sqreen after them.