Updated more contents

Author: javiereguiluz

best_practices/business-logic.rst

@@ -25,15 +25,24 @@ Inside here, you can create whatever directories you want to organize things:
     ├─ var/
     └─ vendor/
 
-Services: Naming and Format
----------------------------
+.. _services-naming-and-format:
 
-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.
+Services: Naming and Configuration
+----------------------------------
+
+.. best-practice::
+
+    Use autowiring to automate the configuration of application services.
 
-Let's create a new ``Slugger`` class inside ``src/Utils/`` and add the following
-``slugify()`` method:
+:doc:`Service autowiring </service_container/autowiring>` is a feature provided
+by Symfony's Service Container to manage services with minimal configuration.
+It reads the type-hints on your constructor (or other methods) and automatically
+passes you the correct services. It can also add :doc:`service tags </service_container/tags>`
+to the services needed them, such as Twig extensions, event subscribers, etc.
+
+The blog application needs a utility that can transform a post title (e.g.
+"Hello World") into a slug (e.g. "hello-world") to include it as part of the
+post URL. Let's create a new ``Slugger`` class inside ``src/Utils/``:
 
 .. code-block:: php
 
@@ -42,11 +51,9 @@ Let's create a new ``Slugger`` class inside ``src/Utils/`` and add the following
 
     class Slugger
     {
-        public function slugify($string)
+        public function slugify(string $value): string
         {
-            return preg_replace(
-                '/[^a-z0-9]/', '-', strtolower(trim(strip_tags($string)))
-            );
+            // ...
         }
     }
 
@@ -71,14 +78,10 @@ such as the ``AdminController``:
 
     use App\Utils\Slugger;
 
