minor #450 Cleanup and comments about Tags feature implementation (yceruto, javiereguiluz)

This PR was merged into the master branch.

Discussion
----------

Cleanup and comments about Tags feature implementation

* Removed unused old `isAuthor()` method from `Post`
* Removed useless PHPDoc
* Add code comments about Tags feature implementation
* Removed setByReference option which is unnecessary now.

Commits
-------

6147bbd Updated the last help note
a62876f Updated some help notes
4d71179 Updated a help note
a574d24 Remove byReference option which is unnecessary now
ba34c26 Cleanup and comments about Tags feature implementation

Author: javiereguiluz

src/AppBundle/Entity/Post.php

@@ -186,14 +186,6 @@ public function setAuthor(User $author)
         $this->author = $author;
     }
 
-    /**
-     * Is the given User the author of this Post?
-     */
-    public function isAuthor(User $user = null)
-    {
-        return $user === $this->author;
-    }
-
     public function getComments()
     {
         return $this->comments;

src/AppBundle/Entity/Tag.php

@@ -55,6 +55,10 @@ public function getName()
      */
     public function jsonSerialize()
     {
+        // This entity implements JsonSerializable (http://php.net/manual/en/class.jsonserializable.php)
+        // so this method is used to customize its JSON representation when json_encode()
+        // is called, for example in tags|json_encode (app/Resources/views/form/fields.html.twig)
+
         return $this->name;
     }
 

src/AppBundle/Form/DataTransformer/TagArrayToStringTransformer.php

@@ -37,6 +37,10 @@ public function __construct(ObjectManager $manager)
      */
     public function transform($array)
     {
+        // The value received is an array of Tag objects generated with
+        // Symfony\Bridge\Doctrine\Form\DataTransformer\CollectionToArrayTransformer::transform()
+        // The value returned is a string that concatenates the string representation of those objects
+
         /* @var Tag[] $array */
         return implode(',', $array);
     }
@@ -52,17 +56,22 @@ public function reverseTransform($string)
 
         $names = explode(',', $string);
 
+        // Get the current tags and find the new ones that should be created.
         $tags = $this->manager->getRepository(Tag::class)->findBy([
             'name' => $names,
         ]);
-
         $newNames = array_diff($names, $tags);
         foreach ($newNames as $name) {
             $tag = new Tag();
             $tag->setName($name);
             $tags[] = $tag;
+
+            // There's no need to persist these new tags because Doctrine does that automatically
+            // thanks to the cascade={"persist"} option in the AppBundle\Entity\Post::$tags property.
         }
 
+        // Return an array of tags to transform them back into a Doctrine Collection.
+        // See Symfony\Bridge\Doctrine\Form\DataTransformer\CollectionToArrayTransformer::reverseTransform()
         return $tags;
     }
 }

src/AppBundle/Form/Type/DateTimePickerType.php

@@ -28,9 +28,6 @@
  */
 class DateTimePickerType extends AbstractType
 {
-    /**
-     * @var MomentFormatConverter
-     */
     private $formatConverter;
 
     public function __construct()

src/AppBundle/Form/Type/TagsInputType.php

@@ -44,9 +44,12 @@ public function __construct(ObjectManager $manager)
     public function buildForm(FormBuilderInterface $builder, array $options)
     {
         $builder
-            ->setByReference(false)
-            ->addModelTransformer(new TagArrayToStringTransformer($this->manager))
-            ->addModelTransformer(new CollectionToArrayTransformer())
+            // The Tag collection must be transformed into a comma separated string.
+            // We could create a custom transformer to do Collection <-> string in one step,
+            // but here we're doing the transformation in two steps (Collection <-> array <-> string)
+            // and reuse the existing CollectionToArrayTransformer.
+            ->addModelTransformer(new CollectionToArrayTransformer(), true)
+            ->addModelTransformer(new TagArrayToStringTransformer($this->manager), true)
         ;
     }