Skip to content

Improved the main performance article to make it more actionable #7960

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 4 commits into from
Closed

Improved the main performance article to make it more actionable #7960

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
ed86964
Improved the main performance article to make it more actionable
javiereguiluz May 29, 2017
146d9f7
Use another format for the checklist
javiereguiluz May 31, 2017
693847c
Finished the reorganization of the article
javiereguiluz Jun 18, 2017
23942b7
Fixed a typo
javiereguiluz Jun 18, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
290 changes: 149 additions & 141 deletions performance.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,200 +4,210 @@
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. Of course, if you really need speed, the
following performance checklists show how to make your application even faster.

.. 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>`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the performance-use-bootstrap-files label does not seem to exist


Use a Byte Code Cache (e.g. OPcache)
------------------------------------
.. _performance-install-apcu-polyfill:

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.
Install APCu Polyfill if your server uses APC
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Your Server Uses

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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`_.
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.

.. tip::
.. _performance-autoloader-apc-cache:

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.
Enable APC Caching for the Autoloader
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not convinced that we should still recommend the ApcClassLoader anymore. The component will be removed in Symfony 4.0 anyway and you can use Composer to achieve the same. I think we should link to https://getcomposer.org/doc/articles/autoloader-optimization.md instead now that Composer has its own autoloader improvement article.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe mention the commands composer install --apcu-autoloader and/or composer dump-autoload --apcu and link for the rest.
(I tried this in #8098)

ApcClassLoader is deprecated (since 3.3), so I vote against recommending.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Using a byte code cache really has no downside, and Symfony has been designed
to perform really well in this type of environment.
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.

Monitoring Source File Changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To use it, adapt your front controller file to use this ``ApcClassLoader`` class::

// app.php
// ...

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.
$loader = require_once __DIR__.'/../app/bootstrap.php.cache';

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.
// 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);

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.
// ...

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).
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. You either need to restart the web server or 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).
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.

Optimizing all the Files Used by Symfony
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. index::
single: Performance; 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:
.. _performance-use-bootstrap-files:

.. code-block:: ini
Use Bootstrap Files
~~~~~~~~~~~~~~~~~~~

; 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';

By default, PHP sets a ``realpath_cache_size`` of ``16K`` which is too low for
Symfony. Consider updating this value at least to ``4096K``. In addition, cached
paths are only stored for ``120`` seconds by default. Consider updating this
value too using the ``realpath_cache_ttl`` option:
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
realpath_cache_size=4096K
realpath_cache_ttl=600
* when debugging, one will need to place break points inside the bootstrap file.

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::

Even when using a byte code cache, performance will improve when using a
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

indentation should use four spaces

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.

Production Server Checklist
---------------------------

#. :ref:`Use the OPcache byte code cache <performance-use-opcache>`
#. :ref:`Configure OPcache for maximum performance <performance-configure-opcache>`
#. :ref:`Don't check PHP timestamps <performance-dont-check-timestamps>`
#. :ref:`Configure the PHP realpath Cache <performance-configure-realpath-cache>`
#. :ref:`Optimize Composer Autoloader <performance-optimize-composer-autoloader>`

.. index::
single: Performance; Autoloader
single: Performance; Byte code cache

Use Composer's Class Map Functionality
--------------------------------------
.. _performance-use-opcache:

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.
Use the OPcache byte code cache
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Byte Code Cache

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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.
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 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``.
.. _performance-configure-opcache:

The class map can be generated from the command line, and might become part of
your deploy process:
Configure OPcache for maximum performance
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maximum Performance

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: bash
The default OPcache configuration is not suited for Symfony application, so
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

applications

it's recommended to change these settings as follows:

$ composer dump-autoload --optimize --no-dev --classmap-authoritative
.. code-block:: ini

``--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.
; php.ini
; maximum memory that OPcache can use to store compiled PHP files
opcache.memory_consumption=256M

Caching the Autoloader with APC
-------------------------------
; maximum number of files that can be stored in the cache
opcache.max_accelerated_files=20000

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::
.. _performance-dont-check-timestamps:

// app.php
// ...
Don't check PHP timestamps
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Check

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Timestamps

~~~~~~~~~~~~~~~~~~~~~~~~~~

$loader = require_once __DIR__.'/../app/bootstrap.php.cache';
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 caching them. This check introduces some overhead
that can be avoided as follows:

// 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);
*/
.. code-block:: ini

// ...
; php.ini

For more details, see :doc:`/components/class_loader/cache_class_loader`.
; after each deploy, call `opcache_reset()` or restart the web server
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You probably do not restart the web server but the PHP FPM process.

; to empty the cache and regenerate the cached files. Otherwise you won't
; see the updates made in the application
opcache.validate_timestamps=0

.. note::

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.
The OPcache is different for the web server and the command console.
You cannot clear the web server OPcache by executing some command
in your terminal. You either need to restart the web server or call the
``opcache_reset()`` function via the web server (i.e. by having this in
a script that you execute over the web).

.. 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);
.. index::
single: Performance; Autoloader

* when debugging, one will need to place break points inside the bootstrap file.
.. _performance-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.
Optimize Composer Autoloader
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Bootstrap Files and Byte Code Caches
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The class loader used while developing the application is optimized to find
new and changed classes. In production servers, PHP files should never change,
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On production servers [...]

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

and in this section we should link to the article in the Composer documentation

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):

.. 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
----------
Expand All @@ -207,9 +217,7 @@ 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
.. _`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