-    public function createAction(Request $request, Slugger $slugger)
+    public function create(Request $request, Slugger $slugger)
     {
         // ...
 
-        // you can also fetch a public service like this
-        // but fetching services in this way is not considered a best practice
-        // $slugger = $this->get(Slugger::class);
-
         if ($form->isSubmitted() && $form->isValid()) {
             $slug = $slugger->slugify($post->getTitle());
             $post->setSlug($slug);

best_practices/controllers.rst

@@ -5,16 +5,15 @@ Symfony follows the philosophy of *"thin controllers and fat models"*. This
 means that controllers should hold just the thin layer of *glue-code*
 needed to coordinate the different parts of the application.
 
-As a rule of thumb, you should follow the 5-10-20 rule, where controllers should
-only define 5 variables or less, contain 10 actions or less and include 20 lines
-of code or less in each action. This isn't an exact science, but it should
-help you realize when code should be refactored out of the controller and
-into a service.
+Your controller methods should just call to other services, trigger some events
+if needed and then return a response, but they should not contain any actual
+business logic. If they do, refactor it out of the controller and into a service.
 
 .. best-practice::
 
-    Make your controller extend the FrameworkBundle base controller and use
-    annotations to configure routing, caching and security whenever possible.
+    Make your controller extend the ``AbstractController`` base controller
+    provided by Symfony and use annotations to configure routing, caching and
+    security whenever possible.
 
 Coupling the controllers to the underlying framework allows you to leverage
 all of its features and increases your productivity.
@@ -33,6 +32,18 @@ Overall, this means you should aggressively decouple your business logic
 from the framework while, at the same time, aggressively coupling your controllers
 and routing *to* the framework in order to get the most out of it.
 
+Controller Action Naming
+------------------------
+
+.. best-practice::
+
+    Don't add the ``Action`` suffix to the methods of the controller actions.
+
+The first Symfony versions required that controller method names ended in
+``Action`` (e.g. ``newAction()``, ``showAction()``). This suffix became optional
+when annotations were introduced for controllers. In modern Symfony applications
+this suffix is neither required nor recommended, so you can safely remove it.
+
 Routing Configuration
 ---------------------
 
@@ -94,32 +105,32 @@ for the homepage of our app:
     namespace App\Controller;
 
     use App\Entity\Post;
-    use Symfony\Bundle\FrameworkBundle\Controller\Controller;
+    use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
     use Symfony\Component\Routing\Annotation\Route;
 
-    class DefaultController extends Controller
+    class DefaultController extends AbstractController
     {
         /**
          * @Route("/", name="homepage")
          */
-        public function indexAction()
+        public function index()
         {
             $posts = $this->getDoctrine()
                 ->getRepository(Post::class)
                 ->findLatest();
 
-            return $this->render('default/index.html.twig', array(
+            return $this->render('default/index.html.twig', [
                 'posts' => $posts,
-            ));
+            ]);
         }
     }
 
 Fetching Services
 -----------------
 
-If you extend the base ``Controller`` class, you can access services directly from
-the container via ``$this->container->get()`` or ``$this->get()``. But instead, you
-should use dependency injection to fetch services: most easily done by
+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
 :ref:`type-hinting action method arguments <controller-accessing-services>`:
 
 .. best-practice::
@@ -153,40 +164,41 @@ For example:
     /**
      * @Route("/{id}", name="admin_post_show")
      */
-    public function showAction(Post $post)
+    public function show(Post $post)
     {
         $deleteForm = $this->createDeleteForm($post);
 
-        return $this->render('admin/post/show.html.twig', array(
+        return $this->render('admin/post/show.html.twig', [
             'post' => $post,
             'delete_form' => $deleteForm->createView(),
-        ));
+        ]);
     }
 
-Normally, you'd expect a ``$id`` argument to ``showAction()``. Instead, by
-creating a new argument (``$post``) and type-hinting it with the ``Post``
-class (which is a Doctrine entity), the ParamConverter automatically queries
-for an object whose ``$id`` property matches the ``{id}`` value. It will
-also show a 404 page if no ``Post`` can be found.
+Normally, you'd expect a ``$id`` argument to ``show()``. Instead, by creating a
+new argument (``$post``) and type-hinting it with the ``Post`` class (which is a
+Doctrine entity), the ParamConverter automatically queries for an object whose
+``$id`` property matches the ``{id}`` value. It will also show a 404 page if no
+``Post`` can be found.
 
 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 the entity
-manually. In our application, we have this situation in ``CommentController``:
+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
+the entity manually. In our application, we have this situation in
+``CommentController``:
 
 .. code-block:: php
 
     /**
      * @Route("/comment/{postSlug}/new", name = "comment_new")
      */
-    public function newAction(Request $request, $postSlug)
+    public function new(Request $request, $postSlug)
     {
         $post = $this->getDoctrine()
             ->getRepository(Post::class)
-            ->findOneBy(array('slug' => $postSlug));
+            ->findOneBy(['slug' => $postSlug]);
 
         if (!$post) {
             throw $this->createNotFoundException();
@@ -209,7 +221,7 @@ flexible:
      * @Route("/comment/{postSlug}/new", name = "comment_new")
      * @ParamConverter("post", options={"mapping": {"postSlug": "slug"}})
      */
-    public function newAction(Request $request, Post $post)
+    public function new(Request $request, Post $post)
     {
         // ...
     }

best_practices/creating-the-project.rst

@@ -6,9 +6,18 @@ Installing Symfony
 
 .. best-practice::
 
-    Use the `Symfony Skeleton`_ and `Composer`_ to create new Symfony-based projects.
+    Use Composer and Symfony Flex to create and manage Symfony applications.
 
-The **Symfony Skeleton** is a minimal and empty Symfony project which you can
+`Composer`_ is the package manager used by modern PHP application to manage their
+dependencies. `Symfony Flex`_ is a Composer plugin designed to automatize some
+of the most common tasks performed in Symfony applications. Using Flex is optional
+but recommended because it improves your productivity significantly.
+
+.. best-practice::
+
+    Use the Symfony Skeleton to create new Symfony-based projects.
+
+The `Symfony Skeleton`_ is a minimal and empty Symfony project which you can
 base your new projects on. Unlike past Symfony versions, this skeleton installs
 the absolute bare minimum amount of dependencies to make a fully working Symfony
 project. Read the :doc:`/setup` article to learn more about installing Symfony.

best_practices/forms.rst

@@ -42,9 +42,9 @@ PHP class::
 
         public function configureOptions(OptionsResolver $resolver)
         {
-            $resolver->setDefaults(array(
+            $resolver->setDefaults([
                 'data_class' => Post::class,
-            ));
+            ]);
         }
     }
 
@@ -59,7 +59,7 @@ To use the class, use ``createForm()`` and pass the fully qualified class name::
     use App\Form\PostType;
 
     // ...
-    public function newAction(Request $request)
+    public function new(Request $request)
     {
         $post = new Post();
         $form = $this->createForm(PostType::class, $post);
@@ -113,14 +113,14 @@ some developers configure form buttons in the controller::
     {
         // ...
 
-        public function newAction(Request $request)
+        public function new(Request $request)
         {
             $post = new Post();
             $form = $this->createForm(PostType::class, $post);
-            $form->add('submit', SubmitType::class, array(
+            $form->add('submit', SubmitType::class, [
                 'label' => 'Create',
                 'attr' => ['class' => 'btn btn-default pull-right'],
-            ));
+            ]);
 
             // ...
         }
@@ -168,7 +168,7 @@ Handling a form submit usually follows a similar template:
 
 .. code-block:: php
 
-    public function newAction(Request $request)
+    public function new(Request $request)
     {
         // build the form ...
 
@@ -179,17 +179,16 @@ Handling a form submit usually follows a similar template:
             $em->persist($post);
             $em->flush();
 
-            return $this->redirect($this->generateUrl(
-                'admin_post_show',
-                array('id' => $post->getId())
-            ));
+            return $this->redirectToRoute('admin_post_show', [
+                'id' => $post->getId()
+            ]);
         }
 
         // render the template
     }
 
 We recommend that you use a single action for both rendering the form and
-handling the form submit. For example, you *could* have a ``newAction()`` that
-*only* renders the form and a ``createAction()`` that *only* processes the form
+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
-``newAction()`` handle everything.
+``new()`` handle everything.

best_practices/security.rst

@@ -116,7 +116,7 @@ Using ``@Security``, this looks like:
      * @Route("/new", name="admin_post_new")
      * @Security("has_role('ROLE_ADMIN')")
      */
-    public function newAction()
+    public function new()
     {
         // ...
     }
@@ -139,7 +139,7 @@ method on the ``Post`` object:
      * @Route("/{id}/edit", name="admin_post_edit")
      * @Security("user.getEmail() == post.getAuthorEmail()")
      */
-    public function editAction(Post $post)
+    public function edit(Post $post)
     {
         // ...
     }
@@ -194,7 +194,7 @@ Now you can reuse this method both in the template and in the security expressio
      * @Route("/{id}/edit", name="admin_post_edit")
      * @Security("post.isAuthor(user)")
      */
-    public function editAction(Post $post)
+    public function edit(Post $post)
     {
         // ...
     }
@@ -222,7 +222,7 @@ more advanced use-case, you can always do the same security check in PHP:
     /**
      * @Route("/{id}/edit", name="admin_post_edit")
      */
-    public function editAction($id)
+    public function edit($id)
     {
         $post = $this->getDoctrine()
             ->getRepository(Post::class)
@@ -282,7 +282,7 @@ the same ``getAuthorEmail()`` logic you used above:
 
         protected function supports($attribute, $subject)
         {
-            if (!in_array($attribute, array(self::CREATE, self::EDIT))) {
+            if (!in_array($attribute, [self::CREATE, self::EDIT])) {
                 return false;
             }
 
@@ -306,7 +306,7 @@ the same ``getAuthorEmail()`` logic you used above:
             switch ($attribute) {
                 // if the user is an admin, allow them to create new posts
                 case self::CREATE:
-                    if ($this->decisionManager->decide($token, array('ROLE_ADMIN'))) {
+                    if ($this->decisionManager->decide($token, ['ROLE_ADMIN'])) {
                         return true;
                     }
 
@@ -338,7 +338,7 @@ Now, you can use the voter with the ``@Security`` annotation:
      * @Route("/{id}/edit", name="admin_post_edit")
      * @Security("is_granted('edit', post)")
      */
-    public function editAction(Post $post)
+    public function edit(Post $post)
     {
         // ...
     }
@@ -351,7 +351,7 @@ via the even easier shortcut in a controller:
     /**
      * @Route("/{id}/edit", name="admin_post_edit")
      */
-    public function editAction($id)
+    public function edit($id)
     {
         $post = ...; // query for the post