<?php
include_once $_SERVER['DOCUMENT_ROOT'] . '/include/shared-manual.inc';
$TOC = array();
$TOC_DEPRECATED = array();
$PARENTS = array();
include_once dirname(__FILE__) ."/toc/book.opcache.inc";
$setup = array (
  'home' => 
  array (
    0 => 'index.php',
    1 => 'PHP Manual',
  ),
  'head' => 
  array (
    0 => 'UTF-8',
    1 => 'uk',
  ),
  'this' => 
  array (
    0 => 'opcache.preloading.php',
    1 => 'Preloading',
    2 => 'Preloading',
  ),
  'up' => 
  array (
    0 => 'book.opcache.php',
    1 => 'OPcache',
  ),
  'prev' => 
  array (
    0 => 'opcache.configuration.php',
    1 => 'Налаштування під час виконання',
  ),
  'next' => 
  array (
    0 => 'ref.opcache.php',
    1 => 'Функції OPcache',
  ),
  'alternatives' => 
  array (
  ),
  'source' => 
  array (
    'lang' => 'en',
    'path' => 'reference/opcache/preload.xml',
  ),
  'history' => 
  array (
  ),
);
$setup["toc"] = $TOC;
$setup["toc_deprecated"] = $TOC_DEPRECATED;
$setup["parents"] = $PARENTS;
manual_setup($setup);

contributors($setup);

?>
<div id="opcache.preloading" class="chapter">
 <h1 class="title">Preloading</h1>


 <p class="para">
  As of PHP 7.4.0, PHP can be configured to preload scripts into the opcache when the engine
  starts.  Any functions, classes, interfaces, or traits (but not constants) in those files will then become
  globally available for all requests without needing to be explicitly included.  That trades
  convenience and performance (because the code is always available) for baseline memory usage.  It also
  requires restarting the PHP process to clear pre-loaded scripts, meaning this feature is
  only practical to use in production, not in a development environment.
 </p>

 <p class="para">
  Note that the optimal tradeoff between performance and memory may vary with the application.
  &quot;Preload everything&quot; may be the easiest strategy, but not necessarily the best strategy.  Additionally,
  preloading is only useful when there is a persistent process from one request to another.  That means
  while it can work in a CLI script if the opcache is enabled, it&#039;s generally pointless.  The exception
  is when using preloading on <a href="ffi.examples-complete.php" class="link">FFI libraries</a>.
 </p>

 <blockquote class="note"><p><strong class="note">Зауваження</strong>: 
  <p class="para">
   Preloading is not supported on Windows.
  </p>
 </p></blockquote>

 <p class="para">
  Configuring preloading involves two steps, and requires that the opcache be enabled.
  First, set the <a href="opcache.configuration.php#ini.opcache.preload" class="link">opcache.preload</a>
  value in <var class="filename">php.ini</var>:
 </p>

 <div class="informalexample">
  <div class="example-contents">
<div class="inicode"><pre class="inicode">opcache.preload=preload.php</pre>
</div>
  </div>

 </div>

 <p class="para">
  <var class="filename">preload.php</var> is an arbitrary file that will run once at server startup
  (PHP-FPM, mod_php, etc.) and load code into persistent memory.  In servers that startup as
  root before switching to an unprivileged system user, or if PHP will be run as root
  (not recommended), the <a href="opcache.configuration.php#ini.opcache.preload-user" class="link">opcache.preload_user</a>
  value can specify the system user to run the preloading.  Running preloading as root is not allowed
  by default. Set <code class="literal">opcache.preload_user=root</code> to explicitly allow it.
 </p>

 <p class="para">
  In the <var class="filename">preload.php</var> script, any file referenced by <span class="function"><a href="function.include.php" class="function">include</a></span>,
  <span class="function"><a href="function.include-once.php" class="function">include_once</a></span>, <span class="function"><a href="function.require.php" class="function">require</a></span>, <span class="function"><a href="function.require-once.php" class="function">require_once</a></span>, or
  <span class="function"><a href="function.opcache-compile-file.php" class="function">opcache_compile_file()</a></span> will be parsed into persistent memory.  In the following example,
  all <var class="filename">.php</var> files in the <var class="filename">src</var> directory will be preloaded, unless they
  are a <code class="literal">Test</code> file.
 </p>

 <div class="informalexample">
  <div class="example-contents">
