Merge remote-tracking branch 'upstream/master'

Author: javiereguiluz

best_practices/business-logic.rst

@@ -56,7 +56,7 @@ The blog application needs a utility that can transform a post title (e.g.
 "Hello World") into a slug (e.g. "hello-world"). The slug will be used as
 part of the post URL.
 
-Let's, create a new ``Slugger`` class inside ``src/AppBundle/Utils/`` and
+Let's create a new ``Slugger`` class inside ``src/AppBundle/Utils/`` and
 add the following ``slugify()`` method:
 
 .. code-block:: php

best_practices/configuration.rst

@@ -42,6 +42,8 @@ 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.
 
+.. _best-practices-canonical-parameters:
+
 Canonical Parameters
 ~~~~~~~~~~~~~~~~~~~~
 
@@ -101,8 +103,8 @@ to control the number of posts to display on the blog homepage:
     parameters:
         homepage.num_items: 10
 
-If you ask yourself when the last time was that you changed the value of
-*any* option like this, odds are that you *never* have. Creating a configuration
+If you've done something like this in the past, it's likely that you've in fact
+*never* actually needed to change that value. Creating a configuration
 option for a value that you are never going to configure just isn't necessary.
 Our recommendation is to define these values as constants in your application.
 You could, for example, define a ``NUM_ITEMS`` constant in the ``Post`` entity:
@@ -124,7 +126,7 @@ everywhere in your application. When using parameters, they are only available
 from places with access to the Symfony container.
 
 Constants can be used for example in your Twig templates thanks to the
-``constant()`` function:
+`constant() function`_:
 
 .. code-block:: html+jinja
 

best_practices/controllers.rst

@@ -76,20 +76,15 @@ Template Configuration
     Don't use the ``@Template()`` annotation to configure the template used by
     the controller.
 
