Merge branch '4.0' into update_http_cache

Author: weaverryan

_build/redirection_map

@@ -100,7 +100,8 @@
 /cookbook/bundles/installation /bundles
 /cookbook/bundles/override /bundles/override
 /cookbook/bundles/prepend_extension /bundles/prepend_extension
-/cookbook/bundles/remove /bundles/remove
+/cookbook/bundles/remove /bundles
+/bundles/remove /bundles
 /cookbook/cache/form_csrf_caching /http_cache/form_csrf_caching
 /cookbook/cache/varnish /http_cache/varnish
 /cookbook/composer /setup/composer
@@ -137,18 +138,21 @@
 /cookbook/deployment/platformsh /deployment/platformsh
 /cookbook/deployment/tools /deployment/tools
 /cookbook/doctrine/common_extensions /doctrine/common_extensions
-/cookbook/doctrine/console /doctrine/console
+/cookbook/doctrine/console /doctrine
 /cookbook/doctrine/custom_dql_functions /doctrine/custom_dql_functions
 /cookbook/doctrine/dbal /doctrine/dbal
 /cookbook/doctrine/event_listeners_subscribers /doctrine/event_listeners_subscribers
 /cookbook/doctrine/index /doctrine
-/cookbook/doctrine/mapping_model_classes /doctrine/mapping_model_classes
+/cookbook/doctrine/mapping_model_classes /doctrine
+/doctrine/mapping_model_classes /doctrine
 /cookbook/doctrine/mongodb_session_storage /doctrine/mongodb_session_storage
 /cookbook/doctrine/multiple_entity_managers /doctrine/multiple_entity_managers
 /cookbook/doctrine/pdo_session_storage /doctrine/pdo_session_storage
 /cookbook/doctrine/registration_form /doctrine/registration_form
 /cookbook/doctrine/resolve_target_entity /doctrine/resolve_target_entity
 /cookbook/doctrine/reverse_engineering /doctrine/reverse_engineering
+/doctrine/repository /doctrine
+/doctrine/console /doctrine
 /cookbook/email/cloud /email/cloud
 /cookbook/email/dev_environment /email/dev_environment
 /cookbook/email/email /email
@@ -282,7 +286,8 @@
 /cookbook/workflow/homestead /setup/homestead
 /cookbook/workflow/index /setup
 /cookbook/workflow/new_project_git /setup/new_project_git
-/cookbook/workflow/new_project_svn /setup/new_project_svn
+/cookbook/workflow/new_project_svn /setup/new_project_git
+/setup/new_project_svn /setup/new_project_git
 /components/asset/index /components/asset
 /components/asset/introduction /components/asset
 /components/browser_kit/index /components/browser_kit

best_practices/business-logic.rst

@@ -268,6 +268,10 @@ were defined by the PHP community. You can learn more about
 use the `PHP-CS-Fixer`_, which is a command-line utility that can fix the
 coding standards of an entire codebase in a matter of seconds.
 
+----
+
+Next: :doc:`/best_practices/controllers`
+
 .. _`full definition`: https://en.wikipedia.org/wiki/Business_logic
 .. _`Doctrine project`: http://www.doctrine-project.org/
 .. _`fixture class`: https://symfony.com/doc/current/bundles/DoctrineFixturesBundle/index.html#writing-simple-fixtures

best_practices/configuration.rst

@@ -11,33 +11,33 @@ three parts.
 Infrastructure-Related Configuration
 ------------------------------------
 
+These are the options that change from one machine to another (e.g. from your
+development machine to the production server) but which don't change the
+application behavior.
+
 .. best-practice::
 
-    Define the infrastructure-related configuration options in the
-    ``app/config/parameters.yml`` file.
+    Define the infrastructure-related configuration options as environment
+    variables. During development, use the ``.env`` file at the root of your
+    project to set these.
 
-The default ``parameters.yml`` file follows this recommendation and defines the
-options related to the database and mail server infrastructure:
+By default, Symfony adds these types of options to the ``.env`` file when
+installing new dependencies in the app:
 
-.. code-block:: yaml
+.. code-block:: bash
 
-    # app/config/parameters.yml
-    parameters:
-        database_driver:   pdo_mysql
-        database_host:     127.0.0.1
-        database_port:     ~
-        database_name:     symfony
-        database_user:     root
-        database_password: ~
+    # .env
+    ###> doctrine/doctrine-bundle ###
+    DATABASE_URL=sqlite:///%kernel.project_dir%/var/data/blog.sqlite
+    ###< doctrine/doctrine-bundle ###
 
