How to configure PHP OPcache for production performance

Enable OPcache to speed up your PHP application by caching compiled bytecode. Follow these steps to install, configure, and verify OPcache on Ubuntu 24.04 with PHP 8.3.

Prerequisites

• Ubuntu 24.04 LTS or Debian 12
• PHP 8.3.x installed via the official packages repository
• Root or sudo access to modify configuration files
• An active web server (Apache or Nginx) running PHP-FPM

Step 1: Install the OPcache extension

Install the PHP OPcache extension using the package manager. This command ensures the extension is available for the PHP version you are currently using.

sudo apt update
sudo apt install php-opcache

You will see output indicating the packages are being downloaded and installed. Ensure the process completes without errors.

Step 2: Locate the PHP configuration file

Find the main configuration file for your PHP installation. On Ubuntu systems using the standard packages, this file is typically located in the /etc/php/ directory.

ls /etc/php/8.3/mods-available/

You will see a file named opcache.ini in the output list. This is the configuration file you need to edit.

Step 3: Enable OPcache in the configuration file

Open the configuration file in a text editor using sudo privileges. You need to enable the extension and set the initial configuration parameters.

sudo nano /etc/php/8.3/mods-available/opcache.ini

Ensure the line starting with extension=opcache is uncommented. If it is commented out with a semicolon, remove the semicolon.

Step 4: Set OPcache memory limits

Adjust the memory allocation settings to fit your server's available RAM. Set the opcache.memory_consumption directive to 256 to allocate 256 megabytes for the cache.

opcache.memory_consumption=256

Set opcache.max_accelerated_files to 10000 to allow caching of up to 10,000 files. This prevents the cache from running out of space prematurely.

opcache.max_accelerated_files=10000

Set opcache.interned_strings_buffer to 16 to allocate 16 megabytes for interned string storage.

opcache.interned_strings_buffer=16

Step 5: Configure the cache directory

Define the directory where OPcache stores its data. Create a dedicated directory for cache files to keep your web root clean.

sudo mkdir -p /var/cache/php-opcache

Set ownership of the new directory to the www-data user and group, which is the standard user for web servers.

sudo chown -R www-data:www-data /var/cache/php-opcache

Update the opcache.save_dir directive in the configuration file to point to this new directory.

opcache.save_dir=/var/cache/php-opcache

Enable the opcache.revalidate_freq setting to 60. This tells the cache to check for file changes every 60 seconds.

opcache.revalidate_freq=60

Set opcache.validate_timestamps to 1. This is required for development and staging environments so the cache updates when source files change.

opcache.validate_timestamps=1

Disable logging for production environments to reduce disk I/O. Set opcache.log_verbosity_level to 1 to suppress verbose error messages.

opcache.log_verbosity_level=1

Step 6: Apply the changes

Restart the PHP-FPM service to apply the new configuration. This action loads the updated settings into memory.

sudo systemctl restart php8.3-fpm

If you are using Apache as a reverse proxy or integrated with PHP, restart the Apache service as well.

sudo systemctl restart apache2

Verify the installation

Create a test file to verify that OPcache is active and functioning correctly. Create a file named opcache_test.php in your web root directory.

sudo nano /var/www/html/opcache_test.php

Add the following code to the file to check the status of the cache.

Access the file via your web browser or using curl. You should see output indicating that OPcache is enabled and displaying memory usage statistics.

curl http://your-domain.com/opcache_test.php

Expected output:

OPcache Status: Enabled
Memory Usage: 25.12 MB
Cached Files: 5
Hit Rate: 100.00%

Troubleshooting

If OPcache does not appear enabled, check the PHP error log for syntax errors in the configuration file. Run the following command to check for syntax errors in the configuration file before restarting services.

php -l /etc/php/8.3/mods-available/opcache.ini

If the command returns "No syntax errors detected in opcache.ini", the file is valid. If it reports an error, correct the syntax and restart the service.

If you are using Nginx, ensure the PHP-FPM socket or port is accessible. Check the Nginx error log for connection refused errors related to PHP-FPM.

sudo tail -f /var/log/nginx/error.log

Ensure the cache directory has the correct permissions. If the directory is not writable by the web server user, OPcache will fail to write data. Run the following command to verify permissions.

ls -ld /var/cache/php-opcache

The output should show ownership by www-data:www-data. If it is owned by root, run the following command to fix ownership.

sudo chown -R www-data:www-data /var/cache/php-opcache

For high-traffic production environments, consider increasing the memory consumption value. Monitor the opcache.memory_usage metric to ensure you are not hitting the memory limit. If the cache is full, the hit rate will drop to zero. Adjust opcache.memory_consumption upwards to accommodate more files.

Ensure that opcache.validate_timestamps is set to 0 for production environments where performance is critical and file changes are rare. This prevents unnecessary file system checks on every request.

opcache.validate_timestamps=0

Finally, verify that the OPcache extension is loaded in the main PHP configuration. Run the following command to list all loaded extensions.

php -m | grep opcache

The output must include opcache. If it is missing, the extension is not loaded. Check the opcache.enable directive to ensure it is set to 1.

php -i | grep opcache.enable

Ensure the value is 1. If it is 0, add opcache.enable=1 to the configuration file and restart PHP-FPM.