<div class="phpcode"><code><span style="color: #000000"><span style="color: #0000BB">&lt;?php<br />$directory </span><span style="color: #007700">= new </span><span style="color: #0000BB">RecursiveDirectoryIterator</span><span style="color: #007700">(</span><span style="color: #0000BB">__DIR__ </span><span style="color: #007700">. </span><span style="color: #DD0000">'/src'</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$fullTree </span><span style="color: #007700">= new </span><span style="color: #0000BB">RecursiveIteratorIterator</span><span style="color: #007700">(</span><span style="color: #0000BB">$directory</span><span style="color: #007700">);<br /></span><span style="color: #0000BB">$phpFiles </span><span style="color: #007700">= new </span><span style="color: #0000BB">RegexIterator</span><span style="color: #007700">(</span><span style="color: #0000BB">$fullTree</span><span style="color: #007700">, </span><span style="color: #DD0000">'/.+((?&lt;!Test)+\.php$)/i'</span><span style="color: #007700">, </span><span style="color: #0000BB">RecursiveRegexIterator</span><span style="color: #007700">::</span><span style="color: #0000BB">GET_MATCH</span><span style="color: #007700">);<br /><br />foreach (</span><span style="color: #0000BB">$phpFiles </span><span style="color: #007700">as </span><span style="color: #0000BB">$key </span><span style="color: #007700">=&gt; </span><span style="color: #0000BB">$file</span><span style="color: #007700">) {<br />    require_once </span><span style="color: #0000BB">$file</span><span style="color: #007700">[</span><span style="color: #0000BB">0</span><span style="color: #007700">];<br />}<br /></span><span style="color: #0000BB">?&gt;</span></span></code></div>
  </div>

 </div>

 <p class="para">
  Both <span class="function"><a href="function.include.php" class="function">include</a></span> and <span class="function"><a href="function.opcache-compile-file.php" class="function">opcache_compile_file()</a></span> will work, but have different
  implications for how code gets handled.

  <ul class="itemizedlist">
   <li class="listitem"><span class="simpara"><span class="function"><a href="function.include.php" class="function">include</a></span> will execute code in the file,
    while <span class="function"><a href="function.opcache-compile-file.php" class="function">opcache_compile_file()</a></span> will not.  That means only the former supports
    conditional declaration (functions declared inside an if-block).</span></li>
   <li class="listitem"><span class="simpara">Because <span class="function"><a href="function.include.php" class="function">include</a></span> will execute code, nested <span class="function"><a href="function.include.php" class="function">include</a></span>d
    files will also be parsed and their declarations preloaded.</span></li>
   <li class="listitem"><span class="simpara"><span class="function"><a href="function.opcache-compile-file.php" class="function">opcache_compile_file()</a></span> can load files in any order.  That is, if
    <var class="filename">a.php</var> defines  class <code class="literal">A</code> and <var class="filename">b.php</var> defines class
    <code class="literal">B</code> that extends <code class="literal">A</code>, then <span class="function"><a href="function.opcache-compile-file.php" class="function">opcache_compile_file()</a></span> can
    load those two files in any order.  When using <span class="function"><a href="function.include.php" class="function">include</a></span>, however, <var class="filename">a.php</var>
    <em>must</em> be included first.</span></li>
   <li class="listitem"><span class="simpara">In either case, if a later script includes a file that has already been preloaded then
    its contents will still execute, but any symbols it defines will not be re-defined.  Using
    <span class="function"><a href="function.include-once.php" class="function">include_once</a></span> will not prevent the file from being included a second time. It
    may be necessary to load a file again in order to include global constants defined in it, as those are not
    handled by preloading.</span></li>
  </ul>

  Which approach is better therefore depends on the desired behavior.  With code that would otherwise use an
  autoloader, <span class="function"><a href="function.opcache-compile-file.php" class="function">opcache_compile_file()</a></span> allows for greater flexibility.  With code that would
  otherwise be loaded manually, <span class="function"><a href="function.include.php" class="function">include</a></span> will be more robust.
 </p>

</div>
<?php manual_footer($setup); ?>