minor #9161 Updated the main performance article to make it more actionable (javiereguiluz)

javiereguiluz · javiereguiluz · commit 2a215c43c617 · 2018-01-30T10:55:36.000+01:00
This PR was squashed before being merged into the 2.7 branch (closes #9161). Discussion ---------- Updated the main performance article to make it more actionable This one finishes and replaces #7960, #8410 and #8332. Commits ------- fa393c5 Updated the main performance article to make it more actionable
diff --git a/performance.rst b/performance.rst
@@ -1,205 +1,210 @@
 .. index::
-   single: Tests
+   single: Performance; Byte code cache; OPcache; APC
 
 Performance
 ===========
 
-Symfony is fast, right out of the box. Of course, if you really need speed,
-there are many ways that you can make Symfony even faster. In this article,
-you'll explore some of the ways to make your Symfony application even faster.
+Symfony is fast, right out of the box. However, you can make it faster if you
+optimize your servers and your applications as explained in the following
+performance checklists.
 
-.. index::
-   single: Performance; Byte code cache
+Symfony Application Checklist
+-----------------------------
+
+#. :ref:`Install APCu Polyfill if your server uses APC <performance-install-apcu-polyfill>`
+#. :ref:`Enable APC Caching for the Autoloader <performance-autoloader-apc-cache>`
+#. :ref:`Use Bootstrap Files <performance-use-bootstrap-files>`
+
+Production Server Checklist
+---------------------------
 
-Use a Byte Code Cache (e.g. OPcache)
-------------------------------------
+#. :ref:`Use the OPcache byte code cache <performance-use-opcache>`
+#. :ref:`Configure OPcache for maximum performance <performance-configure-opcache>`
+#. :ref:`Don't check PHP files timestamps <performance-dont-check-timestamps>`
+#. :ref:`Configure the PHP realpath Cache <performance-configure-realpath-cache>`
+#. :ref:`Optimize Composer Autoloader <performance-optimize-composer-autoloader>`
 
-The first thing that you should do to improve your performance is to use a
-"byte code cache". These caches store the compiled PHP files to avoid having
-to recompile them for every request.
+.. _performance-install-apcu-polyfill:
 
-There are a number of `byte code caches`_ available, some of which are open
-source. As of PHP 5.5, PHP comes with `OPcache`_ built-in. For older versions,
-the most widely used byte code cache is `APC`_.
+Install APCu Polyfill if your Server Uses APC
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-.. tip::
+If your production server still uses the legacy APC PHP extension instead of
+OPcache, install the `APCu Polyfill component`_ in your application to enable
+compatibility with `APCu PHP functions`_ and unlock support for advanced Symfony
+features, such as the APCu Cache adapter.
 
-    If your server still uses the legacy APC PHP extension, install the
-    `APCu Polyfill component`_ in your application to enable compatibility with
-    `APCu PHP functions`_ and unlock support for advanced Symfony features, such
-    as the APCu Cache adapter.
+.. _performance-autoloader-apc-cache:
 
-Using a byte code cache really has no downside, and Symfony has been designed
-to perform really well in this type of environment.
+Enable APC Caching for the Autoloader
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Monitoring Source File Changes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The class autoloading mechanism is one of the slowest parts in PHP applications
+that make use of lots of classes, such as Symfony. A simple way to improve its
+performance is to use the :class:`Symfony\\Component\\ClassLoader\\ApcClassLoader`,
+which caches the location of each class after it's located the first time.
 
-Most byte code caches monitor the source files for changes. This ensures that if
-the source of a file changes, the byte code is recompiled automatically.
-This is really convenient, but it adds overhead.
+To use it, adapt your front controller file like this::
 
-For this reason, some byte code caches offer an option to disable these checks.
-For example, to disable these checks in APC, simply add ``apc.stat=0`` to your
-``php.ini`` configuration.
+    // app.php
+    // ...
 
-When disabling these checks, it will be up to the server administrators to
-ensure that the cache is cleared whenever any source files change. Otherwise,
-the updates you've made in the application won't be seen.
+    $loader = require_once __DIR__.'/../app/bootstrap.php.cache';
 
-For the same reasons, the byte code cache must also be cleared when deploying
-the application (for example by calling ``apc_clear_cache()`` PHP function when
-using APC and ``opcache_reset()`` when using OPcache).
+    // Change 'sf' by something unique to this app to prevent
+    // conflicts with other applications running in the same server
+    $loader = new ApcClassLoader('sf', $loader);
+    $loader->register(true);
+
+    // ...
+
+For more details, see :doc:`/components/class_loader/cache_class_loader`.
 
 .. note::
 
-    In PHP, the CLI and the web processes don't share the same OPcache. This
-    means that you cannot clear the web server OPcache by executing some command
-    in your terminal. These are some of the possible solutions:
+    When using the APC autoloader, if you add new classes, they will be found
+    automatically and everything will work the same as before (i.e. no
+    reason to "clear" the cache). However, if you change the location of a
+    particular namespace or prefix, you'll need to flush your APC cache. Otherwise,
+    the autoloader will still be looking at the old location for all classes
+    inside that namespace.
 
-    #. Restart the web server;
-    #. Call the :phpfunction:`apc_clear_cache` or :phpfunction:`opcache_reset`
-       functions via the web server (i.e. by having these in a script that
-       you execute over the web);
-    #. Use the `cachetool`_ utility to control APC and OPcache from the CLI.
+.. _performance-use-bootstrap-files:
 
-Optimizing all the Files Used by Symfony
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Use Bootstrap Files
+~~~~~~~~~~~~~~~~~~~
 
-By default, PHP's OPcache saves up to 2,000 files in the byte code cache. This
-number is too low for the typical Symfony application, so you should set a
-higher limit with the `opcache.max_accelerated_files`_ configuration option:
+.. caution::
 
-.. code-block:: ini
+    Thanks to the optimizations introduced in PHP 7, bootstrap files are no
+    longer necessary when running your Symfony applications with PHP 7 or a
+    newer PHP version.
 
-    ; php.ini
-    opcache.max_accelerated_files = 20000
+The Symfony Standard Edition includes a script to generate a so-called
+`bootstrap file`_, which is a large file containing the code of the most
+commonly used classes. This saves a lot of IO operations because Symfony no
+longer needs to look for and read those files.
 
-Configure the PHP realpath Cache
---------------------------------
+If you're using the Symfony Standard Edition, then you're probably already
+using the bootstrap file. To be sure, open your front controller (usually
+``app.php``) and check to make sure that the following line exists::
 
-PHP uses an internal cache to store the result of mapping file paths to their
-real and absolute file system paths. This increases the performance for
-applications like Symfony that open many PHP files, especially on Windows
-systems.
+    require_once __DIR__.'/../app/bootstrap.php.cache';
 
-Consider increasing the ``realpath_cache_size`` and ``realpath_cache_ttl``:
+Note that there are two disadvantages when using a bootstrap file:
 
-.. code-block:: ini
+* the file needs to be regenerated whenever any of the original sources change
+  (i.e. when you update the Symfony source or vendor libraries);
 
-    ; php.ini
-    ; 4096k is the default value in PHP 7.2
-    realpath_cache_size=4096K
-    realpath_cache_ttl=600
+* when debugging, one will need to place break points inside the bootstrap file.
 
-.. index::
-   single: Performance; Autoloader
+If you're using the Symfony Standard Edition, the bootstrap file is automatically
+rebuilt after updating the vendor libraries via the ``composer install`` command.
+
+.. note::
 
-Use Composer's Class Map Functionality
---------------------------------------
+  Even when using a byte code cache, performance will improve when using a
+  bootstrap file since there will be fewer files to monitor for changes. Of
+  course, if this feature is disabled in the byte code cache (e.g.
+  ``apc.stat=0`` in APC), there is no longer a reason to use a bootstrap file.
 
-By default, the Symfony Standard Edition uses Composer's autoloader
-in the `autoload.php`_ file. This autoloader is easy to use, as it will
-automatically find any new classes that you've placed in the registered
-directories.
+.. _performance-use-opcache:
 
-Unfortunately, this comes at a cost, as the loader iterates over all configured
-namespaces to find a particular file, making ``file_exists()`` calls until it
-finally finds the file it's looking for.
+Use the OPcache Byte Code Cache
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The simplest solution is to tell Composer to build an optimized "class map",
-which is a big array of the locations of all the classes and it's stored
-in ``vendor/composer/autoload_classmap.php``.
+OPcache stores the compiled PHP files to avoid having to recompile them for
+every request. There are some `byte code caches`_ available, but as of PHP
+5.5, PHP comes with `OPcache`_ built-in. For older versions, the most widely
+used byte code cache is `APC`_.
 
-The class map can be generated from the command line, and might become part of
-your deploy process:
+.. _performance-configure-opcache:
 
-.. code-block:: bash
+Configure OPcache for Maximum Performance
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    $ composer dump-autoload --optimize --no-dev --classmap-authoritative
+The default OPcache configuration is not suited for Symfony applications, so
+it's recommended to change these settings as follows:
 
-``--optimize``
-  Dumps every PSR-0 and PSR-4 compatible class used in your application.
-``--no-dev``
-  Excludes the classes that are only needed in the development environment
-  (e.g. tests).
-``--classmap-authoritative``
-  Prevents Composer from scanning the file system for classes that are not
-  found in the class map.
+.. code-block:: ini
 
-Caching the Autoloader with APC
--------------------------------
+    ; php.ini
+    ; maximum memory that OPcache can use to store compiled PHP files
+    opcache.memory_consumption=256M
 
-Another solution is to cache the location of each class after it's located
-the first time. Symfony comes with a class - :class:`Symfony\\Component\\ClassLoader\\ApcClassLoader` -
-that does exactly this. To use it, just adapt your front controller file.
-If you're using the Standard Distribution, this code should already be available
-as comments in this file::
+    ; maximum number of files that can be stored in the cache
+    opcache.max_accelerated_files=20000
 
-    // app.php
-    // ...
+.. _performance-dont-check-timestamps:
 
-    $loader = require_once __DIR__.'/../app/bootstrap.php.cache';
+Don't Check PHP Files Timestamps
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    // Use APC for autoloading to improve performance
-    // Change 'sf2' by the prefix you want in order
-    // to prevent key conflict with another application
-    /*
-    $loader = new ApcClassLoader('sf2', $loader);
-    $loader->register(true);
-    */
+In production servers, PHP files should never change, unless a new application
+version is deployed. However, by default OPcache checks if cached files have
+changed their contents since they were cached. This check introduces some
+overhead that can be avoided as follows:
 
-    // ...
+.. code-block:: ini
 
-For more details, see :doc:`/components/class_loader/cache_class_loader`.
+    ; php.ini
+    opcache.validate_timestamps=0
 
-.. note::
+After each deploy, you must empty and regenerate the cache of OPcache. Otherwise
+you won't see the updates made in the application. Given than in PHP, the CLI
+and the web processes don't share the same OPcache, you cannot clear the web
+server OPcache by executing some command in your terminal. These are some of the
+possible solutions:
 
-    When using the APC autoloader, if you add new classes, they will be found
-    automatically and everything will work the same as before (i.e. no
-    reason to "clear" the cache). However, if you change the location of a
-    particular namespace or prefix, you'll need to flush your APC cache. Otherwise,
-    the autoloader will still be looking at the old location for all classes
-    inside that namespace.
+1. Restart the web server;
+2. Call the ``apc_clear_cache()`` or ``opcache_reset()`` functions via the
+   web server (i.e. by having these in a script that you execute over the web);
+3. Use the `cachetool`_ utility to control APC and OPcache from the CLI.
 
-.. index::
-   single: Performance; Bootstrap files
+.. _performance-configure-realpath-cache:
 
-Use Bootstrap Files
--------------------
+Configure the PHP realpath Cache
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To ensure optimal flexibility and code reuse, Symfony applications leverage
-a variety of classes and 3rd party components. But loading all of these classes
-from separate files on each request can result in some overhead. To reduce
-this overhead, the Symfony Standard Edition provides a script to generate
-a so-called `bootstrap file`_, consisting of multiple classes definitions
-in a single file. By including this file (which contains a copy of many of
-the core classes), Symfony no longer needs to include any of the source files
-containing those classes. This will reduce disc IO quite a bit.
+When a relative path is transformed into its real and absolute path, PHP
+caches the result to improve performance. The default config of this cache
+is not suited for applications that open many PHP files, such as Symfony.
+It's recommended to change these settings as follows:
 
-If you're using the Symfony Standard Edition, then you're probably already
-using the bootstrap file. To be sure, open your front controller (usually
-``app.php``) and check to make sure that the following line exists::
+.. code-block:: ini
 
-    require_once __DIR__.'/../app/bootstrap.php.cache';
+    ; php.ini
+    ; maximum memory allocated to store the results
+    realpath_cache_size=4096K
 
-Note that there are two disadvantages when using a bootstrap file:
+    ; save the results for 10 minutes (600 seconds)
+    realpath_cache_ttl=600
 
-* the file needs to be regenerated whenever any of the original sources change
-  (i.e. when you update the Symfony source or vendor libraries);
+.. _performance-optimize-composer-autoloader:
 
-* when debugging, one will need to place break points inside the bootstrap file.
+Optimize Composer Autoloader
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you're using the Symfony Standard Edition, the bootstrap file is automatically
-rebuilt after updating the vendor libraries via the ``composer install`` command.
+The class loader used while developing the application is optimized to find
+new and changed classes. In production servers, PHP files should never change,
+unless a new application version is deployed. That's why you can optimize
+Composer's autoloader to scan the entire application once and build a "class map",
+which is a big array of the locations of all the classes and it's stored
+in ``vendor/composer/autoload_classmap.php``.
+
+Execute this command to generate the class map (and make it part of your
+deployment process too):
 
-Bootstrap Files and Byte Code Caches
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. code-block:: bash
+
+    $ composer dump-autoload --optimize --no-dev --classmap-authoritative
 
-Even when using a byte code cache, performance will improve when using a bootstrap
-file since there will be fewer files to monitor for changes. Of course, if this
-feature is disabled in the byte code cache (e.g. ``apc.stat=0`` in APC), there
-is no longer a reason to use a bootstrap file.
+* ``--optimize`` dumps every PSR-0 and PSR-4 compatible class used in your
+  application;
+* ``--no-dev`` excludes the classes that are only needed in the development
+  environment (e.g. tests);
+* ``--classmap-authoritative`` prevents Composer from scanning the file
+  system for classes that are not found in the class map.
 
 Learn more
 ----------
@@ -209,10 +214,9 @@ Learn more
 
 .. _`byte code caches`: https://en.wikipedia.org/wiki/List_of_PHP_accelerators
 .. _`OPcache`: http://php.net/manual/en/book.opcache.php
-.. _`opcache.max_accelerated_files`: http://php.net/manual/en/opcache.configuration.php#ini.opcache.max-accelerated-files
+.. _`bootstrap file`: https://github.com/sensiolabs/SensioDistributionBundle/blob/master/Composer/ScriptHandler.php
+.. _`Composer's autoloader optimization`: https://getcomposer.org/doc/articles/autoloader-optimization.md
 .. _`APC`: http://php.net/manual/en/book.apc.php
 .. _`APCu Polyfill component`: https://github.com/symfony/polyfill-apcu
 .. _`APCu PHP functions`: http://php.net/manual/en/ref.apcu.php
-.. _`autoload.php`: https://github.com/symfony/symfony-standard/blob/master/app/autoload.php
-.. _`bootstrap file`: https://github.com/sensiolabs/SensioDistributionBundle/blob/master/Composer/ScriptHandler.php
 .. _`cachetool`: https://github.com/gordalina/cachetool