-The ``@Template`` annotation is useful, but also involves some magic. For
-that reason, we don't recommend using it.
+The ``@Template`` annotation is useful, but also involves some magic. We
+don't think its benefit is worth the magic, and so recommend against using
+it.
 
 Most of the time, ``@Template`` is used without any parameters, which makes
 it more difficult to know which template is being rendered. It also makes
 it less obvious to beginners that a controller should always return a Response
 object (unless you're using a view layer).
 
-Lastly, the ``@Template`` annotation uses a ``TemplateListener`` class that hooks
-into the ``kernel.view`` event dispatched by the framework. This listener introduces
-a measurable performance impact. In the sample blog application, rendering the
-homepage took 5 milliseconds using the ``$this->render()`` method and 26 milliseconds
-using the ``@Template`` annotation.
-
 How the Controller Looks
 ------------------------
 

best_practices/creating-the-project.rst

@@ -8,35 +8,15 @@ In the past, Symfony projects were created with `Composer`_, the dependency mana
 for PHP applications. However, the current recommendation is to use the **Symfony
 Installer**, which has to be installed before creating your first project.
 
-Linux and Mac OS X Systems
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Open your command console and execute the following:
-
-.. code-block:: bash
-
-    $ curl -LsS http://symfony.com/installer > symfony.phar
-    $ sudo mv symfony.phar /usr/local/bin/symfony
-    $ chmod a+x /usr/local/bin/symfony
-
-Now you can execute the Symfony Installer as a global system command called
-``symfony``.
-
-Windows Systems
-~~~~~~~~~~~~~~~
-
-Open your command console and execute the following:
-
-.. code-block:: bash
-
-    c:\> php -r "readfile('http://symfony.com/installer');" > symfony.phar
+.. best-practice::
 
-Then, move the downloaded ``symfony.phar`` file to your projects directory and
-execute it as follows:
+    Use the Symfony Installer to create new Symfony-based projects.
 
-.. code-block:: bash
+Read the :doc:`installation chapter </book/installation>` of the Symfony Book to
+learn how to install and use the Symfony Installer.
 
-    c:\> php symfony.phar
+.. _linux-and-mac-os-x-systems:
+.. _windows-systems:
 
 Creating the Blog Application
 -----------------------------
@@ -114,7 +94,7 @@ 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 InvoiceBundle depends on
+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.
 
 .. best-practice::

best_practices/forms.rst

@@ -207,3 +207,21 @@ Second, we recommend using ``$form->isSubmitted()`` in the ``if`` statement
 for clarity. This isn't technically needed, since ``isValid()`` first calls
 ``isSubmitted()``. But without this, the flow doesn't read well as it *looks*
 like the form is *always* processed (even on the GET request).
+
+Custom Form Field Types
+-----------------------
+
+.. best-practice::
+
+    Add the ``app_`` prefix to your custom form field types to avoid collisions.
+
+Custom form field types inherit from the ``AbstractType`` class, which defines the
+``getName()`` method to configure the name of that form type. These names must
+be unique in the application.
+
+If a custom form type uses the same name as any of the Symfony's built-in form
+types, it will override it. The same happens when the custom form type matches
+any of the types defined by the third-party bundles installed in your application.
+
+Add the ``app_`` prefix to your custom form field types to avoid name collisions
+that can lead to hard to debug errors.

best_practices/i18n.rst

@@ -11,7 +11,7 @@ following ``translator`` configuration option and set your application locale:
     # app/config/config.yml
     framework:
         # ...
-        translator: { fallback: "%locale%" }
+        translator: { fallbacks: ["%locale%"] }
 
     # app/config/parameters.yml
     parameters:
@@ -80,7 +80,7 @@ English in the application would be:
 
 .. code-block:: xml
 
-    <!-- app/Resources/translations/messages.en.xliff -->
+    <!-- app/Resources/translations/messages.en.xlf -->
     <?xml version="1.0"?>
     <xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
         <file source-language="en" target-language="en" datatype="plaintext" original="file.ext">

best_practices/introduction.rst

@@ -4,7 +4,7 @@
 The Symfony Framework Best Practices
 ====================================
 
-The Symfony framework is well-known for being *really* flexible and is used
+The Symfony Framework is well-known for being *really* flexible and is used
 to build micro-sites, enterprise applications that handle billions of connections
 and even as the basis for *other* frameworks. Since its release in July 2011,
 the community has learned a lot about what's possible and how to do things *best*.
@@ -19,7 +19,7 @@ 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
+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
 `Fabien Potencier`_.
 
@@ -32,7 +32,7 @@ fit the philosophy of the framework as envisioned by its original creator
 
 This guide is **specially suited** for:
 
-* Websites and web applications developed with the full-stack Symfony framework.
+* Websites and web applications developed with the full-stack Symfony Framework.
 
 For other situations, this guide might be a good **starting point** that you can
 then **extend and fit to your specific needs**:
@@ -62,22 +62,30 @@ Symfony to follow everything. If you are totally new to Symfony, welcome!
 Start with :doc:`The Quick Tour </quick_tour/the_big_picture>` tutorial first.
 
 We've deliberately kept this guide short. We won't repeat explanations that
-you can find in the vast Symfony documentation, like discussions about dependency
-injection or front controllers. We'll solely focus on explaining how to do
+you can find in the vast Symfony documentation, like discussions about Dependency
+Injection or front controllers. We'll solely focus on explaining how to do
 what you already know.
 
 The Application
 ---------------
 
-In addition to this guide, you'll find a sample application developed with
-all these best practices in mind. **The application is a simple blog engine**,
-because that will allow us to focus on the Symfony concepts and features without
-getting buried in difficult details.
+In addition to this guide, a sample application has been developed with all these
+best practices in mind. This project, called the Symfony Demo application, can
+be obtained through the Symfony Installer. First, `download and install`_ the
+installer and then execute this command to download the demo application:
 
-Instead of developing the application step by step in this guide, you'll find
-selected snippets of code through the chapters. Please refer to the last chapter
-of this guide to find more details about this application and the instructions
-to install it.
+.. code-block:: bash
+
+    # Linux and Mac OS X
+    $ symfony demo
+
+    # Windows
+    c:\> php symfony demo
+
+**The demo application is a simple blog engine**, because that will allow us to
+focus on the Symfony concepts and features without getting buried in difficult
+implementation details. Instead of developing the application step by step in
+this guide, you'll find selected snippets of code through the chapters.
 
 Don't Update Your Existing Applications
 ---------------------------------------
@@ -95,3 +103,4 @@ practices**. The reasons for not doing it are various:
   your tests or adding features that provide real value to the end users.
 
 .. _`Fabien Potencier`: https://connect.sensiolabs.com/profile/fabpot
+.. _`download and install`: http://symfony.com/download

best_practices/security.rst

@@ -234,7 +234,16 @@ more advanced use-case, you can always do the same security check in PHP:
         }
 
         if (!$post->isAuthor($this->getUser())) {
-            throw $this->createAccessDeniedException();
+            $this->denyAccessUnlessGranted('edit', $post);
+
+	    // or without the shortcut:
+	    //
+	    // use Symfony\Component\Security\Core\Exception\AccessDeniedException;
+	    // ...
+	    //
+	    // if (!$this->get('security.authorization_checker')->isGranted('edit', $post)) {
+	    //    throw $this->createAccessDeniedException();
+	    // }
         }
 
         // ...
