Opcache preload

Gacela ships a preload script that loads the framework and the packages it runs on, the container included, into shared memory at PHP startup. Requests no longer compile those files, and they use less memory. Measure the gain on your own workload.

Requires PHP 8.3+ with opcache enabled.

Setup

Add to php.ini (or your FPM pool config):

opcache.enable=1
opcache.preload=/path/to/project/vendor/gacela-project/gacela/resources/gacela-preload.php
opcache.preload_user=www-data

Restart PHP-FPM:

sudo systemctl restart php8.3-fpm

Check the logs for Gacela Opcache Preload: <n> classes linked, 0 skipped. The count tracks the framework's size; the 0 is the part to check.

The line names anything Gacela could not link, and PHP logs its own Can't preload unlinked class ... warning next to it. Both mean PHP dropped the class from the preload image and loads it per request as usual. That breaks the preload only, not your application.

Preload your own files

Create preload/app-preload.php. Load the classes instead of compiling the files. PHP keeps a compiled class only if everything it extends, implements and uses was preloaded too, and loading the class is what pulls those in.

<?php
require_once dirname(__DIR__) . '/vendor/autoload.php';

class_exists(App\User\UserFacade::class);
class_exists(App\Product\ProductFacade::class);

Point an environment variable in your FPM pool at it:

env[GACELA_PRELOAD_USER_FILES] = /path/to/project/preload/app-preload.php

Deployment

PHP reads the preloaded files once, at startup. Restart PHP-FPM after every deploy:

composer install --no-dev --optimize-autoloader
sudo systemctl restart php8.3-fpm

When to use it

Use it for high-traffic production apps on PHP 8.3+.
Skip it in local development (you would restart after every change) and on very low-traffic sites.

Troubleshooting

Symptom	Check
Files not preloading	`php -v` ≥ 8.3, `php -i \| grep opcache.enable`, preload file readable
Permission denied	`opcache.preload_user` must match the PHP-FPM user (`ps aux \| grep php-fpm`)
`Can't preload unlinked class`	A parent, interface or trait was not preloaded. For your own files, load the class instead of compiling the file (above).
Preload aborts on `fopen(php://stdout)` or similar	A package runs I/O in a Composer `files` autoload entry, which the preload context forbids. Install with `--no-dev`, or preload your classes without requiring the full autoloader.
Nothing happens on Windows	`opcache.preload` is not supported there.

Docker

FROM php:8.3-fpm
RUN docker-php-ext-install opcache
COPY docker/opcache.ini /usr/local/etc/php/conf.d/

# docker/opcache.ini
opcache.enable=1
opcache.preload=/var/www/html/vendor/gacela-project/gacela/resources/gacela-preload.php
opcache.preload_user=www-data