-        mailer_transport:  smtp
-        mailer_host:       127.0.0.1
-        mailer_user:       ~
-        mailer_password:   ~
+    ###> symfony/swiftmailer-bundle ###
+    MAILER_URL=smtp://localhost?encryption=ssl&auth_mode=login&username=&password=
+    ###< symfony/swiftmailer-bundle ###
 
-        # ...
+    # ...
 
-These options aren't defined inside the ``app/config/config.yml`` file because
+These options aren't defined inside the ``config/services.yaml`` file because
 they have nothing to do with the application's behavior. In other words, your
 application doesn't care about the location of your database or the credentials
 to access to it, as long as the database is correctly configured.
@@ -49,37 +49,32 @@ Canonical Parameters
 
 .. best-practice::
 
-    Define all your application's parameters in the
-    ``app/config/parameters.yml.dist`` file.
+    Define all your application's env vars in the ``.env.dist`` file.
 
-Symfony includes a configuration file called ``parameters.yml.dist``, which
-stores the canonical list of configuration parameters for the application.
+Symfony includes a configuration file called ``.env.dist`` at the project root,
+which stores the canonical list of environment variables for the application.
 
-Whenever a new configuration parameter is defined for the application, you
-should also add it to this file and submit the changes to your version control
-system. Then, whenever a developer updates the project or deploys it to a server,
-Symfony will check if there is any difference between the canonical
-``parameters.yml.dist`` file and your local ``parameters.yml`` file. If there
-is a difference, Symfony will ask you to provide a value for the new parameter
-and it will add it to your local ``parameters.yml`` file.
+Whenever a new env var is defined for the application, you should also add it to
+this file and submit the changes to your version control system so your
+workmates can update their ``.env`` files.
 
 Application-Related Configuration
 ---------------------------------
 
 .. best-practice::
 
     Define the application behavior related configuration options in the
-    ``app/config/config.yml`` file.
+    ``config/services.yaml`` file.
 
-The ``config.yml`` file contains the options used by the application to modify
-its behavior, such as the sender of email notifications, or the enabled
-`feature toggles`_. Defining these values in ``parameters.yml`` file would
-add an extra layer of configuration that's not needed because you don't need
-or want these configuration values to change on each server.
+The ``services.yaml`` file contains the options used by the application to
+modify its behavior, such as the sender of email notifications, or the enabled
+`feature toggles`_. Defining these values in ``.env`` file would add an extra
+layer of configuration that's not needed because you don't need or want these
+configuration values to change on each server.
 
-The configuration options defined in the ``config.yml`` file usually vary from
-one :doc:`environment </configuration/environments>` to another. That's
-why Symfony already includes ``app/config/config_dev.yml`` and ``app/config/config_prod.yml``
+The configuration options defined in the ``services.yaml`` may vary from one
+:doc:`environment </configuration/environments>` to another. That's why Symfony
+supports defining ``config/services_dev.yaml`` and ``config/services_prod.yaml``
 files so that you can override specific values for each environment.
 
 Constants vs Configuration Options
@@ -99,7 +94,7 @@ to control the number of posts to display on the blog homepage:
 
 .. code-block:: yaml
 
-    # app/config/config.yml
+    # config/services.yaml
     parameters:
         homepage.num_items: 10
 
@@ -167,7 +162,7 @@ just one or two words to describe the purpose of the parameter:
 
 .. code-block:: yaml
 
-    # app/config/config.yml
+    # config/services.yaml
     parameters:
         # don't do this: 'dir' is too generic and it doesn't convey any meaning
         app.dir: '...'
@@ -178,37 +173,9 @@ just one or two words to describe the purpose of the parameter:
         app.dir.contents: '...'
         app.contents-dir: '...'
 
-Semantic Configuration: Don't Do It
------------------------------------
-
-.. best-practice::
-
-    Don't define a semantic dependency injection configuration for your bundles.
-
-As explained in :doc:`/bundles/extension` article, Symfony bundles
-have two choices on how to handle configuration: normal service configuration
-through the ``services.yml`` file and semantic configuration through a special
-``*Extension`` class.
-
-Although semantic configuration is much more powerful and provides nice features
-such as configuration validation, the amount of work needed to define that
-configuration isn't worth it for bundles that aren't meant to be shared as
-third-party bundles.
-
-Moving Sensitive Options Outside of Symfony Entirely
-----------------------------------------------------
-
-When dealing with sensitive options, like database credentials, we also recommend
-that you store them outside the Symfony project and make them available
-through environment variables:
-
-.. code-block:: yaml
+----
 
