Install PHP agent manually
To download, build, and install the PHP agent from a direct download, you can use the agent installer, or install manually for your distribution.
To install the PHP agent manually, install the agent package for your distribution from https://pkg.contrastsecurity.com.
For Debian
Install the agent package from
https://pkg.contrastsecurity.comto register it into your system:curl -fsSL https://pkg.contrastsecurity.com/api/gpg/key/public \ | sudo gpg --dearmor -o /usr/share/keyrings/contrast-keyring.pgp echo "deb [signed-by=/usr/share/keyrings/contrast-keyring.pgp] https://pkg.contrastsecurity.com/debian-public/ all contrast" \ | sudo tee -a /etc/apt/sources.list.d/contrast.list
Install the agent:
sudo apt-get update && sudo apt-get install -y contrast-php-agent
For Red Hat Package Manager (RPM)
Install the agent package from
https://pkg.contrastsecurity.comto register it into your system:sudo rpm --import https://pkg.contrastsecurity.com/api/gpg/key/public sudo tee /etc/yum.repos.d/contrast.repo <<-"EOF" [contrast] name=Contrast redhat-$releasever repo baseurl=https://pkg.contrastsecurity.com/rpm-public/redhat-$releasever/ gpgcheck=0 enabled=1 gpgkey=https://pkg.contrastsecurity.com/api/gpg/key/public repo_gpgcheck=1 EOF
Install the agent:
sudo yum install -y contrast-php-agent
or
sudo dnf install -y contrast-php-agent
For Amazon Linux 2023
Install the agent package from
https://pkg.contrastsecurity.comto register it into your system:sudo rpm --import https://pkg.contrastsecurity.com/api/gpg/key/public sudo tee /etc/yum.repos.d/contrast.repo <<-"EOF" [contrast] name=Contrast AL2023 repo baseurl=https://pkg.contrastsecurity.com/rpm-public/redhat-9/ gpgcheck=0 enabled=1 gpgkey=https://pkg.contrastsecurity.com/api/gpg/key/public repo_gpgcheck=1 EOF
Install the agent:
sudo yum install -y contrast-php-agent
or
sudo dnf install -y contrast-php-agent
For Alpine
Install the agent package from
https://pkg.contrastsecurity.comto register it into your system:wget -q -O /etc/apk/keys/contrast-security-alpinelinux.rsa.pub \ https://pkg.contrastsecurity.com/artifactory/api/security/keypair/public/repositories/alpine-public echo "https://pkg.contrastsecurity.com/alpine-public/$(cut -d. -f1-2 /etc/alpine-release)/main" \ | tee -a /etc/apk/repositories
Install the agent:
apk add --update contrast-php-agent
Configure PHP
The agent is a PHP extension, so PHP must load it at startup. Use one of the following methods, and then restart PHP-FPM or Apache:
To use contrast-php-util, run contrast-php-util enable-agent. This creates a contrast.ini file in the scan directory used by the PHP command found on your PATH.
To edit php.ini yourself, add the following line to the end of the php.ini file used by your application.
extension=/usr/local/lib/contrast/php/contrast.so
To find the file, run
php-config --ini-path. Ifphp-configis not available, runphp -i | grep php.iniand read the Configuration File (php.ini) Path line. If nophp.iniexists at that path, create one.On some systems, PHP on the command line reads a different ini file than PHP-FPM or Apache. For example, PHP-FPM on Debian and Ubuntu often reads files under
/etc/php/{version}/fpm/. Make sure you change the ini file that the PHP running your application reads.
Configure the PHP agent
Ensure that the necessary extensions are enabled.
The PHP agent requires the
mbstringandjsonextensions. Runphp -mto confirm that both are listed.If
mbstringis missing, enable it inphp.ini, for example withextension=mbstring.The
jsonextension is built into PHP 8.0 and later.extension=curl extension=mbstring extension=json
Configure the PHP agent using the PHP YAML template or environment variables (if not already done).
Start your application in the normal way.
Verify the agent deployment
Interact with your application as you normally would. For example, interact with your application's web interface or send API commands.
In the Agent Wizard, select View agent activity to verify that your agent appears in the agents list.
Verify that you see the name of your application in the applications list.
In Northstar, select Applications from the left navigation.
In Contrast, select Applications from the header.
Verify that you see the name of your local server in the servers list.
In Northstar, select Servers from the left navigation.
In Contrast, select Servers from the header.
Notes
Library analysis and route discovery are 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 with any other third-party extensions (including APMs, etc.) is undefined. The agent is known to be incompatible with xdebug and should not be used concurrently.
The agent may not work properly when preloading is enabled. Disabling preloading when using the agent is recommended.
By default, the agent uses the working directory of the PHP process as the top-level directory of your application. If that directory is
/, the agent uses the web server's document root instead. If neither is the top-level directory of your application source, set theapplication.pathsetting.