# OPcache Configuration Guide

**Last Updated:** 2026-01-14

## Overview

OPcache is PHP's built-in opcode cache that significantly improves PHP script execution performance by caching compiled PHP code in memory. This guide documents how to enable and configure OPcache for optimal blog performance.

## Benefits

- **2-5x faster PHP script execution** - Compiled code is cached in memory
- **Reduced server load** - Less CPU usage for parsing and compiling PHP
- **Better scalability** - Handles more concurrent requests with same resources

## Configuration

### Apache (.htaccess)

If using Apache with PHP-FPM or mod_php, add to `.htaccess`:

```apache
# Enable OPcache (if using php_flag)
php_flag opcache.enable On
php_value opcache.memory_consumption 128
php_value opcache.interned_strings_buffer 8
php_value opcache.max_accelerated_files 10000
php_value opcache.revalidate_freq 2
php_value opcache.fast_shutdown 1
```

**Note:** `.htaccess` directives may not work depending on server configuration. Check with your hosting provider.

### PHP.ini (Recommended)

For production servers, configure OPcache in `php.ini`:

```ini
[opcache]
; Enable OPcache
opcache.enable=1

; Memory for OPcache (MB)
; 128MB recommended for medium-sized sites
opcache.memory_consumption=128

; Interned strings buffer (MB)
; Reduces memory usage for strings
opcache.interned_strings_buffer=8

; Maximum number of files to cache
; 10000 recommended for sites with many PHP files
opcache.max_accelerated_files=10000

; Revalidate files every N requests
; 0 = always check, 2 = check every 2 requests
opcache.revalidate_freq=2

; Fast shutdown (PHP 7.0.0+)
; Improves performance on shutdown
opcache.fast_shutdown=1

; Validate timestamps
; 1 = check file modification time (development)
; 0 = never check (production, requires manual cache clear)
opcache.validate_timestamps=1

; Save comments
; 1 = preserve docblocks and comments (useful for reflection)
opcache.save_comments=1
```

### Production Settings

For production environments, use more aggressive caching:

```ini
[opcache]
opcache.enable=1
opcache.memory_consumption=256
opcache.interned_strings_buffer=16
opcache.max_accelerated_files=20000
opcache.revalidate_freq=0
opcache.validate_timestamps=0
opcache.fast_shutdown=1
opcache.save_comments=1
```

**Important:** When `opcache.validate_timestamps=0`, you must manually clear OPcache after deploying changes:
- Restart PHP-FPM
- Use `opcache_reset()` function
- Use cache clearing script

## Verification

### Check OPcache Status

Create a PHP file to check OPcache status:

```php
<?php
if (function_exists('opcache_get_status')) {
    $status = opcache_get_status();
    if ($status['opcache_enabled']) {
        echo "OPcache: Enabled\n";
        echo "Memory used: " . round($status['memory_usage']['used_memory'] / 1024 / 1024, 2) . " MB\n";
        echo "Memory free: " . round($status['memory_usage']['free_memory'] / 1024 / 1024, 2) . " MB\n";
        echo "Cached scripts: " . $status['opcache_statistics']['num_cached_scripts'] . "\n";
    } else {
        echo "OPcache: Disabled\n";
    }
} else {
    echo "OPcache: Not available\n";
}
?>
```

### Command Line Check

```bash
php -r "echo 'OPcache enabled: ' . (function_exists('opcache_get_status') ? 'Yes' : 'No') . PHP_EOL;"
```

## Cache Clearing

### Manual Clear (Development)

```php
<?php
if (function_exists('opcache_reset')) {
    opcache_reset();
    echo "OPcache cleared";
} else {
    echo "OPcache not available";
}
?>
```

### Automatic Clear (Production)

For production, restart PHP-FPM after deployments:

```bash
# PHP-FPM
sudo service php-fpm restart

# Or reload (graceful)
sudo service php-fpm reload
```

## Troubleshooting

### OPcache Not Enabled

1. Check PHP version (OPcache available in PHP 5.5+)
2. Verify extension is installed: `php -m | grep opcache`
3. Check `php.ini` configuration
4. Restart PHP-FPM/web server

### Memory Issues

If seeing "OPcache: No memory" errors:

1. Increase `opcache.memory_consumption`
2. Reduce `opcache.max_accelerated_files`
3. Check server memory limits

### Stale Cache

If changes not appearing:

1. Set `opcache.validate_timestamps=1` (development)
2. Clear OPcache manually
3. Restart PHP-FPM

## Best Practices

1. **Development:** Use `opcache.validate_timestamps=1` for automatic cache invalidation
2. **Production:** Use `opcache.validate_timestamps=0` for maximum performance, clear cache on deploy
3. **Memory:** Allocate 128-256MB for OPcache depending on codebase size
4. **Monitoring:** Monitor OPcache hit rate and memory usage regularly

## References

- [PHP OPcache Documentation](https://www.php.net/manual/en/book.opcache.php)
- [OPcache Configuration Options](https://www.php.net/manual/en/opcache.configuration.php)