From 76cf3bf174299909e84945e4a0b7b7962bddba1a Mon Sep 17 00:00:00 2001
From: Roberto Butti <roberto.butti@gmail.com>
Date: Sat, 12 Oct 2024 18:54:56 +0200
Subject: [PATCH] the getString() method

---
 CHANGELOG.md                              |  3 +++
 README.md                                 | 15 +++++++++++++++
 src/Traits/FormattableBlock.php           | 15 +++++++++++++++
 tests/Unit/Traits/FormattableBlokTest.php | 19 +++++++++++++++++++
 4 files changed, 52 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index f13aae5..fb86bc0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,8 @@
 # Changelog
 
+## 0.4.2 - WIP
+- Implementing `getString()` for returning a string
+
 ## 0.4.1 - 2024-10-11
 - Implementing `getFormattedByte()` for getting value as formatted byte
 
diff --git a/README.md b/README.md
index ecb4e00..01992d5 100644
--- a/README.md
+++ b/README.md
@@ -201,6 +201,21 @@ Key Features:
 - Automatic unit conversion: converts bytes into appropriate units (e.g., KB, MB, GB) based on the size.
 - customizable precision: you can specify the number of decimal places for the output, making it flexible for various use cases.
 
+### The `getString()` method
+
+The `getString()` method retrieves the value of a specified field as a string from a data block. If the field does not exist or is null, it returns a default value, which can be customized.
+Parameters:
+- `$path` (string): The path to the field (e.g., "0.commit.author.date").
+- `$default` (string): (Optional) The default value to return if the field doesn't exist. Defaults to an empty string ("").
+
+Example Usage:
+```php
+$data1->getString("0.commit.author.date");  // Returns the field value as a string
+$data1->getString("0.commit.author.notexists");  // Returns ""
+$data1->getString("0.commit.author.notexists", "AA");  // Returns "AA"
+$data1->getString("0.commit.comment_count");  // Returns "0" as a string even if the field value is an integer
+```
+
 ### The `getBlock()` method
 If you need to manage a complex array (nested array) or an array obtained from a complex JSON structure, you can access a portion of the array and obtain the `Block` object via the `getBlock()` method.
 
diff --git a/src/Traits/FormattableBlock.php b/src/Traits/FormattableBlock.php
index b4b6bd0..2ae4f15 100644
--- a/src/Traits/FormattableBlock.php
+++ b/src/Traits/FormattableBlock.php
@@ -69,4 +69,19 @@ public function getFormattedByte(
 
         return number_format($bytes / $terabyte, $precision) . ' TB';
     }
+
+    /**
+     * Return a forced string value from the get() method
+     * @param mixed $key the filed key , can be nested for example "commits.0.name"
+     * @param string|null $defaultValue the default value returned if no value is found
+     * @param non-empty-string $charNestedKey for nested field the . character is the default
+     * @return string
+     */
+    public function getString(
+        mixed $key,
+        string $defaultValue = null,
+        string $charNestedKey = ".",
+    ): string {
+        return (string) $this->get($key, $defaultValue, $charNestedKey);
+    }
 }
diff --git a/tests/Unit/Traits/FormattableBlokTest.php b/tests/Unit/Traits/FormattableBlokTest.php
index 97072e0..bd66c7e 100644
--- a/tests/Unit/Traits/FormattableBlokTest.php
+++ b/tests/Unit/Traits/FormattableBlokTest.php
@@ -57,3 +57,22 @@ function (): void {
         expect($data1->getFormattedByte("assets.1.total_bytes", 0))->toBe("2 GB");
     },
 );
+
+test(
+    'Force field to string',
+    function (): void {
+        $data1 = Block::fromJsonFile(__DIR__ . "/../../data/commits-json/commits-10-p1.json");
+        $data2 = Block::fromJsonFile(__DIR__ . "/../../data/commits-json/commits-10-p2.json");
+        $data3 = Block::fromJsonFile(__DIR__ . "/../../data/commits-json/commits-10-p3.json");
+        $data1->append($data2)->append($data3);
+        expect($data1)->toHaveCount(30);
+        expect($data2)->toHaveCount(10);
+        expect($data1->getString("0.commit.author.date"))->toBeString();
+        expect($data1->getString("0.commit.author.notexist"))->toBeString();
+        expect($data1->getString("0.commit.author.notexist"))->toEqual("");
+        expect($data1->getString("0.commit.author.notexist", "AA"))->toEqual("AA");
+        expect($data1->getString("0.commit.comment_count"))->toBeString()->toEqual("0");
+        expect($data1->getString("0.commit.comment_count", 1))->toBeString()->toEqual("0");
+        expect($data1->getString("0.commit.comment_countnotexists", 1))->toBeString()->toEqual("1");
+    },
+);