Merge branch 'master' into 27345-lock-mongodb

Author: Joe Bennett

.platform/routes.yaml

@@ -5,10 +5,7 @@
 name: symfonydocs
 
 # The toolstack used to build the application.
-type: "php"
-
-build:
-    flavor: "composer"
+type: "python:3.7"
 
 # The configuration of app when it is exposed to the web.
 web:
@@ -53,7 +50,7 @@ hooks:
     build: |
       virtualenv .virtualenv
       . .virtualenv/bin/activate
-      # Platform.sh currently sets PIP_USER=1.
+      # SymfonyCloud currently sets PIP_USER=1.
       export PIP_USER=
       pip install pip==9.0.1 wheel==0.29.0
       pip install -r _build/.requirements.txt

.platform.app.yaml renamed to .symfony.cloud.yaml

@@ -0,0 +1,11 @@
+https://{default}/:
+  cache:
+    cookies:
+      - '*'
+    default_ttl: 0
+    enabled: true
+    headers:
+      - Accept
+      - Accept-Language
+  type: upstream
+  upstream: symfonydocs:http

.symfony/routes.yaml

@@ -0,0 +1,16 @@
+FROM  python:2-stretch as builder
+
+WORKDIR /www
+
+COPY ./_build/.requirements.txt _build/
+
+RUN pip install  pip==9.0.1 wheel==0.29.0 \
+    && pip install -r _build/.requirements.txt
+
+COPY . /www
+
+RUN make -C _build html
+
+FROM  nginx:latest
+
+COPY --from=builder /www/_build/html /usr/share/nginx/html

.platform/services.yaml renamed to .symfony/services.yaml

@@ -7,15 +7,32 @@ Contributing
 ------------
 
 >**Note**
->Unless you're documenting a feature that was introduced *after* Symfony 2.8
->(e.g. in Symfony 3.4), all pull requests must be based off of the **2.8** branch,
+>Unless you're documenting a feature that was introduced *after* Symfony 3.4
+>(e.g. in Symfony 4.2), all pull requests must be based off of the **3.4** branch,
 >**not** the master or older branches.
 
 We love contributors! For more information on how you can contribute to the
 Symfony documentation, please read
 [Contributing to the Documentation](https://symfony.com/doc/current/contributing/documentation/overview.html)
 
-Platform.sh
------------
+SymfonyCloud
+------------
+
+Pull requests are automatically built by [SymfonyCloud](https://symfony.com/cloud).
+
+Docker
+------
+
+You can build the doc locally with these commands:
+
+```bash
+# build the image...
+$ docker build . -t symfony-docs
+
+# ...and start the local web server
+# (if it's already in use, change the '8080' port by any other port)
+$ docker run --rm -p 8080:80 symfony-docs
+```
 
-Pull requests are automatically built by [Platform.sh](https://platform.sh).
+You can now read the docs at http://127.0.0.1:8080 (if you use a virtual
+machine, browse its IP instead of localhost; e.g. `http://192.168.99.100:8080`).

Dockerfile

@@ -6,7 +6,7 @@ Jinja2==2.9.6
 MarkupSafe==1.0
 Pygments==2.2.0
 pytz==2017.2
-requests==2.12.5
+requests==2.20.0
 six==1.10.0
 snowballstemmer==1.2.1
 Sphinx==1.3.6

README.markdown

@@ -119,7 +119,7 @@
 /cookbook/console/commands_as_services /console/commands_as_services
 /cookbook/console/console_command /console
 /cookbook/console/index /console
-/cookbook/console/logging /console/logging
+/cookbook/console/logging /console
 /cookbook/console/request_context /console/request_context
 /cookbook/console/style /console/style
 /cookbook/console/usage /console
@@ -390,3 +390,26 @@
 /quick_tour/the_view /quick_tour/flex_recipes
 /service_container/service_locators /service_container/service_subscribers_locators
 /templating/overriding /bundles/override
+/security/custom_provider /security/user_provider
+/security/multiple_user_providers /security/user_provider
+/security/custom_password_authenticator /security/guard_authentication
+/security/api_key_authentication /security/guard_authentication
+/security/pre_authenticated /security/auth_providers
+/security/host_restriction /security/firewall_restriction
+/security/acl_advanced /security/acl
+/security/password_encoding /security
+/weblink /web_link
+/components/weblink /components/web_link
+/frontend/encore/installation-no-flex /frontend/encore/installation
+/http_cache/form_csrf_caching /security/csrf
+/console/logging /console
+/reference/forms/twig_reference /form/form_customization
+/form/rendering /form/form_customization
+/profiler/matchers /profiler
+/profiler/profiling_data /profiler
+/profiler/wdt_follow_ajax /profiler
+/security/entity_provider /security/user_provider
+/session/avoid_session_start /session
+/session/sessions_directory /session
+/frontend/encore/legacy-apps /frontend/encore/legacy-applications
+/configuration/external_parameters /configuration/environment_variables

_build/.requirements.txt

@@ -15,7 +15,7 @@
         <container xmlns="http://symfony.com/schema/dic/services"
             xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
             xsi:schemaLocation="http://symfony.com/schema/dic/services
-                http://symfony.com/schema/dic/services/services-1.0.xsd">
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
 
             <services>
                 <service id="app.mailer" class="App\Mailer">

_build/redirection_map

@@ -57,8 +57,8 @@ post URL. Let's create a new ``Slugger`` class inside ``src/Utils/``::
     }
 
 If you're using the :ref:`default services.yaml configuration <service-container-services-load-example>`,
-this class is auto-registered as a service whose ID is ``App\Utils\Slugger`` (or
-simply ``Slugger::class`` if the class is already imported in your code).
+this class is auto-registered as a service with the ID ``App\Utils\Slugger`` (to
+prevent against typos, import the class and write ``Slugger::class`` in your code).
 
 .. best-practice::
 
@@ -110,7 +110,7 @@ Both formats have the same performance, so this is ultimately a matter of
 personal taste.
 
 We recommend YAML because it's friendly to newcomers and concise. You can
-of course use whatever format you like.
+use any of the other formats if you prefer another format.
 
 Using a Persistence Layer
 -------------------------
@@ -198,7 +198,7 @@ looking for mapping information::
 
         /**
          * @ORM\OneToMany(
-         *      targetEntity="Comment",
+         *      targetEntity="App\Entity\Comment",
          *      mappedBy="post",
          *      orphanRemoval=true
          * )
@@ -232,7 +232,6 @@ Then, this bundle is enabled automatically, but only for the ``dev`` and
 ``test`` environments::
 
     // config/bundles.php
-
     return [
         // ...
         Doctrine\Bundle\FixturesBundle\DoctrineFixturesBundle::class => ['dev' => true, 'test' => true],

_images/components/messenger/overview.png

@@ -6,8 +6,6 @@ and security credentials) and different environments (development, production).
 That's why Symfony recommends that you split the application configuration into
 three parts.
 
-.. _config-parameters.yml:
-
 Infrastructure-Related Configuration
 ------------------------------------
 
@@ -18,8 +16,9 @@ application behavior.
 .. best-practice::
 
     Define the infrastructure-related configuration options as
-    :doc:`environment variables </configuration/external_parameters>`. During
-    development, use the ``.env`` file at the root of your project to set these.
+    :doc:`environment variables </configuration/environment_variables>`. During
+    development, use the ``.env`` and ``.env.local`` files at the root of your
+    project to set these.
 
 By default, Symfony adds these types of options to the ``.env`` file when
 installing new dependencies in the app:
@@ -42,28 +41,33 @@ 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.
 
+To override these variables with machine-specific or sensitive values, create a
+``.env.local`` file. This file should not be added to version control.
+
 .. caution::
 
     Beware that dumping the contents of the ``$_SERVER`` and ``$_ENV`` variables
     or outputting the ``phpinfo()`` contents will display the values of the
     environment variables, exposing sensitive information such as the database
     credentials.
 
-.. _best-practices-canonical-parameters:
-
 Canonical Parameters
 ~~~~~~~~~~~~~~~~~~~~
 
 .. best-practice::
 
-    Define all your application's env vars in the ``.env.dist`` file.
+    Define all your application's env vars in the ``.env`` file.
 
-Symfony includes a configuration file called ``.env.dist`` at the project root,
-which stores the canonical list of environment variables for the application.
+Symfony includes a configuration file called ``.env`` at the project root, which
+stores the canonical list of environment variables for the application. This
+file should be stored in version control and so should only contain non-sensitive
+default values.
+
+.. caution::
 
-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.
+    Applications created before November 2018 had a slightly different system,
+    involving a ``.env.dist`` file. For information about upgrading, see:
+    :doc:`/configuration/dot-env-changes`.
 
 Application-Related Configuration
 ---------------------------------
@@ -96,8 +100,8 @@ paginated results.
     Use constants to define configuration options that rarely change.
 
 The traditional approach for defining configuration options has caused many
-Symfony apps to include an option like the following, which would be used
-to control the number of posts to display on the blog homepage:
+Symfony applications to include an option like the following, which would be
+used to control the number of posts to display on the blog homepage:
 
 .. code-block:: yaml
 

_images/components/messenger/overview.svg

@@ -128,7 +128,7 @@ Fetching Services
 
 If you extend the base ``AbstractController`` class, you can't access services
 directly from the container via ``$this->container->get()`` or ``$this->get()``.
-Instead, you must use dependency injection to fetch services: most easily done by
+Instead, you must use dependency injection to fetch services by
 :ref:`type-hinting action method arguments <controller-accessing-services>`:
 
 .. best-practice::
@@ -181,7 +181,7 @@ When Things Get More Advanced
 
 The above example works without any configuration because the wildcard name
 ``{id}`` matches the name of the property on the entity. If this isn't true, or
-if you have even more complex logic, the easiest thing to do is just query for
+if you have even more complex logic, your best choice is to query for
 the entity manually. In our application, we have this situation in
 ``CommentController``::
 
@@ -218,9 +218,9 @@ flexible::
         // ...
     }
 
-The point is this: the ParamConverter shortcut is great for simple situations.
-But you shouldn't forget that querying for entities directly is still very
-easy.
+The point is this: the ParamConverter shortcut is great for most situations.
+However, there is nothing wrong with querying for entities directly if the
+ParamConverter would get complicated.
 
 Pre and Post Hooks
 ------------------

_images/components/serializer/serializer_workflow.png

@@ -48,7 +48,8 @@ Structuring the Application
 ---------------------------
 
 After creating the application, enter the ``blog/`` directory and you'll see a
-number of files and directories generated automatically:
+number of files and directories generated automatically. These are the most
+important ones:
 
 .. code-block:: text
 
@@ -75,13 +76,13 @@ Application Bundles
 
 When Symfony 2.0 was released, most developers naturally adopted the symfony
 1.x way of dividing applications into logical modules. That's why many Symfony
-apps used bundles to divide their code into logical features: UserBundle,
+applications used bundles to divide their code into logical features: UserBundle,
 ProductBundle, InvoiceBundle, etc.
 
 But a bundle is *meant* to be something that can be reused as a stand-alone
 piece of software. If UserBundle cannot be used *"as is"* in other Symfony
-apps, then it shouldn't be its own bundle. Moreover, if InvoiceBundle depends on
-ProductBundle, then there's no advantage to having two separate bundles.
+applications, then it shouldn't be its own bundle. Moreover, if InvoiceBundle
+depends on ProductBundle, then there's no advantage to having two separate bundles.
 
 .. best-practice::
 

_images/components/serializer/serializer_workflow.svg

@@ -134,7 +134,7 @@ view layer:
     {{ form_start(form) }}
         {{ form_widget(form) }}
 
-        <input type="submit" class="btn" value="Create" />
+        <input type="submit" class="btn" value="Create"/>
     {{ form_end(form) }}
 
 Validation
@@ -161,7 +161,7 @@ blank, add the following in the ``Post`` object::
     class Post
     {
         /**
-         * @Assert\NotBlank()
+         * @Assert\NotBlank
          */
         public $title;
     }

_images/components/workflow/pull_request.png

@@ -19,8 +19,8 @@ What is this Guide About?
 -------------------------
 
 This guide aims to fix that by describing the **best practices for developing
-web apps with the Symfony full-stack Framework**. These are best practices that
-fit the philosophy of the framework as envisioned by its original creator
+web applications with the Symfony full-stack Framework**. These are best practices
+that fit the philosophy of the framework as envisioned by its original creator
 `Fabien Potencier`_.
 
 .. note::
@@ -44,13 +44,13 @@ then **extend and fit to your specific needs**:
 
 We know that old habits die hard and some of you will be shocked by some
 of these best practices. But by following these, you'll be able to develop
-apps faster, with less complexity and with the same or even higher quality.
-It's also a moving target that will continue to improve.
+applications faster, with less complexity and with the same or even higher
+quality. It's also a moving target that will continue to improve.
 
 Keep in mind that these are **optional recommendations** that you and your
 team may or may not follow to develop Symfony applications. If you want to
-continue using your own best practices and methodologies, you can of course
-do it. Symfony is flexible enough to adapt to your needs. That will never
+continue using your own best practices and methodologies, you can still do
+that. Symfony is flexible enough to adapt to your needs. That will never
 change.
 
 Who this Book Is for (Hint: It's not a Tutorial)
@@ -102,5 +102,5 @@ for not doing it are various:
 
 Next: :doc:`/best_practices/creating-the-project`
 
-.. _`Fabien Potencier`: https://connect.sensiolabs.com/profile/fabpot
+.. _`Fabien Potencier`: https://connect.symfony.com/profile/fabpot
 .. _`Symfony Demo`: https://github.com/symfony/demo