ez-php/opcache

OPcache preload script generator for the ez-php framework — scans class paths and writes a ready-to-use preload.php

1.3.0 2026-03-29 22:47 UTC

Requires

• php: ^8.5
• ez-php/contracts: ^1.0

Requires (Dev)

• ez-php/docker: ^1.0
• friendsofphp/php-cs-fixer: ^3.94
• phpstan/phpstan: ^2.1
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-strict-rules: ^2.0
• phpunit/phpunit: ^13.0

MIT

• Andreas Uretschnig

• framework
• performance
• php
• Opcache
• preloading
• ez-php

README

OPcache preload script generator for the ez-php framework.

Scans configured class directories and generates a ready-to-use preload.php that can be referenced by PHP's opcache.preload ini directive. Preloading compiles framework classes into shared memory at server startup, eliminating per-request file I/O and compilation overhead.

Installation

composer require ez-php/opcache

Registration

Add the service provider in provider/modules.php:

$app->register(\EzPhp\OPCache\PreloaderServiceProvider::class);

Configuration

Add config/opcache.php:

<?php

return [
    // Absolute path for the generated preload script.
    'output_file' => base_path('preload.php'),

    // Directories to scan for PHP files.
    'paths' => [
        base_path('vendor/ez-php/framework/src'),
        base_path('vendor/ez-php/contracts/src'),
        base_path('app'),
    ],

    // Filename glob patterns to exclude.
    'exclude' => [
        '*Test.php',
        '*TestCase.php',
        '*Interface.php',
    ],

    // Set to true to use require_once instead of opcache_compile_file.
    // Useful when classes have cross-file dependencies that must be resolved
    // in the correct order. Defaults to false.
    'require_once' => false,
];

Generating the preload script

Use the Preloader directly — for example from a Composer script or a deploy step:

use EzPhp\OPCache\PreloadConfig;
use EzPhp\OPCache\Preloader;

$config = new PreloadConfig(
    outputFile: '/var/www/html/preload.php',
    paths: [
        '/var/www/html/vendor/ez-php/framework/src',
        '/var/www/html/vendor/ez-php/contracts/src',
    ],
    excludePatterns: ['*Test.php', '*TestCase.php'],
);

$count = (new Preloader($config))->generate();

echo "Generated preload script with {$count} files.\n";

Or resolve it from the container after bootstrapping the application:

$preloader = $app->make(\EzPhp\OPCache\Preloader::class);
$count = $preloader->generate();

Enabling preloading in php.ini

After generating the script, point PHP to it:

opcache.preload=/var/www/html/preload.php
opcache.preload_user=www-data

Restart PHP-FPM or the web server after each change to the preload script.

Generated script format

<?php

// Auto-generated OPcache preload script.
// Generated by ez-php/opcache at 2026-03-29 12:00:00
// Total files: 42
// Usage: set opcache.preload=<this-file> in php.ini

if (function_exists('opcache_compile_file')) {
    opcache_compile_file('/var/www/html/vendor/ez-php/framework/src/Application.php');
    opcache_compile_file('/var/www/html/vendor/ez-php/framework/src/Container.php');
    // ...
}

Testing

No external services required — all tests run in-process using temporary directories.

composer test

License

MIT