@@ -334,6 +343,9 @@ via the even easier shortcut in a controller:
 
         // or without the shortcut:
         //
+        // use Symfony\Component\Security\Core\Exception\AccessDeniedException;
+        // ...
+        //
         // if (!$this->get('security.authorization_checker')->isGranted('edit', $post)) {
         //    throw $this->createAccessDeniedException();
         // }

best_practices/templates.rst

@@ -51,6 +51,10 @@ Another advantage is that centralizing your templates simplifies the work
 of your designers. They don't need to look for templates in lots of directories
 scattered through lots of bundles.
 
+.. best-practice::
+
+    Use lowercased snake_case for directory and template names.
+
 Twig Extensions
 ---------------
 

best_practices/tests.rst

@@ -30,25 +30,35 @@ A functional test can be as easy as this:
 
 .. code-block:: php
 
-    /** @dataProvider provideUrls */
-    public function testPageIsSuccessful($url)
-    {
-        $client = self::createClient();
-        $client->request('GET', $url);
+    // src/AppBundle/Tests/ApplicationAvailabilityFunctionalTest.php
+    namespace AppBundle\Tests;
 
-        $this->assertTrue($client->getResponse()->isSuccessful());
-    }
+    use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;
 
-    public function provideUrls()
+    class ApplicationAvailabilityFunctionalTest extends WebTestCase
     {
-        return array(
-            array('/'),
-            array('/posts'),
-            array('/post/fixture-post-1'),
-            array('/blog/category/fixture-category'),
-            array('/archives'),
-            // ...
-        );
+        /**
+         * @dataProvider urlProvider
+         */
+        public function testPageIsSuccessful($url)
+        {
+            $client = self::createClient();
+            $client->request('GET', $url);
+
+            $this->assertTrue($client->getResponse()->isSuccessful());
+        }
+
+        public function urlProvider()
+        {
+            return array(
+                array('/'),
+                array('/posts'),
+                array('/post/fixture-post-1'),
+                array('/blog/category/fixture-category'),
+                array('/archives'),
+                // ...
+            );
+        }
     }
 
 This code checks that all the given URLs load successfully, which means that

best_practices/web-assets.rst

@@ -29,8 +29,8 @@ much more concise:
 .. note::
 
     Keep in mind that ``web/`` is a public directory and that anything stored
-    here will be publicly accessible. For that reason, you should put your
-    compiled web assets here, but not their source files (e.g. SASS files).
+    here will be publicly accessible, including all the original asset files
+    (e.g. Sass, LESS and CoffeScript files).
 
 Using Assetic
 -------------
@@ -51,16 +51,15 @@ tools like GruntJS.
 
 :doc:`Assetic </cookbook/assetic/asset_management>` is an asset manager capable
 of compiling assets developed with a lot of different frontend technologies
-like LESS, Sass and CoffeeScript.
-Combining all your assets with Assetic is a matter of wrapping all the assets
-with a single Twig tag:
+like LESS, Sass and CoffeeScript. Combining all your assets with Assetic is a
+matter of wrapping all the assets with a single Twig tag:
 
 .. code-block:: html+jinja
 
     {% stylesheets
         'css/bootstrap.min.css'
         'css/main.css'
-        filter='cssrewrite' output='css/compiled/all.css' %}
+        filter='cssrewrite' output='css/compiled/app.css' %}
         <link rel="stylesheet" href="{{ asset_url }}" />
     {% endstylesheets %}
 
@@ -69,7 +68,7 @@ with a single Twig tag:
     {% javascripts
         'js/jquery.min.js'
         'js/bootstrap.min.js'
-        output='js/compiled/all.js' %}
+        output='js/compiled/app.js' %}
         <script src="{{ asset_url }}"></script>
     {% endjavascripts %}