Merge remote-tracking branch 'upstream/master'

Author: javiereguiluz

best_practices/business-logic.rst

@@ -326,14 +326,13 @@ Coding Standards
 
 The Symfony source code follows the `PSR-1`_ and `PSR-2`_ coding standards that
 were defined by the PHP community. You can learn more about
-`the Symfony Code Standards`_ and even 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.
+:doc:`the Symfony Coding standards </contributing/code/standards>` and even
+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.
 
 .. _`full definition`: http://en.wikipedia.org/wiki/Business_logic
 .. _`Doctrine project`: http://www.doctrine-project.org/
 .. _`fixture class`: http://symfony.com/doc/current/bundles/DoctrineFixturesBundle/index.html#writing-simple-fixtures
 .. _`PSR-1`: http://www.php-fig.org/psr/psr-1/
 .. _`PSR-2`: http://www.php-fig.org/psr/psr-2/
-.. _`the Symfony Code Standards`: http://symfony.com/doc/current/contributing/code/standards.html
 .. _`PHP-CS-Fixer`: https://github.com/FriendsOfPHP/PHP-CS-Fixer

best_practices/configuration.rst

@@ -74,8 +74,8 @@ 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:`/cookbook/configuration/environments` to another. That's why Symfony
-already includes ``app/config/config_dev.yml`` and ``app/config/config_prod.yml``
+one :doc:`environment </cookbook/configuration/environments>` to another. That's
+why Symfony already includes ``app/config/config_dev.yml`` and ``app/config/config_prod.yml``
 files so that you can override specific values for each environment.
 
 Constants vs Configuration Options

best_practices/controllers.rst

