Skip to main content

Install PHP agent with Debian

Steps

To install the PHP agent:

  1. Install the agent package from https://pkg.contrastsecurity.com. This command registers our package repository in your system:

    curl \
  https://pkg.contrastsecurity.com/api/gpg/key/public | sudo apt-key add -

echo "deb https://pkg.contrastsecurity.com/debian-public/ $(sed -rne 's/^VERSION_CODENAME=(.*)$/\1/p' /etc/*ease) contrast" \
  | sudo tee /etc/apt/sources.list.d/contrast.list

echo "deb https://pkg.contrastsecurity.com/debian-public/ all contrast" \
  | sudo tee -a /etc/apt/sources.list.d/contrast.list

  2. Once complete, use this command to install the agent:

    sudo apt-get update && sudo apt-get install contrast-php-agent

    Note

    Once PHP is configured to use the extension, it will be used whenever the interpreter is executed. This step should be delayed until immediately before the application itself is run. This will prevent any unexpected behavior when running artisan or other PHP commands.

  3. Locate the PHP configuration file, called php.ini and on many systems it can be found under /usr/local/etc/php/.

    If the php-config command is available, it can be used to find the configuration file path using php-config --ini-path. If no configuration file yet exists under that path, it will need to be created.

  4. Edit your PHP configuration file:

    echo "extension=/usr/local/lib/contrast/php/contrast.so" >> `php-config --ini-path`/php.ini

  5. Configure the PHP agent using the PHP YAML template or environment variables.

  6. Start your application in the normal way.

  7. Exercise and test your application.

  8. Verify that the PHP agent is running by checking the Contrast UI and/or looking for PHP agent log output (depending on configuration).

Notes

  • It is possible to use the agent with the PHP CLI by adding a flag to the command line:

    php -d extension=/usr/local/lib/contrast/php/contrast.so

  • Library analysis and route discovery is currently performed on the first request to the application. For this reason we expect the first request to be considerably slower than subsequent requests.

  • The agent has not been tested with third-party PHP extensions. The behavior of the agent when any other third-party extensions (including xdebug, APMs, etc.) is undefined.

  • The agent may not work properly when preloading is enabled. Disabling preloading when using the agent is recommended.

  • By default the agent assumes that the server’s working directory when it runs the PHP application is the same as the top level directory of the application source tree. The agent uses this path to perform library analysis and route discovery. If this is not the case, you will need to use the application.path setting in the configuration to set the top-level working directory of your application.

In this section: