［PHP］opcache_invalidate関数の使い方とベストプラクティス – 効率的なキャッシュ管理術

PHPのOPcacheを使用してパフォーマンスを向上させている際、特定のファイルのキャッシュを無効化したい場面が必ず出てきます。そんな時に威力を発揮するのが opcache_invalidate 関数です。

この記事では、opcache_invalidate 関数の基本的な使い方から実際の開発現場での活用方法まで、実例豊富に解説していきます。

opcache_invalidate関数とは？

opcache_invalidate は、指定したPHPファイルのOPcacheを強制的に無効化（削除）する関数です。ファイルが更新された際に、古いキャッシュを確実にクリアしたい場合に使用します。

基本的な構文

opcache_invalidate(string $filename, bool $force = false): bool

パラメータ:

$filename: 無効化したいPHPファイルのフルパス
$force: 強制的に無効化するかどうか（デフォルト: false）

戻り値:

true: 正常に無効化された、またはファイルがキャッシュされていない
false: 無効化に失敗した

基本的な使い方

1. シンプルな無効化

<?php
// 特定のファイルをキャッシュから削除
$result = opcache_invalidate('/path/to/your/script.php');

if ($result) {
    echo "キャッシュを正常に無効化しました";
} else {
    echo "キャッシュの無効化に失敗しました";
}
?>

2. 強制無効化を使用

<?php
// 強制的にキャッシュを無効化
$result = opcache_invalidate('/path/to/your/script.php', true);

if ($result) {
    echo "強制的にキャッシュを無効化しました";
} else {
    echo "強制無効化に失敗しました";
}
?>

forceパラメータの重要性

$force パラメータは非常に重要な役割を持っています。その違いを理解しましょう。

force = false の場合

<?php
// opcache.validate_timestamps が有効な場合のみ動作
$result = opcache_invalidate('/path/to/script.php', false);

// 本番環境では opcache.validate_timestamps = 0 が一般的なため
// この場合は無効化されない可能性がある
?>

force = true の場合

<?php
// opcache.validate_timestamps の設定に関係なく強制的に無効化
$result = opcache_invalidate('/path/to/script.php', true);

// 本番環境でも確実に無効化される
?>

実践的な活用例

1. ファイルアップロード後の自動無効化

<?php
function deployAndInvalidateCache($filePath, $newContent) {
    // ファイルを更新
    if (file_put_contents($filePath, $newContent) !== false) {
        // キャッシュを無効化
        $invalidateResult = opcache_invalidate($filePath, true);
        
        return [
            'file_updated' => true,
            'cache_invalidated' => $invalidateResult,
            'message' => $invalidateResult ? 
                'ファイル更新とキャッシュクリアが完了しました' : 
                'ファイルは更新されましたが、キャッシュクリアに失敗しました'
        ];
    }
    
    return [
        'file_updated' => false,
        'cache_invalidated' => false,
        'message' => 'ファイルの更新に失敗しました'
    ];
}

// 使用例
$result = deployAndInvalidateCache(
    '/var/www/html/config.php', 
    "<?php\n\$config = ['version' => '2.0'];\n"
);

print_r($result);
?>

2. 開発環境での自動リロード機能

<?php
class DevelopmentCacheManager {
    private $watchedFiles = [];
    
    public function __construct() {
        $this->watchedFiles = $this->getWatchedFiles();
    }
    
    public function checkAndInvalidateModifiedFiles() {
        $invalidated = [];
        
        foreach ($this->watchedFiles as $file => $lastModified) {
            if (file_exists($file)) {
                $currentModified = filemtime($file);
                
                if ($currentModified > $lastModified) {
                    if (opcache_invalidate($file, true)) {
                        $invalidated[] = $file;
                        $this->updateFileTimestamp($file, $currentModified);
                    }
                }
            }
        }
        
        return $invalidated;
    }
    
    private function getWatchedFiles() {
        // 実際の実装では、設定ファイルや環境変数から取得
        return [
            '/var/www/html/app/config.php' => filemtime('/var/www/html/app/config.php'),
            '/var/www/html/app/functions.php' => filemtime('/var/www/html/app/functions.php'),
            // 他の監視対象ファイル...
        ];
    }
    
    private function updateFileTimestamp($file, $timestamp) {
        $this->watchedFiles[$file] = $timestamp;
    }
}

// 使用例
$cacheManager = new DevelopmentCacheManager();
$invalidatedFiles = $cacheManager->checkAndInvalidateModifiedFiles();

if (!empty($invalidatedFiles)) {
    echo "以下のファイルのキャッシュを無効化しました:\n";
    foreach ($invalidatedFiles as $file) {
        echo "- " . basename($file) . "\n";
    }
}
?>

3. 管理画面でのキャッシュ管理

<?php
class AdminCacheManager {
    public function invalidateSpecificFile($filePath) {
        // セキュリティチェック
        if (!$this->isValidPath($filePath)) {
            return [
                'success' => false,
                'message' => '不正なファイルパスです'
            ];
        }
        
        // ファイル存在チェック
        if (!file_exists($filePath)) {
            return [
                'success' => false,
                'message' => 'ファイルが見つかりません'
            ];
        }
        
        // キャッシュされているかチェック
        if (!$this->isFileCached($filePath)) {
            return [
                'success' => true,
                'message' => 'ファイルはキャッシュされていません'
            ];
        }
        
        // 無効化実行
        $result = opcache_invalidate($filePath, true);
        
        return [
            'success' => $result,
            'message' => $result ? 
                'キャッシュを正常に無効化しました' : 
                'キャッシュの無効化に失敗しました'
        ];
    }
    
    public function invalidateDirectory($directoryPath) {
        $invalidated = [];
        $failed = [];
        
        $files = $this->getPhpFilesInDirectory($directoryPath);
        
        foreach ($files as $file) {
            if (opcache_invalidate($file, true)) {
                $invalidated[] = $file;
            } else {
                $failed[] = $file;
            }
        }
        
        return [
            'invalidated' => $invalidated,
            'failed' => $failed,
            'total_processed' => count($files)
        ];
    }
    
    private function isValidPath($path) {
        // セキュリティチェック：許可されたディレクトリ内のファイルかどうか
        $allowedPaths = ['/var/www/html/', '/opt/app/'];
        
        foreach ($allowedPaths as $allowedPath) {
            if (strpos(realpath($path), realpath($allowedPath)) === 0) {
                return true;
            }
        }
        
        return false;
    }
    
    private function isFileCached($filePath) {
        $status = opcache_get_status(true);
        return isset($status['scripts'][$filePath]);
    }
    
    private function getPhpFilesInDirectory($directory) {
        $files = [];
        $iterator = new RecursiveIteratorIterator(
            new RecursiveDirectoryIterator($directory)
        );
        
        foreach ($iterator as $file) {
            if ($file->isFile() && $file->getExtension() === 'php') {
                $files[] = $file->getPathname();
            }
        }
        
        return $files;
    }
}

// 管理画面での使用例
if ($_POST['action'] === 'invalidate_file') {
    $manager = new AdminCacheManager();
    $result = $manager->invalidateSpecificFile($_POST['file_path']);
    
    header('Content-Type: application/json');
    echo json_encode($result);
    exit;
}
?>

デプロイメント時の活用

Git フック連携

<?php
// post-receive フック内で使用するスクリプト例
function invalidateChangedFiles($gitLogOutput) {
    $changedFiles = [];
    $lines = explode("\n", $gitLogOutput);
    
    foreach ($lines as $line) {
        if (preg_match('/\.php$/', $line)) {
            $filePath = '/var/www/html/' . trim($line);
            if (file_exists($filePath)) {
                $changedFiles[] = $filePath;
            }
        }
    }
    
    $results = [];
    foreach ($changedFiles as $file) {
        $results[$file] = opcache_invalidate($file, true);
    }
    
    return $results;
}

// 使用例（Gitフックから呼び出し）
$gitDiff = shell_exec('git diff-tree --no-commit-id --name-only -r HEAD');
$invalidationResults = invalidateChangedFiles($gitDiff);

// ログ出力
foreach ($invalidationResults as $file => $success) {
    $status = $success ? 'SUCCESS' : 'FAILED';
    error_log("OPcache invalidation {$status}: {$file}");
}
?>

デプロイメントスクリプト

<?php
class DeploymentCacheManager {
    private $logFile;
    
    public function __construct($logFile = '/var/log/opcache_deployment.log') {
        $this->logFile = $logFile;
    }
    
    public function performDeployment($appPath) {
        $this->log('Deployment started');
        
        // 1. 現在のキャッシュ状態を記録
        $preDeployStatus = $this->getCacheStatus();
        $this->log('Pre-deployment cache status recorded');
        
        // 2. アプリケーションファイルのキャッシュを全て無効化
        $invalidationResults = $this->invalidateApplicationFiles($appPath);
        $this->log('Application cache invalidated: ' . 
                   json_encode($invalidationResults));
        
        // 3. 新しいファイルが正常に動作することを確認
        $healthCheck = $this->performHealthCheck();
        
        if (!$healthCheck['success']) {
            $this->log('Health check failed: ' . $healthCheck['message']);
            return false;
        }
        
        // 4. デプロイメント完了
        $postDeployStatus = $this->getCacheStatus();
        $this->log('Post-deployment cache status: ' . 
                   json_encode($postDeployStatus));
        $this->log('Deployment completed successfully');
        
        return true;
    }
    
    private function invalidateApplicationFiles($appPath) {
        $results = [
            'invalidated' => 0,
            'failed' => 0,
            'files' => []
        ];
        
        $phpFiles = $this->findPhpFiles($appPath);
        
        foreach ($phpFiles as $file) {
            $success = opcache_invalidate($file, true);
            
            if ($success) {
                $results['invalidated']++;
            } else {
                $results['failed']++;
            }
            
            $results['files'][$file] = $success;
        }
        
        return $results;
    }
    
    private function findPhpFiles($directory) {
        $files = [];
        $iterator = new RecursiveIteratorIterator(
            new RecursiveDirectoryIterator($directory),
            RecursiveIteratorIterator::LEAVES_ONLY
        );
        
        foreach ($iterator as $file) {
            if ($file->isFile() && 
                pathinfo($file->getFilename(), PATHINFO_EXTENSION) === 'php') {
                $files[] = $file->getPathname();
            }
        }
        
        return $files;
    }
    
    private function getCacheStatus() {
        $status = opcache_get_status();
        return [
            'enabled' => $status['opcache_enabled'],
            'hit_rate' => $status['opcache_statistics']['opcache_hit_rate'],
            'cached_scripts' => $status['opcache_statistics']['num_cached_scripts'],
            'memory_usage' => $status['memory_usage']['used_memory']
        ];
    }
    
    private function performHealthCheck() {
        // 簡単なヘルスチェック例
        try {
            $testFile = '/tmp/opcache_test_' . uniqid() . '.php';
            file_put_contents($testFile, '<?php return "OK";');
            
            $result = include $testFile;
            unlink($testFile);
            
            return [
                'success' => $result === 'OK',
                'message' => 'Health check passed'
            ];
        } catch (Exception $e) {
            return [
                'success' => false,
                'message' => 'Health check failed: ' . $e->getMessage()
            ];
        }
    }
    
    private function log($message) {
        $timestamp = date('Y-m-d H:i:s');
        file_put_contents($this->logFile, 
                         "[{$timestamp}] {$message}\n", 
                         FILE_APPEND | LOCK_EX);
    }
}

// 使用例
$deploymentManager = new DeploymentCacheManager();
$success = $deploymentManager->performDeployment('/var/www/html');

if ($success) {
    echo "デプロイメントが正常に完了しました\n";
} else {
    echo "デプロイメントに失敗しました\n";
    exit(1);
}
?>

