minor symfony#22 Added @method constraints where appropriate and added more help notes (javiereguiluz)

This PR was squashed before being merged into the master branch (closes symfony#22).

Discussion
----------

Added @method constraints where appropriate and added more help notes

Commits
-------

8d0cc81 Added @method constraints where appropriate and added more help notes

Author: javiereguiluz

src/AppBundle/Controller/Admin/BlogController.php

@@ -56,6 +56,11 @@ public function indexAction()
      * Creates a new Post entity.
      *
      * @Route("/new", name="admin_post_new")
+     * @Method({"GET", "POST"})
+     *
+     * NOTE: the Method annotation is optional, but it's a recommended practice
+     * to constraint the HTTP methods each controller responds to (by default
+     * it responds to all methods).
      */
     public function newAction(Request $request)
     {
@@ -84,12 +89,12 @@ public function newAction(Request $request)
     /**
      * Finds and displays a Post entity.
      *
-     * @Route("/{id}", name="admin_post_show")
+     * @Route("/{id}", requirements={"id" = "\d+"}, name="admin_post_show")
      * @Method("GET")
      * @Security("post.isAuthor(user)")
      *
-     *      NOTE:   You can also centralize security logic by using a "voter"
-     *              http://symfony.com/doc/current/cookbook/security/voters_data_permission.html
+     * NOTE: You can also centralize security logic by using a "voter"
+     * See http://symfony.com/doc/current/cookbook/security/voters_data_permission.html
      */
     public function showAction(Post $post)
     {
@@ -104,7 +109,8 @@ public function showAction(Post $post)
     /**
      * Displays a form to edit an existing Post entity.
      *
-     * @Route("/{id}/edit", name="admin_post_edit")
+     * @Route("/{id}/edit", requirements={"id" = "\d+"}, name="admin_post_edit")
+     * @Method({"GET", "POST"})
      * @Security("post.isAuthor(user)")
      */
     public function editAction(Post $post, Request $request)
@@ -136,6 +142,10 @@ public function editAction(Post $post, Request $request)
      * @Route("/{id}", name="admin_post_delete")
      * @Method("DELETE")
      * @Security("post.isAuthor(user)")
+     *
+     * The Security annotation value is an expression (if it evaluates to false,
+     * the authorization mechanism will prevent the user accessing this resource).
+     * The isAuthor() method is defined in the AppBundle\Entity\Post entity.
      */
     public function deleteAction(Request $request, Post $post)
     {
@@ -155,6 +165,12 @@ public function deleteAction(Request $request, Post $post)
     /**
      * Creates a form to delete a Post entity by id.
      *
+     * This is necessary because browsers don't support HTTP methods different
+     * from GET and POST. Since the controller that removes the blog posts expects
+     * a DELETE method, the trick is to create a simple form that *fakes* the
+     * HTTP DELETE method.
+     * See http://symfony.com/doc/current/cookbook/routing/method_parameters.html.
+     *
      * @param Post $post The post object
      *
      * @return \Symfony\Component\Form\Form The form

src/AppBundle/Controller/BlogController.php

@@ -45,6 +45,11 @@ public function indexAction()
 
     /**
      * @Route("/posts/{slug}", name="blog_post")
+     *
+     * NOTE: The $post controller argument is automatically injected by Symfony
+     * after performing a database query looking for a Post with the 'slug'
+     * value given in the route.
+     * See http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html
      */
     public function postShowAction(Post $post)
     {
@@ -54,12 +59,13 @@ public function postShowAction(Post $post)
     /**
      * @Route("/comment/{postSlug}/new", name = "comment_new")
      * @Security("is_granted('IS_AUTHENTICATED_FULLY')")
-     * @Method("POST")
-     *
-     * NOTE: The following ParamConverter mapping is required because the route parameter
-     * (postSlug) doesn't match any of the Doctrine entity properties (slug):
      *
+     * @Method("POST")
      * @ParamConverter("post", options={"mapping": {"postSlug": "slug"}})
+     *
+     * NOTE: The ParamConverter mapping is required because the route parameter
+     * (postSlug) doesn't match any of the Doctrine entity properties (slug).
+     * See http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/converters.html#doctrine-converter
      */
     public function commentNewAction(Request $request, Post $post)
     {
@@ -88,10 +94,12 @@ public function commentNewAction(Request $request, Post $post)
     }
 
     /**
-     * Called via the render() function in Twig.
+     * This controller is called directly via the render() function in the
+     * blog/post_show.html.twig template. That's why it's not needed to define
+     * a route name for it.
      *
      * The "id" of the Post is passed in and then turned into a Post object
-     * by the ParamConverter.
+     * automatically by the ParamConverter.
      *
      * @param Post $post
      *
@@ -107,6 +115,11 @@ public function commentFormAction(Post $post)
         ));
     }
 
+    /**
+     * This is a utility method used to create comment forms. It's recommended
+     * to not define this kind of methods in a controller class, but sometimes
+     * is convenient for defining small methods.
+     */
     private function createCommentForm()
     {
         $form = $this->createForm(new CommentType());

src/AppBundle/Controller/SecurityController.php

@@ -17,7 +17,7 @@
 
 /**
  * Controller used to manage the application security.
- * See http://symfony.com/doc/current/cookbook/security/form_login_setup.html
+ * See http://symfony.com/doc/current/cookbook/security/form_login_setup.html.
  *
  * @author Ryan Weaver <[email protected]>
  * @author Javier Eguiluz <[email protected]>