Install PHP on Linux for Matomo

Auto-hébergement

This guide explains how to install and configure PHP for Matomo on Linux for Ubuntu 22.04, 24.04 and RHEL 8 and 9 (Rocky Linux, AlmaLinux).

PHP execution environments used by Matomo

Matomo uses two PHP execution environments, each with its own configuration file. PHP-FPM runs the web interface and handles tracking requests, while PHP-CLI runs archiving and maintenance tasks.

Console commands such as core:archive, core:update, and scheduled tasks always use the PHP-CLI environment. A common issue occurs when PHP settings or extensions are updated in one environment but not the other, resulting in unexpected behaviour.

Installation steps

Step 1: Check your current PHP setup

Before installing PHP, verify whether PHP is already available in your Linux environment.

1. The PHP-CLI environment runs the Matomo archiver and other command-line database tasks. Check the CLI version from your Linux terminal (for example, Ubuntu, WSL, or via SSH):

php -v

2. The PHP-FPM environment is used by your web server to render the Matomo interface. To check this version, create a temporary file (for example, phpinfo.php), in your web root directory, containing:

<?php 
phpinfo(); 
?>

3. Save the file and open it in your browser (https://your-domain.com/phpinfo.php).
4. It will display the PHP configuration used by the web server to run Matomo.
5. Confirm both PHP versions meet Matomo’s requirements and PHP-CLI matches the version used by the web server.
6. If PHP is not installed, the following error appears: php: command not found. Install PHP before continuing.
7. Choose the installation method that matches your Linux distribution:

Step 2: Install PHP

Ubuntu 22.04 and 24.04

1. Run the following commands in a Linux terminal (for example, Ubuntu or Ubuntu on Windows Subsystem for Linux).
2. Refresh the local package index and download the latest package lists from configured repositories:

sudo apt update

3. Install PHP for Apache, PHP CLI for Matomo console commands, and MySQL support required by Matomo:

sudo apt install php php-curl php-gd php-cli php-mysql php-xml php-mbstring php-intl php-zip

4.Verify the installation:

php -v

Optional check: apply preference to index.php over index.html

Apache may load index.html before index.php when both files exist in the same directory. This can prevent Matomo from loading if an index.html file is present.

1. Open the directory index configuration and ensure index.php appears first:

sudo nano /etc/apache2/mods-enabled/dir.conf

2. If index.html appears before index.php, move index.php to the first position.
3. Save the file and exit the editor.
4. Restart Apache so the change takes effect:

sudo systemctl restart apache2

RHEL 8 and 9 (Rocky Linux, AlmaLinux)

If you are using Ubuntu, follow the instructions above as package names, commands, and configuration paths differ between Ubuntu and RHEL-based systems. This section only applies to RHEL, Rocky Linux, and AlmaLinux (and other RHEL-compatible distributions).

1. Enable PHP module by first getting the list of available PHP versions:

sudo dnf module list php

2. Enable a supported version, for example PHP 8.1:

sudo dnf module enable php:8.1

3. Install PHP packages:

sudo dnf install php php-cli php-mysqlnd

4. Restart Apache so the change takes effect:

sudo systemctl restart httpd

5. Verify PHP CLI:

php -v

Step 3: Install required PHP extensions for Matomo

Matomo requires several PHP extensions. Missing extensions are the most common cause of system check errors.

1. Install the following extensions (at a minimum).
2. Ubuntu:

sudo apt install php-gd php-curl php-mbstring php-xml php-zip

2. RHEL-based systems:

sudo dnf install php-gd php-curl php-mbstring php-xml php-zip

3. Restart Apache after installing extensions.

Step 4: Verify Matomo console commands

Ensure Matomo can run CLI commands:

cd /path/to/matomo
php console core:archive --help

If this fails, PHP CLI is not configured correctly.

Step 5: Verify the PHP setup

Before continuing with the Matomo installation, verify that PHP is correctly installed and accessible.

1. Check PHP CLI and confirm PHP runs without errors and the version meets Matomo’s requirements:

php -v

2. Check loaded PHP extensions and verify required extensions are listed such as curl, gd, mbstring, and xml:

php -m

3. If these checks succeed, PHP is ready for Matomo.
4. If you encounter errors, explore the troubleshooting section below.

Troubleshoot Matomo system check errors

After installing or updating PHP, Matomo runs a system check to verify that the server environment meets the requirements. This check runs automatically during installation and updates. The following sections explain how to resolve common PHP-related errors reported by the system check.

You can also access the report at any time under Administration matomo admin gear icon > Diagnostic > System Check.

PHP Configuration

Important settings such as the PHP version, memory limits, and other runtime parameters are defined in your PHP configuration. A common source of confusion is that there are often two separate PHP environments on a server:

  • One used by the command line (CLI)
  • One used by the web server

These environments may use different versions or configuration files.

1. To check the CLI PHP environment, run:

php -v

2. To check the web server PHP environment, follow the instructions under Step 1: Check your PHP setup (at the top of this page).
3. Ensure that both environments meet the required PHP version and configuration settings.
4. If necessary, install or upgrade PHP using your distribution’s package manager.
5. Restart your web server.

PDO extension

Reports if the PHP Data Objects (PDO) extension is not installed or not enabled.

1. Run these commands to resolve the error.
2. Ubuntu:

sudo apt install php-pdo
sudo systemctl restart apache2

3. RHEL-based systems:

sudo dnf install php-pdo
sudo systemctl restart httpd

PDO\MYSQL extension

Reports if the PDO\MYSQL extension is missing and indicates if the PHP MySQL driver is not installed.

1. Run these commands to resolve the error.
2. Ubuntu:

sudo apt install php-mysql
sudo systemctl restart apache2

3. RHEL-based systems:

sudo dnf install php-mysqlnd
sudo systemctl restart httpd

Other required extensions

The system will report if one or more extensions are missing and indicates which required PHP extensions are not installed.

1. Run these commands to install the extensions and resolve the error.
2. Ubuntu:

sudo apt install php-gd php-curl php-mbstring php-xml php-zip
sudo systemctl restart apache2

3. RHEL-based systems:

sudo dnf install php-gd php-curl php-mbstring php-xml php-zip
sudo systemctl restart httpd

Required functions

1. The system will report if there are missing functions.
2. For example, gzcompress and gzuncompress with the PHP zlib extension missing or disabled.
3. Follow the steps in Other required extensions to install and enable the extension, then restart your web server.

PHP setup for Matomo on Linux

Once all system check items pass, PHP is correctly configured for Matomo and both the web server environment and the PHP command-line interface are ready for use. You should be able to complete the Matomo installation and run console commands such as core:archive.

If system check warnings reappear after updates, review this troubleshooting section and restart your web server after making changes. This resolves most PHP-related issues without rebuilding PHP or modifying source code.

Previous FAQ: What is the Trusted Host Check feature in Matomo?