パフォーマンス考慮事項

1. 一括無効化の最適化

<?php
function batchInvalidateFiles($files) {
    $startTime = microtime(true);
    $results = [];
    
    // バッチサイズを制限してメモリ使用量を抑制
    $batchSize = 100;
    $batches = array_chunk($files, $batchSize);
    
    foreach ($batches as $batch) {
        foreach ($batch as $file) {
            $results[$file] = opcache_invalidate($file, true);
        }
        
        // 短い休息を入れてCPU負荷を分散
        usleep(1000); // 1ms
    }
    
    $endTime = microtime(true);
    
    return [
        'results' => $results,
        'execution_time' => $endTime - $startTime,
        'total_files' => count($files)
    ];
}
?>

エラーハンドリングとログ管理

包括的なエラーハンドリング

<?php
class SafeOpcacheInvalidator {
    private $logger;
    
    public function __construct($logFile = null) {
        $this->logger = $logFile ?? '/var/log/opcache_invalidation.log';
    }
    
    public function safeInvalidate($filePath, $force = true) {
        try {
            // 前提条件チェック
            if (!function_exists('opcache_invalidate')) {
                throw new RuntimeException('OPcache extension is not available');
            }
            
            if (!file_exists($filePath)) {
                throw new InvalidArgumentException("File does not exist: {$filePath}");
            }
            
            // 正規化されたパスを取得
            $realPath = realpath($filePath);
            if ($realPath === false) {
                throw new RuntimeException("Unable to resolve real path for: {$filePath}");
            }
            
            // 無効化実行
            $result = opcache_invalidate($realPath, $force);
            
            // 結果をログに記録
            $this->log('SUCCESS', $realPath, $force, $result);
            
            return [
                'success' => true,
                'file' => $realPath,
                'invalidated' => $result
            ];
            
        } catch (Exception $e) {
            $this->log('ERROR', $filePath ?? 'unknown', $force, false, $e->getMessage());
            
            return [
                'success' => false,
                'file' => $filePath,
                'error' => $e->getMessage()
            ];
        }
    }
    
    private function log($level, $file, $force, $result, $error = null) {
        $timestamp = date('Y-m-d H:i:s');
        $forceStr = $force ? 'TRUE' : 'FALSE';
        $resultStr = $result ? 'SUCCESS' : 'FAILED';
        
        $message = "[{$timestamp}] {$level}: File={$file}, Force={$forceStr}, Result={$resultStr}";
        
        if ($error) {
            $message .= ", Error={$error}";
        }
        
        file_put_contents($this->logger, $message . "\n", FILE_APPEND | LOCK_EX);
    }
}

// 使用例
$invalidator = new SafeOpcacheInvalidator();
$result = $invalidator->safeInvalidate('/path/to/file.php');

if (!$result['success']) {
    echo "無効化に失敗しました: " . $result['error'];
}
?>

ベストプラクティス

1. 本番環境での使用指針

<?php
// 本番環境用の設定
if (getenv('APP_ENV') === 'production') {
    // 本番環境では必ずforce=trueを使用
    $result = opcache_invalidate($file, true);
} else {
    // 開発環境ではforce=falseでも動作する場合がある
    $result = opcache_invalidate($file, false);
}
?>

2. 監視とアラート

<?php
function monitorInvalidationHealth() {
    $recentFailures = 0;
    $logFile = '/var/log/opcache_invalidation.log';
    
    if (file_exists($logFile)) {
        $logs = file($logFile, FILE_IGNORE_NEW_LINES);
        $recent = array_slice($logs, -100); // 最新100行をチェック
        
        foreach ($recent as $line) {
            if (strpos($line, 'FAILED') !== false) {
                $recentFailures++;
            }
        }
    }
    
    if ($recentFailures > 10) {
        // アラート送信
        error_log("High OPcache invalidation failure rate: {$recentFailures} failures in recent operations");
        // 実際の環境では、メール送信やSlack通知など
    }
    
    return $recentFailures;
}
?>