Optimize setCode, enhance has, and minor cleanup

- Prevent calling setCode if the code hasn’t changed.
- Added $checkDefault argument to the has method in the Localizer class.
- Code cleanup and minor tweaks across files.

Author: nabeghe

.phpunit.result.cache

@@ -1 +1 @@
-{"version":1,"defects":{"ArrayBasedTranslators::testForDefaultTranslation":3,"ArrayBasedTranslators::testForDifferentTranslator":3,"ClassBasedTranslators::testForDefaultTranslation":3,"ClassBasedTranslators::testForDifferentTranslator":3,"ArrayBasedTranslatorsTest::testRandom":3},"times":{"ArrayBasedTranslators::testForGet":0.007,"ArrayBasedTranslators::testForDefaultTranslation":0.001,"ArrayBasedTranslators::testForDifferentTranslator":0,"ClassBasedTranslators::testDynamicMessage":0.156,"ClassBasedTranslators::testForGet":0.005,"ClassBasedTranslators::testForDefaultTranslation":0,"ClassBasedTranslators::testForDifferentTranslator":0,"ArrayBasedTranslatorsTest::testForGet":0.006,"ArrayBasedTranslatorsTest::testForDefaultTranslation":0,"ArrayBasedTranslatorsTest::testForDifferentTranslator":0.001,"ArrayBasedTranslatorsTest::testRandom":0,"ClassBasedTranslatorsTest::testForGet":0.013,"ClassBasedTranslatorsTest::testForDefaultTranslation":0.001,"ClassBasedTranslatorsTest::testForDifferentTranslator":0.001,"ClassBasedTranslatorsTest::testRandom":0}}
+{"version":1,"defects":{"ArrayBasedTranslators::testForDefaultTranslation":3,"ArrayBasedTranslators::testForDifferentTranslator":3,"ClassBasedTranslators::testForDefaultTranslation":3,"ClassBasedTranslators::testForDifferentTranslator":3,"ArrayBasedTranslatorsTest::testRandom":3},"times":{"ArrayBasedTranslators::testForGet":0.007,"ArrayBasedTranslators::testForDefaultTranslation":0.001,"ArrayBasedTranslators::testForDifferentTranslator":0,"ClassBasedTranslators::testDynamicMessage":0.156,"ClassBasedTranslators::testForGet":0.005,"ClassBasedTranslators::testForDefaultTranslation":0,"ClassBasedTranslators::testForDifferentTranslator":0,"ArrayBasedTranslatorsTest::testForGet":0.012,"ArrayBasedTranslatorsTest::testForDefaultTranslation":0.002,"ArrayBasedTranslatorsTest::testForDifferentTranslator":0.001,"ArrayBasedTranslatorsTest::testRandom":0,"ClassBasedTranslatorsTest::testForGet":0.005,"ClassBasedTranslatorsTest::testForDefaultTranslation":0,"ClassBasedTranslatorsTest::testForDifferentTranslator":0,"ClassBasedTranslatorsTest::testRandom":0}}

README.md

@@ -15,21 +15,15 @@ composer require nabeghe/light-localization
 ### 📁 Localization Directory
 
 - Create a directory for localization.
-- In this directory, create new folders, each of these folders actually represent Localization codes.
+- In this directory, create new folders, each of these folders actually represent localization codes.
   They can be language codes or anything else.
 - Inside each code directory, php files will be placed, each of these files has the role of a translator.
-
   - These files can return an array or an object that inheritance from `Nabeghe\LightLocalization\Translator` class.
   - If it's an array, each key is a translation key & it will represent a value,
-  but if it's an object, each field or method is a translation key.
-  The priority is with the method & it must return a value.
-  - With the method, you can have dynamic localization!
+    but if it's an object, each field or method is a translation key.
+    The priority is with the method & it must return a value.
   - Objects can implement the `ArrayAccess` interface in addition to inheriting from the mentioned class.
 
-### Examples
-
-Check the examples folder in the repositiry.
-
 ```php
 use Nabeghe\LightLocalization\Localizer;
 
@@ -55,19 +49,20 @@ echo $localizer->get('hello', 'messages');
 ```
 
 **Notice:** The localization code can be specified in the constructor method.
-Of course, it's possible to change it later via method `recode`.
+Of course, it's possible to change it later via method `setCode`.
 
-**Notice:** "For each localizer, a default localizer can be specified in the constructor.
-Additionally, instead of specifying a default localizer, a string can be designated as the default translation."
+**Notice:** For each localizer, a default localizer can be specified in the constructor.
+Additionally, instead of specifying a default localizer, a string can be designated as the default translation.
 
 ## 🧩 Features
 
 - Get the value (translation) using the key.
+- Fetch random translations from keys with array of strings using the `rnd` method instead of `get`.
 - Localization code (the second parameter of Localizer constructor).
 - Default translation that can be a string or another localizer.
   (the third parameter of Localizer constructor).
