PHP OPcache Prune

A simple, lightweight alternative to gordalina/cachetool for clearing PHP OPcache during deployments. This script is designed specifically for cron-style deployments with Deployer and includes a configurable sleep timeout to avoid race conditions in Docker environments with caching I/O layers.

Features

• Simple: Single bash script with minimal dependencies
• Safe: Uses random filenames and automatic cleanup
• Race condition prevention: Configurable sleep timeout before cache clearing
• Docker-friendly: Handles caching I/O layer synchronization issues
• Deployer integration: Perfect for automated deployment workflows
• Error handling: Proper exit codes and error reporting

Why This Tool?

While cachetool is a powerful and feature-rich solution, sometimes you need something simpler and more focused. This script is ideal when:

• You only need OPcache clearing functionality
• You're working in Docker environments with filesystem caching layers
• You need to prevent race conditions between file writes and cache clearing
• You want a lightweight solution for deployment automation
• You're using Deployer and need a simple cache clearing step

How It Works

1. Creates a temporary PHP file in your web root with a random filename
2. Waits for a specified number of seconds (default: 5) to ensure filesystem synchronization
3. Calls the PHP file via HTTP to execute opcache_reset()
4. Cleans up by deleting the temporary file
5. Reports success or failure with proper exit codes

Requirements

• Bash shell
• curl command
• openssl command (for random filename generation)
• Web server with PHP and OPcache extension enabled
• Write permissions to the web root directory

Installation

Simply download the script and make it executable:

curl -O https://raw.githubusercontent.com/cron-eu/php-opcache-prune/refs/heads/master/php-opcache-prune.sh
chmod +x php-opcache-prune.sh

Usage

Basic Usage

./php-opcache-prune.sh /var/www/html https://example.com

With Custom Wait Time

./php-opcache-prune.sh /var/www/html https://example.com 10

Parameters

Parameter	Description	Required	Default
webroot_path	Path to your web application's document root	Yes	-
base_url	Base URL of your web application	Yes	-
wait_seconds	Seconds to wait before calling the cache clear script	No	5

Deployer Integration

Add this to your Deployer deployment script:

<?php
namespace Deployer;

// Define the opcache clear task
task('opcache:clear', function () {
    $webroot = get('deploy_path') . '/current/public';
    $url = get('url');
    $waitTime = get('opcache_wait_time', 5);
    
    run("./php-opcache-prune.sh $webroot $url $waitTime");
})->desc('Clear PHP OPcache');

// Add it to your deployment flow
after('deploy:symlink', 'opcache:clear');

Or run it directly in a deployment task:

task('deploy', [
    'deploy:prepare',
    'deploy:vendors',
    'deploy:publish',
    'opcache:clear',
]);

Docker Considerations

In Docker environments, especially those with overlay filesystems or caching layers, there can be delays between when files are written and when they become visible to the web server. The configurable wait time helps mitigate these race conditions:

# For slower Docker environments, increase wait time
./php-opcache-prune.sh /var/www/html https://example.com 10

Error Codes

Exit Code	Description
0	Success
1	Invalid arguments (missing webroot or URL)
2	Webroot directory not writable
3	HTTP call failed or returned non-2xx response

Security Considerations

• The script uses random filenames to prevent predictable URLs
• Temporary files are automatically cleaned up after use
• The PHP script only exposes OPcache reset functionality
• Files are created with 0644 permissions

Troubleshooting

"opcache_reset() not available"

• Ensure PHP OPcache extension is installed and enabled
• Check that opcache.enable=1 in your PHP configuration

"Webroot not a writable directory"

• Verify the webroot path is correct
• Check directory permissions for the user running the script

HTTP errors

• Verify the base URL is accessible
• Check web server error logs
• Ensure PHP files can be executed in the webroot

Contributing

Feel free to submit issues and enhancement requests!

License

This project is open source and available under the MIT License.