Improve documentation and update PhpDoc and method signatures (#22)

* Add missing information about Doctrine relationship. * Don't allow empty parameter on setters of Translation objects. * Cleanup some PhpDoc and method signatures * Update README.md Co-authored-by: Ashura <[email protected]>
Locastic · Jun 15, 2020 · 443d3ec · 443d3ec
1 parent 93d90a5
commit 443d3ec
Show file tree

Hide file tree

Showing 6 changed files with 36 additions and 36 deletions.
diff --git a/README.md b/README.md
@@ -30,22 +30,23 @@ Implementation:
 **Translatable entity:**
 
 - Extend your model/resource with `Locastic\ApiTranslationBundle\Model\AbstractTranslatable`
-- Add createTranslation method which returns new object of translation Entity. Example:
+- Add `createTranslation()` method which returns new object of translation Entity. Example:
 ``` php
 use Locastic\ApiPlatformTranslationBundle\Model\AbstractTranslatable;
+use Locastic\ApiPlatformTranslationBundle\Model\TranslationInterface;
 
 class Post extends AbstractTranslatable
 {
     // ...
 
-    protected function createTranslation()
+    protected function createTranslation(): TranslationInterface
     {
         return new PostTranslation();
     }
 }
 ```
 
-- Add `translations` serialization group to translations relation:
+- Add a `translations`-property. Add the `translations` serializations group and make a connection to the translation entity:
 ``` php
 use Locastic\ApiPlatformTranslationBundle\Model\AbstractTranslatable;
 
@@ -54,6 +55,8 @@ class Post extends AbstractTranslatable
     // ...
 
     /**
+     * @ORM\OneToMany(targetEntity="PostTranslation", mappedBy="translatable", fetch="EXTRA_LAZY", indexBy="locale", cascade={"PERSIST"}, orphanRemoval=true)
+     *
      * @Groups({"post_write", "translations"})
      */
     protected $translations;
@@ -71,20 +74,16 @@ class Post extends AbstractTranslatable
     // ...
 
     /**
-    * @var string
-    *
     * @Groups({"post_read"})
     */
     private $title;
 
-    public function setTitle($title)
+    public function setTitle(string $title)
     {
         $this->getTranslation()->setTitle($title);
-
-        return $this;
     }
 
-    public function getTitle()
+    public function getTitle(): ?string
     {
         return $this->getTranslation()->getTitle();
     }
@@ -104,28 +103,32 @@ use Locastic\ApiPlatformTranslationBundle\Model\AbstractTranslation;
 class PostTranslation extends AbstractTranslation
 {
     // ...
+
+    /**
+     * @ORM\ManyToOne(targetEntity="Post", inversedBy="translations")
+     */
+    protected $translatable;
 
     /**
-     * @var string
-     *
+     * @ORM\Column(type="string")
+     * 
      * @Groups({"post_read", "post_write", "translations"})
      */
     private $title;
 
     /**
-     * @var string
+     * @ORM\Column(type="string")
+     *
      * @Groups({"post_write", "translations"})
      */
     protected $locale;
 
-    public function setTitle($title)
+    public function setTitle(string $title): void
     {
         $this->title = $title;
-
-        return $this;
     }
 
-    public function getTitle()
+    public function getTitle(): ?string
     {
         return $this->title;
     }

diff --git a/src/Model/AbstractTranslation.php b/src/Model/AbstractTranslation.php
@@ -33,7 +33,7 @@ public function getTranslatable(): ?TranslatableInterface
     /**
      * {@inheritdoc}
      */
-    public function setTranslatable(?TranslatableInterface $translatable = null): void
+    public function setTranslatable(?TranslatableInterface $translatable): void
     {
         if ($translatable === $this->translatable) {
             return;

diff --git a/src/Model/TranslatableInterface.php b/src/Model/TranslatableInterface.php
@@ -4,7 +4,7 @@
 
 namespace Locastic\ApiPlatformTranslationBundle\Model;
 
-use Doctrine\Common\Collections\ArrayCollection;
+use Doctrine\Common\Collections\Collection;
 
 /**
  * Interface TranslatableInterface
@@ -14,9 +14,9 @@
 interface TranslatableInterface
 {
     /**
-     * @return ArrayCollection|TranslationInterface[]
+     * @return Collection<TranslationInterface>|TranslationInterface[]
      */
-    public function getTranslations();
+    public function getTranslations(): Collection;
 
     /**
      * @param null|string $locale

diff --git a/src/Model/TranslatableTrait.php b/src/Model/TranslatableTrait.php
@@ -5,6 +5,7 @@
 namespace Locastic\ApiPlatformTranslationBundle\Model;
 
 use Doctrine\Common\Collections\ArrayCollection;
+use Doctrine\Common\Collections\Collection;
 use Doctrine\Common\Collections\Criteria;
 use Doctrine\Common\Collections\Expr\Comparison;
 use Doctrine\ORM\PersistentCollection;
@@ -17,7 +18,7 @@
 trait TranslatableTrait
 {
     /**
-     * @var ArrayCollection|PersistentCollection|TranslationInterface[]
+     * @var Collection<TranslationInterface>|TranslationInterface[]
      */
     protected $translations;
 
@@ -53,9 +54,7 @@ public function __construct()
     }
 
     /**
-     * @param null|string $locale
-     *
-     * @return TranslationInterface
+     * {@inheritdoc}
      *
      * @throws \RuntimeException
      */
@@ -132,17 +131,15 @@ public function removeTranslationWithLocale(string $locale): void
     }
 
     /**
-     * @return ArrayCollection|TranslationInterface[]
+     * {@inheritdoc}
      */
-    public function getTranslations()
+    public function getTranslations(): Collection
     {
         return $this->translations;
     }
 
     /**
-     * @param TranslationInterface $translation
-     *
-     * @return bool
+     * {@inheritdoc}
      */
     public function hasTranslation(TranslationInterface $translation): bool
     {
@@ -152,7 +149,7 @@ public function hasTranslation(TranslationInterface $translation): bool
     }
 
     /**
-     * @param TranslationInterface $translation
+     * {@inheritdoc}
      */
     public function addTranslation(TranslationInterface $translation): void
     {
@@ -165,7 +162,7 @@ public function addTranslation(TranslationInterface $translation): void
     }
 
     /**
-     * @param TranslationInterface $translation
+     * {@inheritdoc}
      */
     public function removeTranslation(TranslationInterface $translation): void
     {
@@ -177,15 +174,15 @@ public function removeTranslation(TranslationInterface $translation): void
     }
 
     /**
-     * @param null|string $currentLocale
+     * {@inheritdoc}
      */
     public function setCurrentLocale(?string $currentLocale): void
     {
         $this->currentLocale = $currentLocale;
     }
 
     /**
-     * @param null|string $fallbackLocale
+     * {@inheritdoc}
      */
     public function setFallbackLocale(?string $fallbackLocale): void
     {

diff --git a/src/Model/TranslationInterface.php b/src/Model/TranslationInterface.php
@@ -15,9 +15,9 @@ interface TranslationInterface
     public function getTranslatable(): ?TranslatableInterface;
 
     /**
-     * @param null|TranslatableInterface $translatable
+     * @param TranslatableInterface $translatable
      */
-    public function setTranslatable(?TranslatableInterface $translatable = null): void;
+    public function setTranslatable(?TranslatableInterface $translatable): void;
 
     /**
      * @return null|string

diff --git a/src/Translation/Translator.php b/src/Translation/Translator.php
@@ -46,7 +46,7 @@ public function __construct(TranslatorInterface $translator, RequestStack $reque
     /**
      * {@inheritdoc}
      */
-    public function trans($id, array $parameters = array(), $domain = null, $locale = null): string
+    public function trans($id, array $parameters = array(), string $domain = null, string $locale = null): string
     {
         if (!$locale) {
             $locale = $this->loadCurrentLocale();