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. the PHP version (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

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

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, let's copy the binary extension to the PHP binary extensions directory:

$ cp /usr/lib/sqreen/extensions/<PHP version>/sqreen.so <PHP binary extensions directory>
# Example:
# 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:

Copy for ZTS builds only

$ cp /usr/lib/sqreen/extensions/<PHP version>-zts/sqreen.so <PHP binary extensions directory>

Example:

# cp /usr/lib/sqreen/extensions/5.6-zts/sqreen.so /usr/lib/php/extensions/no-debug-zts-20131226

Configuration

Then, put the sample configuration sqreen.ini file to the right place:

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

Finally, edit the sqreen.ini file to set a value on the Sqreen token. The token value can be found in your Sqreen dashboard: https://my.sqreen.io/

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 in order to allow us to protect your code leveraging them. We found that 50 is in general a good value.

priority = 50

What about other modules?

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