Manual configuration of the PHP extension

For more advanced needs or custom PHP setup that may not be supported by sqreen-installer, there are a few easy steps to manually configure the Sqreen PHP extension.

Prerequisites

The php command line (or the phpinfo() function) will help you to gather the following:

  1. 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)?
  4. PHP configuration directory

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

In the last case (ZTS), nothing is returned: it means the PHP extension does not uses ZTS.

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 isn't 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

On top of having packages for most Linux distributions, the Sqreen extension is available from static repositories. Download it manually from here or in this way:

$ 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

The Sqreen PHP extension files will be extracted on your disk.

Configuration steps

Copy for non ZTS builds

When PHP 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 extensions directory>
# Example for PHP 5.6 non ZTS:
cp /usr/lib/sqreen/extensions/5.6/sqreen.so /usr/lib/php/extensions/no-debug-non-zts-20131226

Otherwise when PHP uses ZTS, please follow those instructions instead:

# cp /usr/lib/sqreen/extensions/<PHP version>-zts/sqreen.so <PHP binary extensions directory>
# Example for PHP 5.6 ZTS:
cp /usr/lib/sqreen/extensions/5.6-zts/sqreen.so /usr/lib/php/extensions/no-debug-zts-20131226

Next, move the sample sqreen.ini configuration file to the right location:

# cp /usr/lib/sqreen/conf/sqreen.ini <PHP configuration directory>
# Example for PHP 5.6:
cp /usr/lib/sqreen/conf/sqreen.ini /usr/local/etc/php/5.6/conf.d

Edit the sqreen.ini file to set a value on the Sqreen token. The token value is available in your Sqreen dashboard.

sqreen.token = 'your token value'

The module loading priority is important as well for Sqreen to load after other extensions (e.g. database drivers). This is needed to allow the extension to protect your code. We found that 50 is a good value.

priority = 50

What about other modules?

Modules such as New Relic or Blackfire also perform instrumentation. Sqreen library should be required after them.