-    # app/config/config.yml
-    doctrine:
-        dbal:
-            # ...
-            password: "%env(DB_PASSWORD)%"
+Next: :doc:`/best_practices/business-logic`
 
 .. _`feature toggles`: https://en.wikipedia.org/wiki/Feature_toggle
 .. _`constant() function`: http://twig.sensiolabs.org/doc/functions/constant.html

best_practices/controllers.rst

@@ -237,4 +237,8 @@ If you need to execute some code before or after the execution of your controlle
 you can use the EventDispatcher component to
 :doc:`set up before and after filters </event_dispatcher/before_after_filters>`.
 
+----
+
+Next: :doc:`/best_practices/templates`
+
 .. _`ParamConverter`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html

best_practices/creating-the-project.rst

@@ -8,7 +8,7 @@ Installing Symfony
 
     Use Composer and Symfony Flex to create and manage Symfony applications.
 
-`Composer`_ is the package manager used by modern PHP application to manage
+`Composer`_ is the package manager used by modern PHP applications to manage
 their dependencies. `Symfony Flex`_ is a Composer plugin designed to automate
 some of the most common tasks performed in Symfony applications. Using Flex is
 optional but recommended because it improves your productivity significantly.
@@ -91,6 +91,10 @@ Symfony applications can still use third-party bundles (installed in ``vendor/``
 to add features, but you should use PHP namespaces instead of bundles to organize
 your own code.
 
+----
+
+Next: :doc:`/best_practices/configuration`
+
 .. _`Composer`: https://getcomposer.org/
 .. _`Symfony Flex`: https://github.com/symfony/flex
 .. _`Symfony Skeleton`: https://github.com/symfony/skeleton

best_practices/forms.rst

@@ -192,3 +192,5 @@ handling the form submit. For example, you *could* have a ``new()`` action that
 *only* renders the form and a ``create()`` action that *only* processes the form
 submit. Both those actions will be almost identical. So it's much simpler to let
 ``new()`` handle everything.
+
+Next: :doc:`/best_practices/i18n`

best_practices/i18n.rst

@@ -76,4 +76,8 @@ English in the application would be:
         </file>
     </xliff>
 
+----
+
+Next: :doc:`/best_practices/security`
+
 .. _`JMSTranslationBundle`: https://github.com/schmittjoh/JMSTranslationBundle

best_practices/introduction.rst

@@ -98,5 +98,9 @@ for not doing it are various:
 * The amount of work spent on this could be better dedicated to improving
   your tests or adding features that provide real value to the end users.
 
+----
+
+Next: :doc:`/best_practices/creating-the-project`
+
 .. _`Fabien Potencier`: https://connect.sensiolabs.com/profile/fabpot
 .. _`Symfony Demo`: https://github.com/symfony/demo

best_practices/security.rst

@@ -385,6 +385,10 @@ If your company uses a user login method not supported by Symfony, you can
 develop :doc:`your own user provider </security/custom_provider>` and
 :doc:`your own authentication provider </security/custom_authentication_provider>`.
 
+----
+
+Next: :doc:`/best_practices/web-assets`
+
 .. _`ParamConverter`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
 .. _`@Security annotation`: https://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/security.html
 .. _`FOSUserBundle`: https://github.com/FriendsOfSymfony/FOSUserBundle

best_practices/templates.rst

@@ -116,5 +116,9 @@ If you're using the :ref:`default services.yaml configuration <service-container
 you're done! Symfony will automatically know about your new service and tag it to
 be used as a Twig extension.
 
+----
+
+Next: :doc:`/best_practices/forms`
+
 .. _`Twig`: http://twig.sensiolabs.org/
 .. _`Parsedown`: http://parsedown.org/

best_practices/web-assets.rst

@@ -25,6 +25,11 @@ the JavaScript-based tools used in modern web applications. Check out the
 `official Webpack Encore documentation`_ to learn more about all the available
 features.
 
+----
+
+Next: :doc:`/best_practices/tests`
+
+.. _`official Assetic documentation`: https://github.com/kriswallsmith/assetic
 .. _`Webpack Encore`: https://github.com/symfony/webpack-encore
 .. _`Webpack`: https://webpack.js.org/
 .. _`official Webpack Encore documentation`: https://symfony.com/doc/current/frontend.html

bundles.rst

@@ -44,7 +44,6 @@ file::
 Learn more
 ----------
 
-* :doc:`/bundles/remove`
 * :doc:`/bundles/override`
 * :doc:`/bundles/best_practices`
 * :doc:`/bundles/configuration`