Add: fallback support

Author: jordyvanderhaegen

README.md

@@ -56,6 +56,25 @@ $post->title_nl
 $post->getTranslation('title', 'nl')
 ```
 
+### Using a fallback
+This package allows you to return the value of an attribute's `fallback_locale` defined in the `config/app.php` of your application.
+
+The third `useFallbackLocale` parameter of the `getTranslation` method may be used to control this behaviour:
+```php
+$post->title_en = 'Your first translation';
+$post->title_nl = null;
+$post->getTranslation('title', 'nl', true); // returns 'Your first translation'
+$post->getTranslation('title', 'nl', false); // returns null
+```
+
+Or you may use dedicated methods for this:
+```php
+$post->title_en = 'Your first translation';
+$post->title_nl = null;
+$post->getTranslationWithFallback('title', 'nl'); // returns 'Your first translation'
+$post->getTranslationWithoutFallback('title', 'nl'); // returns null
+```
+
 ### Setting translations
 
 To set the translation for the current locale you may use the attribute you have defined in the `translatable` property. Or you could pass it immediately when creating a model:

src/UnderscoreTranslatable.php

@@ -17,17 +17,31 @@ public function getTranslatableAttributeName(string $key, ?string $locale = null
         return $key . '_' . ($locale ?? App::getLocale());
     }
 
-    public function getTranslation(string $key, ?string $locale = null): mixed
+    public function getTranslation(string $key, ?string $locale = null, bool $useFallbackLocale = false): mixed
     {
         $value = $this->{$this->getTranslatableAttributeName($key, $locale)};
 
         if ($this->hasGetMutator($key)) {
-            return $this->mutateAttribute($key, $value);
+            $value = $this->mutateAttribute($key, $value);
+        }
+
+        if (empty($value) && $useFallbackLocale) {
+            $value = $this->getTranslation($key, config('app.fallback_locale', $locale), false);
         }
 
         return $value;
     }
 
+    public function getTranslationWithFallback(string $key, ?string $locale = null): mixed
+    {
+        return $this->getTranslation($key, $locale, true);
+    }
+
+    public function getTranslationWithoutFallback(string $key, ?string $locale = null): mixed
+    {
+        return $this->getTranslation($key, $locale, false);
+    }
+
     public function setTranslation(string $key, string $locale, mixed $value): self
     {
         if ($this->hasSetMutator($key)) {

tests/UnderscoreTranslatableTest.php

@@ -44,7 +44,7 @@ public function it_wont_interfere_when_setting_non_translatable_attributes()
     }
 
     /** @test */
-    public function it_can_get_a_translatable_attribute_using_a_method()
+    public function it_can_get_a_translation()
     {
         $post = new Post();
         $post->title_en = 'Test en';
@@ -56,7 +56,67 @@ public function it_can_get_a_translatable_attribute_using_a_method()
     }
 
     /** @test */
-    public function it_can_get_a_translatable_attribute_using_a_property()
+    public function it_can_get_a_translation_using_a_fallback()
+    {
+        $post = new Post();
+        $post->title_en = 'Test en';
+        $post->title_nl = 'Test nl';
+
+        $this->assertEquals('Test nl', $post->getTranslation('title', 'nl', true));
+        $this->assertEquals('Test en', $post->getTranslation('title', 'en', true));
+        $this->assertEquals('Test en', $post->getTranslation('title', 'fr', true));
+    }
+
+    /** @test */
+    public function it_can_get_a_translation_without_using_a_fallback()
+    {
+        $post = new Post();
+        $post->title_en = 'Test en';
+        $post->title_nl = 'Test nl';
+
+        $this->assertEquals('Test nl', $post->getTranslation('title', 'nl', false));
+        $this->assertEquals('Test en', $post->getTranslation('title', 'en', false));
+        $this->assertNull($post->getTranslation('title', 'fr', false));
+    }
+
+    /** @test */
+    public function it_can_get_a_translation_with_a_fallback()
+    {
+        $post = new Post();
+        $post->title_en = 'Test en';
+        $post->title_nl = 'Test nl';
+
+        $this->assertEquals('Test nl', $post->getTranslationWithFallback('title', 'nl'));
+        $this->assertEquals('Test en', $post->getTranslationWithFallback('title', 'en'));
+        $this->assertEquals('Test en', $post->getTranslationWithFallback('title', 'fr'));
+    }
+
+    /** @test */
+    public function it_can_get_a_translation_without_a_fallback()
+    {
+        $post = new Post();
+        $post->title_en = 'Test en';
+        $post->title_nl = 'Test nl';
+
+        $this->assertEquals('Test nl', $post->getTranslationWithoutFallback('title', 'nl'));
+        $this->assertEquals('Test en', $post->getTranslationWithoutFallback('title', 'en'));
+        $this->assertNull($post->getTranslationWithoutFallback('title', 'fr'));
+    }
+
+    /** @test */
+    public function it_can_get_a_translatable_attribute_using_a_method_with_a_fallback()
+    {
+        $post = new Post();
+        $post->title_en = 'Test en';
+        $post->title_nl = null;
+
+        $this->assertEquals('Test en', $post->getTranslation('title', 'nl', true));
+        $this->assertEquals('Test en', $post->getTranslation('title', 'en', true));
+        $this->assertEquals('Test en', $post->getTranslation('title', 'fr', true));
+    }
+
+    /** @test */
+    public function it_can_get_a_translation_using_a_property()
     {
         $post = new Post();
         $post->title_en = 'Test en';
@@ -73,7 +133,7 @@ public function it_can_get_a_translatable_attribute_using_a_property()
     }
 
     /** @test */
-    public function it_can_get_a_translatable_attribute_using_an_accessor()
+    public function it_can_get_a_translation_using_an_accessor()
     {
         $post = new Post();
         $post->field_with_accessor_en = 'Test en';