Merge branch '3.3' into 3.4

* 3.3:
  Reword a code comment
  uploading example: explaining the need for md5
  soap_web_service: code style in examples
  Updated the main performance article to make it more actionable
  Fix typos
  Added a note about using slashes and the special _format param

Author: xabbuh

controller/soap_web_service.rst

@@ -40,8 +40,8 @@ In this case, the SOAP service will allow the client to call a method called
         {
 
             $message = new \Swift_Message('Hello Service')
-                                    ->setTo('me@example.com')
-                                    ->setBody($name . ' says hi!');
+                ->setTo('me@example.com')
+                ->setBody($name.' says hi!');
 
             $this->mailer->send($message);
 

controller/upload_file.rst

@@ -132,8 +132,7 @@ Finally, you need to update the code of the controller that handles the form::
                 /** @var Symfony\Component\HttpFoundation\File\UploadedFile $file */
                 $file = $product->getBrochure();
 
-                // Generate a unique name for the file before saving it
-                $fileName = md5(uniqid()).'.'.$file->guessExtension();
+                $fileName = $this->generateUniqueFileName().'.'.$file->guessExtension();
 
                 // Move the file to the directory where brochures are stored
                 $file->move(
@@ -154,6 +153,16 @@ Finally, you need to update the code of the controller that handles the form::
                 'form' => $form->createView(),
             ));
         }
+        
+        /**
+         * @return string
+         */
+        private function generateUniqueFileName()
+        {
+            // md5() reduces the similarity of the file names generated by
+            // uniqid(), which is based on timestamps
+            return md5(uniqid());
+        }
     }
 
 Now, create the ``brochures_directory`` parameter that was used in the

introduction/from_flat_php_to_symfony2.rst

@@ -580,7 +580,7 @@ nice way to group related pages. The controller functions are also sometimes cal
 The two controllers (or actions) are still lightweight. Each uses the
 :doc:`Doctrine ORM library </doctrine>` to retrieve objects from the
 database and the Templating component to render a template and return a
-``Response`` object. The list ``list.php`` template is now quite a bit simpler:
+``Response`` object. The ``list.php`` template is now quite a bit simpler:
 
 .. code-block:: html+php
 
@@ -623,7 +623,7 @@ The ``layout.php`` file is nearly identical:
 
 .. note::
 
-    The show ``show.php`` template is left as an exercise: updating it should be
+    The ``show.php`` template is left as an exercise: updating it should be
     really similar to updating the ``list.php`` template.
 
 When Symfony's engine (called the Kernel) boots up, it needs a map so
@@ -673,10 +673,10 @@ It's a beautiful thing.
 Better Templates
 ~~~~~~~~~~~~~~~~
 
-If you choose to use it, Symfony comes standard with a templating engine
+If you choose to use it, Symfony comes with a templating engine
 called `Twig`_ that makes templates faster to write and easier to read.
-It means that the sample application could contain even less code! Take,
-for example, rewriting ``list.html.php`` template in Twig would look like
+It means that the sample application could contain even less code! For
+example, rewriting the ``list.html.php`` template in Twig would look like
 this:
 
 .. code-block:: html+twig
@@ -699,7 +699,7 @@ this:
         </ul>
     {% endblock %}
 
-And rewriting ``layout.html.php`` template in Twig would look like this:
+And rewriting the ``layout.html.php`` template in Twig would look like this:
 
 .. code-block:: html+twig
 
@@ -721,9 +721,9 @@ be discussed. For more information, see the :doc:`templating article </templatin
 Where Symfony Delivers
 ----------------------
 
-In the rest of documentation articles, you'll learn more about how each piece of
-Symfony works and how you can organize your project. For now, celebrate at how
-migrating the blog from flat PHP to Symfony has improved life:
+In the rest of the documentation articles, you'll learn more about how each piece of
+Symfony works and how you can organize your project. For now, celebrate how
+migrating the blog from flat PHP to Symfony has improved your life:
 
 * Your application now has **clear and consistently organized code** (though
   Symfony doesn't force you into this). This promotes **reusability** and

performance.rst

@@ -1,130 +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
+---------------------------
+
+#. :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>`
+
+.. _performance-install-apcu-polyfill:
+
+Install APCu Polyfill if your Server Uses 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.
+
+.. _performance-autoloader-apc-cache:
+
+Enable APC Caching for the Autoloader
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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.
+
+To use it, adapt your front controller file like this::
+
+    // app.php
+    // ...
+
+    $loader = require_once __DIR__.'/../app/bootstrap.php.cache';
+
+    // 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::
+
+    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.
 
-Use a Byte Code Cache (e.g. OPcache)
-------------------------------------
+.. _performance-use-bootstrap-files:
 
-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.
+Use Bootstrap Files
+~~~~~~~~~~~~~~~~~~~
 
-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`_.
+.. caution::
 
-.. tip::
+    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.
 
-    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.
+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.
 
-Using a byte code cache really has no downside, and Symfony has been designed
-to perform really well in this type of environment.
+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::
 
-Monitoring Source File Changes
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    require_once __DIR__.'/../app/bootstrap.php.cache';
 
-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.
+Note that there are two disadvantages when using a bootstrap file:
 
-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.
+* the file needs to be regenerated whenever any of the original sources change
+  (i.e. when you update the Symfony source or vendor libraries);
 
-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.
+* when debugging, one will need to place break points inside the bootstrap file.
 
-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).
+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::
 
-    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:
+  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.
 
-    #. 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-opcache:
 
-Optimizing all the Files Used by Symfony
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Use the OPcache Byte Code Cache
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-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:
+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`_.
+
+.. _performance-configure-opcache:
+
+Configure OPcache for Maximum Performance
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The default OPcache configuration is not suited for Symfony applications, so
+it's recommended to change these settings as follows:
 
 .. code-block:: ini
 
     ; php.ini
-    opcache.max_accelerated_files = 20000
+    ; maximum memory that OPcache can use to store compiled PHP files
+    opcache.memory_consumption=256M
 
-Configure the PHP realpath Cache
---------------------------------
+    ; maximum number of files that can be stored in the cache
+    opcache.max_accelerated_files=20000
+
+.. _performance-dont-check-timestamps:
 
-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.
+Don't Check PHP Files Timestamps
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Consider increasing the ``realpath_cache_size`` and ``realpath_cache_ttl``:
+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
 
     ; php.ini
-    ; 4096k is the default value in PHP 7.2
-    realpath_cache_size=4096K
-    realpath_cache_ttl=600
+    opcache.validate_timestamps=0
 
-.. index::
-   single: Performance; Autoloader
+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:
+
+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.
+
+.. _performance-configure-realpath-cache:
 
-Use Composer's Class Map Functionality
---------------------------------------
+Configure the PHP realpath Cache
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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:
+
+.. code-block:: ini
+
+    ; php.ini
+    ; maximum memory allocated to store the results
+    realpath_cache_size=4096K
+
+    ; save the results for 10 minutes (600 seconds)
+    realpath_cache_ttl=600
 
-Symfony uses Composer's autoloader. This autoloader is easy to use, as it will
-automatically find any new classes that you've placed in the registered
-directories.
+.. _performance-optimize-composer-autoloader:
 
-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.
+Optimize Composer Autoloader
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The simplest solution is to tell Composer to build an optimized "class map",
+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``.
 
-The class map can be generated from the command line, and might become part of
-your deploy process:
+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
 
-``--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.
+* ``--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
 ----------
@@ -134,7 +214,8 @@ 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