Merge pull request #30 from Hi-Folks/feat/29-getstring

the getString() method

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
 

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.
 

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);
+    }
 }

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");
+    },
+);