Merge pull request #48 from Hi-Folks/feat/getstringstrict

Implementing getStringStrict()

Author: roberto-butti

CHANGELOG.md

@@ -1,7 +1,8 @@
 # Changelog
 
-## 1.0.2 - WIP
-- - Adding `getIntStrict()` method for returning strict int.
+## 1.0.2 - 2025-10-05
+- Adding `getIntStrict()` method for returning strict int.
+- Adding `getStringStrict()` method for returning strict string.
 
 ## 1.0.1 - 2025-10-04
 - Adding `getInt()` method for returing casted integer value.

README.md

@@ -263,19 +263,37 @@ Key Features:
 ### 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 ("").
+- `$default` (string|null): (Optional) The default value to return if the field doesn't exist. Defaults to null.
 
 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");  // Returns null
 $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 `getStringStrict()` method
+
+The `getStringStrict()` 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 string value, which can be customized ("" by default).
+
+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 "".
+
+Example Usage:
+```php
+$data1->getStringStrict("0.commit.author.date");  // Returns the field value as a string
+$data1->getStringStrict("0.commit.author.notexists");  // Returns an empty string ""
+$data1->getStringStrict("0.commit.author.notexists", "AA");  // Returns "AA"
+$data1->getStringStrict("0.commit.comment_count");  // Returns "0" as a string even if the field value is an integer
+```
+
 ### The `getInt()` method
 
 The `getInt()` method retrieves the value of a specified field as a integer from a data block. If the field does not exist or is null, it returns a default value, which can be customized (null by default).

src/Traits/TypeableBlock.php

@@ -7,7 +7,7 @@
 trait TypeableBlock
 {
     /**
-     * Return a forced string value from the get() method
+     * Return a string value from the get() method
      * @param int|string $key the field 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
@@ -16,8 +16,42 @@ public function getString(
         int|string $key,
         ?string $defaultValue = null,
         string $charNestedKey = ".",
+    ): ?string {
+        $returnValue = $this->get($key, $defaultValue, $charNestedKey);
+        if ($returnValue === null) {
+            return $defaultValue;
+        }
+
+        if (is_scalar($returnValue)) {
+            return strval($returnValue);
+        }
+
+        return $defaultValue;
+
+    }
+
+    /**
+     * Return a forced string value from the get() method
+     * @param int|string $key the field key , can be nested for example "commits.0.name"
+     * @param string $defaultValue the default value returned if no value is found, by default is ""
+     * @param non-empty-string $charNestedKey for nested field the . character is the default
+     */
+    public function getStringStrict(
+        int|string $key,
+        string $defaultValue = "",
+        string $charNestedKey = ".",
     ): string {
-        return (string) $this->get($key, $defaultValue, $charNestedKey);
+        $returnValue = $this->get($key, $defaultValue, $charNestedKey);
+        if ($returnValue === null) {
+            return $defaultValue;
+        }
+
+        if (is_scalar($returnValue)) {
+            return strval($returnValue);
+        }
+
+        return $defaultValue;
+
     }
 
     /**

tests/Unit/Traits/TypeableBlockTest.php

@@ -12,15 +12,32 @@ function (): void {
         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.author.notexist"))->toBeNull();
+        expect($data1->getString("0.commit.author.notexist", "AA"))->toBeString()->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");
     },
 );
 
+test(
+    'Testing getStringStrict()',
+    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->getStringStrict("0.commit.author.date"))->toBeString();
+        expect($data1->getStringStrict("0.commit.author.notexist"))->toBeString()->toBe("");
+        expect($data1->getStringStrict("0.commit.author.notexist", "AA"))->toBeString()->toEqual("AA");
+        expect($data1->getStringStrict("0.commit.comment_count"))->toBeString()->toEqual("0");
+        expect($data1->getStringStrict("0.commit.comment_count", 1))->toBeString()->toEqual("0");
+        expect($data1->getStringStrict("0.commit.comment_countnotexists", 1))->toBeString()->toEqual("1");
+    },
+);
+
 test(
     'Testing getInt()',
     function (): void {