v1.1.0

Added new method `rnd`, which is used to return a random text if the value is an array.
Added LocalizerInterface.php

.phpunit.result.cache

@@ -1 +1 @@
-{"version":1,"defects":{"ArrayBasedTranslators::testForDefaultTranslation":3,"ArrayBasedTranslators::testForDifferentTranslator":3,"ClassBasedTranslators::testForDefaultTranslation":3,"ClassBasedTranslators::testForDifferentTranslator":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}}
+{"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}}

composer.json

@@ -2,7 +2,7 @@
   "name": "nabeghe/light-localization",
   "description": "A light weight, key-value & path-based PHP localization library that translations are loaded up when needed.",
   "type": "library",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "homepage": "https://github.com/nabeghe/light-localization",
   "license": "MIT",
   "autoload": {
@@ -22,7 +22,7 @@
     "test": "vendor/bin/phpunit tests"
   },
   "require": {
-    "php": ">=7.4"
+    "php": ">=8.1"
   },
   "require-dev": {
     "phpunit/phpunit": "^9.0"

src/Localizer.php

@@ -4,13 +4,8 @@
  * Localizer class.
  * @package Nabeghe\LightLocalization
  */
-class Localizer
+class Localizer implements LocalizerInterface
 {
-    /**
-     * Default translator name.
-     */
-    public const DEFAULT_TRANSLATOR = 'main';
-
     /**
      * The root path, where the directories related to the language codes are located.
      * @var string
@@ -101,7 +96,7 @@ public function getTranslators(): array
      * @param  string  $code  Optional. Localization code. Default `generic`.
      * @param  Localizer|string  $defaultTranslation  Optional. Default translation. Default is empty string.
      */
-    public function __construct(string $path, string $code = 'generic', $defaultTranslation = '')
+    public function __construct(string $path, string $code = self::DEFAULT_CODE, $defaultTranslation = '')
     {
         $this->path = rtrim($path, '/');
         $this->code = $code;
@@ -218,4 +213,25 @@ public function get(string $key, string $translator = self::DEFAULT_TRANSLATOR)
         }
         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

@@ -0,0 +1,110 @@
+<?php namespace Nabeghe\LightLocalization;
+
+/**
+ * Localizer interface.
+ * @package Nabeghe\LightLocalization
+ */
+interface LocalizerInterface
+{
+    /**
+     * Default translator name.
+     */
+    public const DEFAULT_TRANSLATOR = 'main';
+
+    /**
+     * Default translator code.
+     */
+    public const DEFAULT_CODE = 'generic';
+
+    /**
+     * Retrieves the root path.
+     */
+    public function getPath();
+
+    /**
+     * Retrieves the current language code.
+     */
+    public function getCode();
+
+    /**
+     * 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);
+
+    /**
+     * Retrieves the default translation.
+     */
+    public function getDefaultTranslation();
+
+    /**
+     * Retrieves the list of loaded translators.
+     * @return array
+     */
+    public function getTranslators(): array;
+
+    /**
+     * 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);
+
+    /**
+     * Checks whether the translator exists or not.
+     * @param  string  $translator  Translator Translator file name.
+     * @return bool
+     */
+    public function translatorExists(string $translator = self::DEFAULT_TRANSLATOR);
+
+    /**
+     * Checks if a translator is loaded before or not.
+     * @param  string  $translator  Translator file name.
+     * @return bool
+     */
+    public function isLoaded(string $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);
+
+    /**
+     * Loads all loaded translators from the beginning.
+     */
+    public function refresh();
+
+    /**
+     * Removes a translator from loaded state.
+     * @param  string  $translator  Translator file name.
+     * @return bool
+     */
+    public function unload(string $translator = self::DEFAULT_TRANSLATOR);
+
+    /**
+     * 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);
+
+    /**
+     * 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);
+
+    /**
+     * 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);
+}

tests/LocalizerCase.php

@@ -36,7 +36,16 @@ public function testForDefaultTranslation(): void
     public function testForDifferentTranslator(): void
     {
         $expected = 'Hadi Akbarzadeh';
-        $translated = $this->localizer->get('name', 'developer'); // from `names.php` file.
+        $translated = $this->localizer->get('name', 'developer'); // from `developer.php` file.
         $this->assertSame($expected, $translated);
     }
+
+    public function testRandom(): void
+    {
+        $expected = 'Hadi Akbarzadeh';
+        $translated = $this->localizer->rnd('symbol', 'developer'); // from `developer.php` file.
+        $this->assertSame(true, in_array($translated, [
+            'H', 'A', 'D', 'I', 'E', 'L', 'S', 'A',
+        ]));
+    }
 }

tests/data/array/en/developer.php

@@ -3,4 +3,7 @@
 return [
     'name' => 'Hadi Akbarzadeh',
     'github' => 'https://github.com/nabeghe',
+    'symbol' => [
+        'H', 'A', 'D', 'I', 'E', 'L', 'S', 'A',
+    ],
 ];

tests/data/class/en/developer.php

@@ -4,4 +4,8 @@
 
     public string $github = 'https://github.com/nabeghe';
 
+    public array $symbol = [
+        'H', 'A', 'D', 'I', 'E', 'L', 'S', 'A',
+    ];
+
 };