@@ -14,7 +14,8 @@ Changes since [v1.6.0](https://github.com/gitonomy/gitlib/releases/tag/v1.6.0).
   `Repository`/`Admin`. It avoids spawning a `git` process for every operation; see
   ["Choosing a driver"](doc/repository.md#choosing-a-driver) for its requirements, its
   differences with the `'cli'` driver, and when it is faster. `benchmark.php` compares both
-  drivers on a repository. ([#253](https://github.com/gitonomy/gitlib/pull/253))
+  drivers on a repository. With php-fpm, `LibGit2DriverFactory::preload()` keeps libgit2 loaded
+  from `opcache.preload`. ([#253](https://github.com/gitonomy/gitlib/pull/253))
 - The `'driver'` option also accepts a configured driver factory (`Driver\Cli\CliDriverFactory`,
   `Driver\Ffi\LibGit2DriverFactory`, or any `Driver\DriverFactoryInterface`), to configure the
   backend or to replace it in tests; see
 
@@ -140,12 +140,25 @@ Differences with the `'cli'` driver:
 -   Rename detection in diffs may pair files differently.
 -   Blame line ranges are limited to `<start>,<end>` and `<start>,+<count>`.
 
-The `ffi.enable` PHP setting defaults to `preload`: outside the CLI
-(php-fpm...), only preloaded code can use FFI, and the `'ffi'` driver throws
-an `UnsupportedOperationException`. Either preload gitlib's sources through
-[`opcache.preload`](https://www.php.net/manual/en/opcache.preloading.php), or
-set `ffi.enable` to `true`, which lets any code of the application call C
-functions.
+#### With php-fpm
+
+Call `LibGit2DriverFactory::preload()` from the
+[`opcache.preload`](https://www.php.net/manual/en/opcache.preloading.php)
+script, with the library path you give to `LibGit2DriverFactory`, if any:
+
+```php
+// preload.php
+require __DIR__.'/vendor/autoload.php';
+
+Gitonomy\Git\Driver\Ffi\LibGit2DriverFactory::preload();
+```
+
+libgit2 then stays loaded and initialized for the lifetime of php-fpm,
+instead of every request loading it again (about 10 ms, see below), and the
+driver works with the default `ffi.enable` setting, `preload`: outside the
+CLI, only preloaded code can use FFI. Without preloading, the `'ffi'` driver
+throws an `UnsupportedOperationException` unless `ffi.enable` is `true`,
+which lets any code of the application call C functions.
 
 ### Performance
 
@@ -180,9 +193,10 @@ an AMD Ryzen AI 9 HX 370.
 -   The `'ffi'` driver reads objects (commits, files, references) 2 to 28
     times faster: no process to start.
 -   Loading libgit2 costs about 10 ms, mostly libgit2 setting up OpenSSL,
-    which reads the system's CA certificates. PHP frees it at the end of
-    every request: with php-fpm, each request pays it again, so a request
-    running a few operations isn't faster. A worker or a command pays it once.
+    which reads the system's CA certificates. A command or a worker pays it
+    once. PHP unloads libgit2 at the end of every request: with php-fpm, each
+    request pays it again, unless
+    [libgit2 is preloaded](#with-php-fpm), which brings it down to 0.1 ms.
 -   libgit2 doesn't use git's commit-graph, and caches objects per
     repository only: walking a long history (counting commits, finding the
     branches including a commit, logging a path) is up to 60 times slower.
 
@@ -45,7 +45,7 @@ final class LibGit2
 
     /**
      * Loads libgit2 once per request (the whole process with the CLI) and per
-     * library path.
+     * library path, or takes the one preload() loaded.
      *
      * @throws UnsupportedOperationException The FFI extension or libgit2 1.9 is missing, or "ffi.enable" restricts FFI
      */
@@ -56,6 +56,40 @@ public static function load(?string $libraryPath): \FFI
         return $ffiByLibraryPath[$libraryPath ?? ''] ??= self::doLoad($libraryPath);
     }
 
+    /**
+     * Loads and initializes libgit2 for the whole process, from the
+     * opcache.preload script: PHP unloads a library at the end of every
+     * request otherwise, and libgit2 initializes itself again (about 10 ms).
+     *
+     * @throws UnsupportedOperationException The FFI extension or libgit2 1.9 is missing
+     */
+    public static function preload(?string $libraryPath): void
+    {
+        self::assertFfiIsAvailable();
+        $path = $libraryPath ?? self::locate();
+        self::assertSupportedVersion($path);
+
+        // FFI::load() reads the library to load from the header.
+        $header = tempnam(sys_get_temp_dir(), 'gitlib-libgit2-');
+
+        try {
+            file_put_contents($header, \sprintf("#define FFI_SCOPE \"%s\"\n#define FFI_LIB \"%s\"\n", self::scope($libraryPath), $path).file_get_contents(__DIR__.'/libgit2.h'));
+            $ffi = \FFI::load($header);
+        } catch (\FFI\Exception $e) {
+            throw new UnsupportedOperationException(\sprintf('Unable to preload libgit2 from "%s".', $path), 0, $e);
+        } finally {
+            unlink($header);
+        }
+
+        // FFI::load() only warns while preloading.
+        if (null === $ffi) {
+            throw new UnsupportedOperationException(\sprintf('Unable to preload libgit2 from "%s".', $path));
+        }
+
+        // Once for the forked processes (php-fpm workers...) too.
+        self::initialize($ffi);
+    }
+
     /**
      * @throws DriverException When $rc is a libgit2 error code
      */
@@ -87,6 +121,45 @@ public static function oidToHex(\FFI $ffi, CData $oid): string
     }
 
     private static function doLoad(?string $libraryPath): \FFI
+    {
+        self::assertFfiIsAvailable();
+
+        $ffi = self::preloaded($libraryPath) ?? self::define($libraryPath ?? self::locate());
+        // Only counts one more user once libgit2 is initialized.
+        self::initialize($ffi);
+
+        return $ffi;
+    }
+
+    /**
+     * @return \FFI|null What preload() loaded for $libraryPath, if it was called
+     */
+    private static function preloaded(?string $libraryPath): ?\FFI
+    {
+        try {
+            return \FFI::scope(self::scope($libraryPath));
+        } catch (\FFI\Exception) {
+            return null;
+        }
+    }
+
+    private static function define(string $libraryPath): \FFI
+    {
+        self::assertSupportedVersion($libraryPath);
+
+        try {
+            return \FFI::cdef(file_get_contents(__DIR__.'/libgit2.h'), $libraryPath);
+        } catch (\FFI\Exception $e) {
+            throw new UnsupportedOperationException(\sprintf('Unable to load libgit2 from "%s"; use the "cli" driver.', $libraryPath), 0, $e);
+        }
+    }
+
+    private static function scope(?string $libraryPath): string
+    {
+        return 'gitonomy/gitlib:'.($libraryPath ?? '');
+    }
+
+    private static function assertFfiIsAvailable(): void
     {
         if (!\extension_loaded('ffi')) {
             throw new UnsupportedOperationException('The "ffi" driver requires the FFI extension; use the "cli" driver.');
@@ -96,36 +169,32 @@ private static function doLoad(?string $libraryPath): \FFI
             \FFI::cdef();
         } catch (\FFI\Exception $e) {
             // ffi.enable defaults to "preload": outside the CLI, only preloaded code can use FFI.
-            throw new UnsupportedOperationException('The "ffi.enable" setting restricts the FFI API: set it to "true", preload gitlib, or use the "cli" driver.', 0, $e);
+            throw new UnsupportedOperationException('The "ffi.enable" setting restricts the FFI API: call LibGit2DriverFactory::preload() from the opcache.preload script, set "ffi.enable" to "true", or use the "cli" driver.', 0, $e);
         }
+    }
 
-        $libraryPath ??= self::locate();
-
+    private static function assertSupportedVersion(string $libraryPath): void
+    {
         try {
-            $versionFfi = \FFI::cdef('int git_libgit2_version(int *major, int *minor, int *rev);', $libraryPath);
+            $ffi = \FFI::cdef('int git_libgit2_version(int *major, int *minor, int *rev);', $libraryPath);
         } catch (\FFI\Exception $e) {
             throw new UnsupportedOperationException(\sprintf('Unable to load libgit2 from "%s"; use the "cli" driver.', $libraryPath), 0, $e);
         }
 
-        $major = $versionFfi->new('int');
-        $minor = $versionFfi->new('int');
-        $rev = $versionFfi->new('int');
-        $versionFfi->git_libgit2_version(\FFI::addr($major), \FFI::addr($minor), \FFI::addr($rev));
+        $major = $ffi->new('int');
+        $minor = $ffi->new('int');
+        $rev = $ffi->new('int');
+        $ffi->git_libgit2_version(\FFI::addr($major), \FFI::addr($minor), \FFI::addr($rev));
         if (self::SUPPORTED_VERSION !== [$major->cdata, $minor->cdata]) {
             throw new UnsupportedOperationException(\sprintf('The "ffi" driver requires libgit2 %s, but "%s" is libgit2 %d.%d.%d; use the "cli" driver.', implode('.', self::SUPPORTED_VERSION), $libraryPath, $major->cdata, $minor->cdata, $rev->cdata));
         }
+    }
 
-        try {
-            $ffi = \FFI::cdef(file_get_contents(__DIR__.'/libgit2.h'), $libraryPath);
-        } catch (\FFI\Exception $e) {
-            throw new UnsupportedOperationException(\sprintf('Unable to load libgit2 from "%s"; use the "cli" driver.', $libraryPath), 0, $e);
-        }
-
+    private static function initialize(\FFI $ffi): void
+    {
         if ($ffi->git_libgit2_init() < 0) {
             throw new UnsupportedOperationException(\sprintf('Unable to initialize libgit2: %s', self::lastErrorMessage($ffi)));
         }
-
-        return $ffi;
     }
 
     private static function locate(): string
 
@@ -43,6 +43,26 @@ public function __construct(?string $libraryPath = null)
         $this->ffi = LibGit2::load($libraryPath);
     }
 
+    /**
+     * To call from the opcache.preload script, with php-fpm for instance:
+     * libgit2 then stays loaded and initialized for the whole process,
+     * instead of every request loading it again (about 10 ms), and the driver
+     * may call FFI whatever "ffi.enable" is.
+     *
+     * @param string|null $libraryPath The libgit2 shared library, as given to the constructor
+     *
+     * @throws UnsupportedOperationException The FFI extension or libgit2 1.9 is missing
+     */
+    public static function preload(?string $libraryPath = null): void
+    {
+        LibGit2::preload($libraryPath);
+
+        // Classes declared while preloading may call FFI, even when
+        // "ffi.enable" is "preload", its default.
+        class_exists(LibGit2Driver::class);
+        class_exists(PathFilter::class);
+    }
+
     public static function isSupported(): bool
     {
         try {
 
@@ -12,6 +12,7 @@
 
 namespace Gitonomy\Git\Tests;
 
+use Gitonomy\Git\Driver\Ffi\LibGit2DriverFactory;
 use PHPUnit\Framework\Attributes\RequiresPhpExtension;
 use PHPUnit\Framework\TestCase;
 use Symfony\Component\Process\Process;
@@ -21,6 +22,8 @@
  */
 class LibGit2DriverFactoryTest extends TestCase
 {
+    private const string AUTOLOAD = __DIR__.'/../../../../vendor/autoload.php';
+
     #[RequiresPhpExtension('ffi')]
     public function testRestrictedFfiApiIsReported(): void
     {
@@ -34,9 +37,34 @@ public function testRestrictedFfiApiIsReported(): void
             }
             PHP;
 
-        $process = new Process([\PHP_BINARY, '-d', 'ffi.enable=0', '-r', $code, __DIR__.'/../../../../vendor/autoload.php']);
+        $process = new Process([\PHP_BINARY, '-d', 'ffi.enable=0', '-r', $code, self::AUTOLOAD]);
+        $process->mustRun();
+
+        $this->assertSame('The "ffi.enable" setting restricts the FFI API: call LibGit2DriverFactory::preload() from the opcache.preload script, set "ffi.enable" to "true", or use the "cli" driver.', $process->getOutput());
+    }
+
+    #[RequiresPhpExtension('ffi')]
+    #[RequiresPhpExtension('Zend OPcache')]
+    public function testPreloadKeepsLibgit2LoadedForTheProcess(): void
+    {
+        if (!LibGit2DriverFactory::isSupported()) {
+            $this->markTestSkipped('libgit2 1.9 is not installed.');
+        }
+
+        $preload = AbstractTestCase::createTempDir().'/preload.php';
+        file_put_contents($preload, \sprintf('<?php require %s; %s::preload();', var_export(self::AUTOLOAD, true), LibGit2DriverFactory::class));
+
+        // FFI::scope() throws unless preload() registered the scope of libgit2.
+        $code = <<<'PHP'
+            require $argv[1];
+            FFI::scope('gitonomy/gitlib:');
+            echo new Gitonomy\Git\Repository($argv[2], ['driver' => 'ffi'])->getHeadCommit()->getHash();
+            PHP;
+
+        $repository = AbstractTestCase::createFoobarRepository();
+        $process = new Process([\PHP_BINARY, '-d', 'opcache.enable_cli=1', '-d', 'opcache.preload='.$preload, '-r', $code, self::AUTOLOAD, $repository->getGitDir()]);
         $process->mustRun();
 
-        $this->assertSame('The "ffi.enable" setting restricts the FFI API: set it to "true", preload gitlib, or use the "cli" driver.', $process->getOutput());
+        $this->assertSame($repository->getHeadCommit()->getHash(), $process->getOutput());
     }
 }