@@ -110,8 +110,9 @@ for the homepage of our app:
          */
         public function indexAction()
         {
-            $em = $this->getDoctrine()->getManager();
-            $posts = $em->getRepository('App:Post')->findLatest();
+            $posts = $this->getDoctrine()
+                ->getRepository('AppBundle:Post')
+                ->findLatest();
 
             return $this->render('default/index.html.twig', array(
                 'posts' => $posts
@@ -136,6 +137,9 @@ For example:
 
 .. code-block:: php
 
+    use AppBundle\Entity\Post;
+    use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
+
     /**
      * @Route("/{id}", name="admin_post_show")
      */
@@ -144,7 +148,7 @@ For example:
         $deleteForm = $this->createDeleteForm($post);
 
         return $this->render('admin/post/show.html.twig', array(
-            'post'      => $post,
+            'post'        => $post,
             'delete_form' => $deleteForm->createView(),
         ));
     }
@@ -186,8 +190,10 @@ flexible:
 
 .. code-block:: php
 
+    use AppBundle\Entity\Post;
     use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
     use Sensio\Bundle\FrameworkExtraBundle\Configuration\ParamConverter;
+    use Symfony\Component\HttpFoundation\Request;
 
     /**
      * @Route("/comment/{postSlug}/new", name = "comment_new")
@@ -206,6 +212,7 @@ Pre and Post Hooks
 ------------------
 
 If you need to execute some code before or after the execution of your controllers,
-you can use the EventDispatcher component to :doc:`/cookbook/event_dispatcher/before_after_filters`.
+you can use the EventDispatcher component to
+:doc:`set up before and after filters </cookbook/event_dispatcher/before_after_filters>`.
 
 .. _`ParamConverter`: http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html

best_practices/creating-the-project.rst

@@ -4,50 +4,39 @@ Creating the Project
 Installing Symfony
 ------------------
 
-There is only one recommended way to install Symfony:
+In the past, Symfony projects were created with `Composer`_, the dependency manager
+for PHP applications. However, the current recommendation is to use the **Symfony
+Installer**, which has to be installed before creating your first project.
 
-.. best-practice::
-
-    Always use `Composer`_ to install Symfony.
-
-Composer is the dependency manager used by modern PHP applications. Adding or
-removing requirements for your project and updating the third-party libraries
-used by your code is a breeze thanks to Composer.
-
-Dependency Management with Composer
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Linux and Mac OS X Systems
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Before installing Symfony, you need to make sure that you have Composer installed
-globally. Open your terminal (also called *command console*) and run the following
-command:
+Open your command console and execute the following:
 
 .. code-block:: bash
 
-    $ composer --version
-    Composer version 1e27ff5e22df81e3cd0cd36e5fdd4a3c5a031f4a 2014-08-11 15:46:48
+    $ curl -LsS http://symfony.com/installer > symfony.phar
+    $ sudo mv symfony.phar /usr/local/bin/symfony
+    $ chmod a+x /usr/local/bin/symfony
 
-You'll probably see a different version identifier. Never mind because Composer
-is updated on a continuous basis and its specific version doesn't matter.
+Now you can execute the Symfony Installer as a global system command called
+``symfony``.
 
-Installing Composer Globally
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Windows Systems
+~~~~~~~~~~~~~~~
 
-In case you don't have Composer installed globally, execute the following two
-commands if you use Linux or Mac OS X (the second command will ask for your
-user password):
+Open your command console and execute the following:
 
 .. code-block:: bash
 
-    $ curl -sS https://getcomposer.org/installer | php
-    $ sudo mv composer.phar /usr/local/bin/composer
+    c:\> php -r "readfile('http://symfony.com/installer');" > symfony.phar
 
-.. note::
+Then, move the downloaded ``symfony.phar`` file to your projects directory and
+execute it as follows:
 
-    Depending on your Linux distribution, you may need to execute ``su`` command
-    instead of ``sudo``.
+.. code-block:: bash
 
-If you use a Windows system, download the executable installer from the
-`Composer download page`_ and follow the steps to install it.
+    c:\> php symfony.phar
 
 Creating the Blog Application
 -----------------------------
@@ -58,64 +47,19 @@ to create files and execute the following commands:
 
 .. code-block:: bash
 
+    # Linux, Mac OS X
     $ cd projects/
-    $ composer create-project symfony/framework-standard-edition blog/
-
-This command will create a new directory called ``blog`` that will contain
-a fresh new project based on the most recent stable Symfony version available.
-
-Checking the Symfony Installation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Once the installation is finished, enter the ``blog/`` directory and check that
-Symfony is correctly installed by executing the following command:
-
-.. code-block:: bash
-
-    $ cd blog/
-    $ php app/console --version
-
-    Symfony version 2.6.* - app/dev/debug
-
-If you see the installed Symfony version, everything worked as expected. If not,
-you can execute the following *script* to check what does prevent your system
-from correctly executing Symfony applications:
-
-.. code-block:: bash
-
-    $ php app/check.php
-
-Depending on your system, you can see up to two different lists when executing the
-`check.php` script. The first one shows the mandatory requirements which your
-system must meet to execute Symfony applications. The second list shows the
-optional requirements suggested for an optimal execution of Symfony applications:
-
-.. code-block:: bash
-
-    Symfony2 Requirements Checker
-    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-    > PHP is using the following php.ini file:
-      /usr/local/zend/etc/php.ini
-
-    > Checking Symfony requirements:
-      .....E.........................W.....
-
-    [ERROR]
-    Your system is not ready to run Symfony2 projects
-
-    Fix the following mandatory requirements
-    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-     * date.timezone setting must be set
-       > Set the "date.timezone" setting in php.ini* (like Europe/Paris).
-
-    Optional recommendations to improve your setup
-    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    $ symfony new blog
 
-     * short_open_tag should be disabled in php.ini
-       > Set short_open_tag to off in php.ini*.
+    # Windows
+    c:\> cd projects/
+    c:\projects\> php symfony.phar new blog
 
+This command creates a new directory called ``blog`` that contains a fresh new
+project based on the most recent stable Symfony version available. In addition,
+the installer checks if your system meets the technical requirements to execute
+Symfony applications. If not, you'll see the list of changes needed to meet those
+requirements.
 
 .. tip::
 
@@ -208,8 +152,7 @@ that follows these best practices:
 
 .. tip::
 
-    If you are using Symfony 2.6 or a newer version, the ``AppBundle`` bundle
-    is already generated for you. If you are using an older Symfony version,
+    If your Symfony installation doesn't come with a pre-generated ``AppBundle``,
     you can generate it by hand executing this command:
 
     .. code-block:: bash
@@ -243,7 +186,7 @@ it's released:
     └─ web/
 
 The changes are pretty superficial, but for now, we recommend that you use
-the Symfony2 directory structure.
+the Symfony directory structure.
 
 .. _`Composer`: https://getcomposer.org/
 .. _`Get Started`: https://getcomposer.org/doc/00-intro.md

best_practices/forms.rst

@@ -13,8 +13,8 @@ Building Forms
     Define your forms as PHP classes.
 
 The Form component allows you to build forms right inside your controller
-code. Honestly, unless you need to reuse the form somewhere else, that's
-totally fine. But for organize and reuse, we recommend that you define each
+code. This is perfectly fine if you don't need to reuse the form somewhere else.
+But for organization and reuse, we recommend that you define each
 form in its own PHP class::
 
     namespace AppBundle\Form;
@@ -165,8 +165,9 @@ fields:
 
 If you need more control over how your fields are rendered, then you should
 remove the ``form_widget(form)`` function and render your fields individually.
-See :doc:`/cookbook/form/form_customization` for more information on this and how
-you can control *how* the form renders at a global level using form theming.
+See the :doc:`/cookbook/form/form_customization` article for more information
+on this and how you can control *how* the form renders at a global level
+using form theming.
 
 Handling Form Submits
 ---------------------

best_practices/security.rst

@@ -43,6 +43,7 @@ which uses a login form to load users from the database:
 
 .. code-block:: yaml
 
+    # app/config/security.yml
     security:
         encoders:
             AppBundle\Entity\User: bcrypt
@@ -73,16 +74,16 @@ Authorization (i.e. Denying Access)
 -----------------------------------
 
 Symfony gives you several ways to enforce authorization, including the ``access_control``
-configuration in :doc:`security.yml </reference/configuration/security>` the
+configuration in :doc:`security.yml </reference/configuration/security>`, the
 :ref:`@Security annotation <best-practices-security-annotation>` and using
-:ref:`isGranted <best-practices-directly-isGranted>` on the ``security.context``
+:ref:`isGranted <best-practices-directly-isGranted>` on the ``security.authorization_checker``
 service directly.
 
 .. best-practice::
 
     * For protecting broad URL patterns, use ``access_control``;
     * Whenever possible, use the ``@Security`` annotation;
-    * Check security directly on the ``security.context`` service whenever
+    * Check security directly on the ``security.authorization_checker`` service whenever
       you have a more complex situation.
 
 There are also different ways to centralize your authorization logic, like
@@ -207,6 +208,8 @@ Now you can reuse this method both in the template and in the security expressio
     {% endif %}
 
 .. _best-practices-directly-isGranted:
+.. _checking-permissions-without-security:
+.. _manually-checking-permissions:
 
 Checking Permissions without @Security
 --------------------------------------
@@ -315,7 +318,7 @@ Now, you can use the voter with the ``@Security`` annotation:
         // ...
     }
 
-You can also use this directly with the ``security.context`` service, or
+You can also use this directly with the ``security.authorization_checker`` service or
 via the even easier shortcut in a controller:
 
 .. code-block:: php
@@ -327,16 +330,20 @@ via the even easier shortcut in a controller:
     {
         $post = // query for the post ...
 
-        if (!$this->get('security.context')->isGranted('edit', $post)) {
-            throw $this->createAccessDeniedException();
-        }
+        $this->denyAccessUnlessGranted('edit', $post);
+
+        // or without the shortcut:
+        //
+        // if (!$this->get('security.authorization_checker')->isGranted('edit', $post)) {
+        //    throw $this->createAccessDeniedException();
+        // }
     }
 
 Learn More
 ----------
 
 The `FOSUserBundle`_, developed by the Symfony community, adds support for a
-database-backed user system in Symfony2. It also handles common tasks like
+database-backed user system in Symfony. It also handles common tasks like
 user registration and forgotten password functionality.
 
 Enable the :doc:`Remember Me feature </cookbook/security/remember_me>` to
@@ -350,11 +357,7 @@ If your company uses a user login method not supported by Symfony, you can
 develop :doc:`your own user provider </cookbook/security/custom_provider>` and
 :doc:`your own authentication provider </cookbook/security/custom_authentication_provider>`.
 
-.. _`Security Cookbook Section`: http://symfony.com/doc/current/cookbook/security/index.html
-.. _`security.yml`: http://symfony.com/doc/current/reference/configuration/security.html
 .. _`ParamConverter`: http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
 .. _`@Security annotation`: http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/security.html
-.. _`security voter`: http://symfony.com/doc/current/cookbook/security/voters_data_permission.html
-.. _`ACL's`: http://symfony.com/doc/current/cookbook/security/acl.html
 .. _`expression`: http://symfony.com/doc/current/components/expression_language/introduction.html
 .. _`FOSUserBundle`: https://github.com/FriendsOfSymfony/FOSUserBundle

best_practices/templates.rst

@@ -9,7 +9,7 @@ languages - like `Twig`_ - were created to make templating even better.
 
     Use Twig templating format for your templates.
 
-Generally speaking, PHP templates are much more verbose than in Twig because
+Generally speaking, PHP templates are much more verbose than Twig templates because
 they lack native support for lots of modern features needed by templates,
 like inheritance, automatic escaping and named arguments for filters and
 functions.
@@ -153,6 +153,7 @@ name is irrelevant because you never use it in your own code):
         app.twig.app_extension:
             class:     AppBundle\Twig\AppExtension
             arguments: ["@markdown"]
+            public:    false
             tags:
                 - { name: twig.extension }