Merge branch '3.1' into 3.2

* 3.1:
  [#6937] A few small tweaks!
  Porting #6937 back to 2.7
  Remove yourself word in acl doc page
  %kernel.root_dir%/app/data/data.sqlite -> %kernel.root_dir%/data/data.sqlite
  Fix sample sqlite database path in doctrine config
  Fix sample sqlite database path in doctrine config
  Fixed code example wrong prepend() method declaration

Author: weaverryan

performance.rst

@@ -6,39 +6,82 @@ 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 chapter,
-you'll explore many of the most common and powerful ways to make your Symfony
-application even faster.
+you'll explore some of the ways to make your Symfony application even faster.
 
 .. index::
    single: Performance; Byte code cache
 
-Use a Byte Code Cache (e.g. APC)
---------------------------------
+Use a Byte Code Cache (e.g. OPcache)
+------------------------------------
+
+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.
 
-One of the best (and easiest) things that you should do to improve your performance
-is to use a "byte code cache". The idea of a byte code cache is to remove
-the need to constantly recompile the PHP source code. 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 probably `APC`_
+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`_.
 
 Using a byte code cache really has no downside, and Symfony has been architected
 to perform really well in this type of environment.
 
-Further Optimizations
-~~~~~~~~~~~~~~~~~~~~~
+Monitoring Source File Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Byte code caches usually 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 obviously adds overhead.
+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.
 
 For this reason, some byte code caches offer an option to disable these checks.
-Obviously, when disabling these checks, it will be up to the server admin
-to ensure that the cache is cleared whenever any source files change. Otherwise,
-the updates you've made won't be seen.
+For example, to disable these checks in APC, simply add ``apc.stat=0`` to your
+``php.ini`` configuration.
+
+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).
+
+.. 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).
+
+Optimizing all the Files Used by Symfony
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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:
 
-For example, to disable these checks in APC, simply add ``apc.stat=0`` to
-your ``php.ini`` configuration.
+.. code-block:: ini
+
+    ; php.ini
+    opcache.max_accelerated_files = 20000
+
+Configure the PHP realpath Cache
+--------------------------------
+
+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.
+
+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:
+
+.. code-block:: ini
+
+    ; php.ini
+    realpath_cache_size=4096K
+    realpath_cache_ttl=600
 
 .. index::
    single: Performance; Autoloader
@@ -55,15 +98,25 @@ 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.
 
-The simplest solution is to tell Composer to build a "class map" (i.e. a
-big array of the locations of all the classes). This can be done from the
-command line, and might become part of your deploy process:
+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``.
+
+The class map can be generated from the command line, and might become part of
+your deploy process:
 
-.. code-block:: terminal
+.. code-block:: bash
 
-    $ composer dump-autoload --optimize
+    $ composer dump-autoload --optimize --no-dev --classmap-authoritative
 
-Internally, this builds the big class map array in ``vendor/composer/autoload_classmap.php``.
+``--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.
 
 Caching the Autoloader with APC
 -------------------------------
@@ -147,6 +200,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
 .. _`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

reference/configuration/doctrine.rst

@@ -203,7 +203,7 @@ Full Default Configuration
                         password="secret"
                         driver="pdo_mysql"
                         driver-class="MyNamespace\MyDriverImpl"
-                        path="%kernel.data_dir%/data.sqlite"
+                        path="%kernel.root_dir%/../var/data/data.sqlite"
                         memory="true"
                         unix-socket="/tmp/mysql.sock"
                         wrapper-class="MyDoctrineDbalConnectionWrapper"
@@ -395,7 +395,7 @@ The following block shows all possible configuration keys:
                 # the DBAL driverOptions option
                 options:
                     foo: bar
-                path:                 '%kernel.data_dir%/data.sqlite'
+                path:                 '%kernel.root_dir%/data/data.sqlite'
                 memory:               true
                 unix_socket:          /tmp/mysql.sock
                 # the DBAL wrapperClass option
@@ -431,7 +431,7 @@ The following block shows all possible configuration keys:
                     password="secret"
                     driver="pdo_mysql"
                     driver-class="MyNamespace\MyDriverImpl"
-                    path="%kernel.data_dir%/data.sqlite"
+                    path="%kernel.root_dir%/../var/data/data.sqlite"
                     memory="true"
                     unix-socket="/tmp/mysql.sock"
                     wrapper-class="MyDoctrineDbalConnectionWrapper"

security/acl.rst

@@ -22,7 +22,7 @@ the ACL system comes in.
 
 Imagine you are designing a blog system where your users can comment on your
 posts. Now, you want a user to be able to edit their own comments, but not those
-of other users; besides, you yourself want to be able to edit all comments. In
+of other users; besides, you want to be able to edit all comments. In
 this scenario, ``Comment`` would be the domain object that you want to
 restrict access to. You could take several approaches to accomplish this using
 Symfony, two basic approaches are (non-exhaustive):