-- Create different translators in different files.
-- Dynamic translations using methods in the class-based translation files.
+- Create different translators in different files and array-based or class-based translations.
+- Dynamic translations.
 - Reload the translator.
 - Remove the loaded translator.
 - Refreshing translators and reloading them.

src/Localizer.php

@@ -20,11 +20,8 @@ class Localizer implements LocalizerInterface
 
     /**
      * Default translation that can be a string or another localizer.
-     * If the key is not found in the translation, the default will be used.
-     * If the default is a string, the string itself will be returned instead of the default translation,
-     * but if it's a localizer object, it's `get` method will be used to retrieve the translation.
-     * @see self::get()
      * @var Localizer|string
+     * @see self::get()
      */
     protected $defaultTranslation;
 
@@ -34,30 +31,24 @@ class Localizer implements LocalizerInterface
      */
     protected array $translators = [];
 
-    /**
-     * Retrieves the root path.
-     */
     public function getPath(): string
     {
         return $this->path;
     }
 
-    /**
-     * Retrieves the current language code.
-     */
     public function getCode(): string
     {
         return $this->code;
     }
 
-    /**
-     * Changes the localization code.
-     * @param  string  $code  New code.
-     * @param  bool  $refresh  Optional. After changing the code, should it reload the loaded translators or remove all of them from the loaded state? Default false.
-     */
     public function setCode(string $code, bool $refresh = false): void
     {
+        if ($this->code == $code) {
+            return;
+        }
+
         $this->code = $code;
+
         if ($refresh) {
             $this->refresh();
         } else {
@@ -73,18 +64,11 @@ public function recode(string $code, bool $refresh = false): void
         $this->setCode($code, $refresh);
     }
 
-    /**
-     * Retrieves the default translation.
-     */
     public function getDefaultTranslation()
     {
         return $this->defaultTranslation;
     }
 
-    /**
-     * Retrieves the list of loaded translators.
-     * @return array
-     */
     public function getTranslators(): array
     {
         return $this->translators;
@@ -94,7 +78,7 @@ public function getTranslators(): array
      * Constructor.
      * @param  string  $path  The root path where the directories related to the codes are located.
      * @param  string  $code  Optional. Localization code. Default `generic`.
-     * @param  Localizer|string  $defaultTranslation  Optional. Default translation. Default is empty string.
+     * @param  Localizer|string  $defaultTranslation  Optional. Default translation. Default value is an emoty string.
      */
     public function __construct(string $path, string $code = self::DEFAULT_CODE, $defaultTranslation = '')
     {
@@ -103,60 +87,40 @@ public function __construct(string $path, string $code = self::DEFAULT_CODE, $de
         $this->defaultTranslation = $defaultTranslation;
     }
 
-    /**
-     * Retrieves the file path of a translator.
-     * @param  string  $translator  Optional. The translator file name without `.php` extension. Default `main`.
-     * @return string
-     */
     public function getTranslatorPath(string $translator = self::DEFAULT_TRANSLATOR): string
     {
         return "$this->path/$this->code/$translator.php";
     }
 
-    /**
-     * Checks whether the translator exists or not.
-     * @param  string  $translator  Translator Translator file name.
-     * @return bool
-     */
     public function translatorExists(string $translator = self::DEFAULT_TRANSLATOR): bool
     {
         return file_exists($this->getTranslatorPath($translator));
     }
 
-    /**
-     * Checks if a translator is loaded before or not.
-     * @param  string  $translator  Translator file name.
-     * @return bool
-     */
     public function isLoaded(string $translator): bool
     {
         return isset($this->translators[$translator]);
     }
 
-    /**
-     * Loads a translator even if it is already loaded.
-     * @param  string  $translator  Translator file name.
-     * @return bool
-     */
     public function load($translator = self::DEFAULT_TRANSLATOR): bool
     {
         $success = false;
-        $branch_path = $this->getTranslatorPath($translator);
-        if (file_exists($branch_path)) {
-            $new_data = include $branch_path;
-            if (!$new_data) {
+
+        $translator_path = $this->getTranslatorPath($translator);
+        if (file_exists($translator_path)) {
+            $new_data = include $translator_path;
+            if (!is_array($new_data)) {
                 $new_data = [];
             } else {
                 $success = true;
             }
         }
+
         $this->translators[$translator] = $new_data ?? [];
+
         return $success;
     }
 
-    /**
-     * Loads all loaded translators from the beginning.
-     */
     public function refresh(): void
     {
         $translators_names = array_keys($this->translators);
@@ -165,73 +129,58 @@ public function refresh(): void
         }
     }
 
-    /**
-     * Removes a translator from loaded state.
-     * @param  string  $translator  Translator file name.
-     * @return bool
-     */
     public function unload(string $translator = self::DEFAULT_TRANSLATOR): bool
     {
         if (isset($this->translators[$translator])) {
             unset($this->translators[$translator]);
             return true;
         }
+
         return false;
     }
 
-    /**
-     * Checks whether a key exists in a translator or not.
-     * @param  string  $key
-     * @param  string  $translator  Translator file name.
-     * @return bool
-     */
-    public function has(string $key, $translator = self::DEFAULT_TRANSLATOR)
+    public function has(string $key, $translator = self::DEFAULT_TRANSLATOR, bool $checkDefault = true): bool
     {
         if (!isset($this->translators[$translator])) {
             $this->load($translator);
         }
+
         return isset($this->translators[$translator][$key])
-            || (!is_string($this->defaultTranslation) && $this->defaultTranslation->has($key, $translator));
+            || ($checkDefault && !is_string($this->defaultTranslation) && $this->defaultTranslation->has($key, $translator, $checkDefault));
     }
 
-    /**
-     * Retrieves a string or translation using its key.
-     * @param  string  $key  The key is in the translator.
-     * @param  string  $translator  Translator file name.
-     * @return string|mixed
-     */
     public function get(string $key, string $translator = self::DEFAULT_TRANSLATOR)
     {
         if (!isset($this->translators[$translator])) {
             $this->load($translator);
         }
+
         if (isset($this->translators[$translator][$key])) {
             return $this->translators[$translator][$key];
         }
+
         if (is_string($this->defaultTranslation)) {
             return $this->defaultTranslation;
         }
+
         return $this->defaultTranslation->get($key, $translator);
     }
 
-    /**
-     * It's's similar to the {@see self::get()} method, with the difference that if the output is an array, it randomly returns one of the values within it.
-     * @param  string  $key
-     * @param  string  $translator
-     * @return mixed|Localizer|string
-     */
     public function rnd(string $key, string $translator = self::DEFAULT_TRANSLATOR)
     {
         $text = $this->get($key, $translator);
         if (!is_array($text)) {
             return $text;
         }
+
         if ($text) {
             return $text[array_rand($text)];
         }
+
         if (is_string($this->defaultTranslation)) {
             return $this->defaultTranslation;
         }
+
         return $this->defaultTranslation->get($key, $translator);
     }
 }

src/LocalizerInterface.php

@@ -34,18 +34,19 @@ public function getCode();
     public function setCode(string $code, bool $refresh = false);
 
     /**
-     * Retrieves the default translation.
+     * Returns the default translation.
+     * @return Localizer|string
      */
     public function getDefaultTranslation();
 
     /**
-     * Retrieves the list of loaded translators.
+     * Returns the list of loaded translators.
      * @return array
      */
     public function getTranslators(): array;
 
     /**
-     * Retrieves the file path of a translator.
+     * Returns the file path of a translator.
      * @param  string  $translator  Optional. The translator file name without `.php` extension. Default `main`.
      * @return string
      */
@@ -85,23 +86,24 @@ public function refresh();
     public function unload(string $translator = self::DEFAULT_TRANSLATOR);
 
     /**
-     * Checks whether a key exists in a translator or not.
+     * Checks whether a key exists in a translator or not.<br>
      * @param  string  $key
      * @param  string  $translator  Translator file name.
+     * @param  bool  $checkDefault  Should the default translation also be checked if it is a Localizer? Default true.
      * @return bool
      */
-    public function has(string $key, $translator = self::DEFAULT_TRANSLATOR);
+    public function has(string $key, $translator = self::DEFAULT_TRANSLATOR, bool $checkDefault = true): bool;
 
     /**
-     * Retrieves a string or translation using its key.
+     * Returns a string or translation using its key.
      * @param  string  $key  The key is in the translator.
      * @param  string  $translator  Translator file name.
      * @return string|mixed
      */
     public function get(string $key, string $translator = self::DEFAULT_TRANSLATOR);
 
     /**
-     * It's's similar to the {@see self::get()} method, with the difference that if the output is an array, it randomly returns one of the values within it.
+     * It's similar to the {@see self::get()} method, with the difference that if the output is an array, it randomly returns one of the values within it.
      * @param  string  $key
      * @param  string  $translator
      * @return mixed|Localizer|string

tests/LocalizerCase.php

@@ -1,7 +1,7 @@
 <?php declare(strict_types=1);
 
-use Nabeghe\LightLocalization\Localizer;
 use PHPUnit\Framework\TestCase;
+use Nabeghe\LightLocalization\Localizer;
 
 abstract class LocalizerCase extends TestCase
 {
@@ -16,6 +16,7 @@ public function __construct(?string $name = null, array $data = [], $dataName =
             'fa',
             new Localizer(__DIR__.'/data/'.$this->getTranslatorsDirectoryName(), 'en'),
         );
+
         parent::__construct($name, $data, $dataName);
     }
 
@@ -37,6 +38,7 @@ public function testForDifferentTranslator(): void
     {
         $expected = 'Hadi Akbarzadeh';
         $translated = $this->localizer->get('name', 'developer'); // from `developer.php` file.
+
         $this->assertSame($expected, $translated);
     }