Merge pull request #42 from Hi-Folks/feat/typeable

Adding getInt() method

Author: roberto-butti

CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## 1.0.1 - WIP
+- Adding getInt() method for returing casted integer value
+
 ## 1.0.0 - 2025-06-13
 - Upgrade dev package PestPHP 3
 - Upgrade dev package PHPstan 2

README.md

@@ -276,6 +276,23 @@ $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 `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).
+Parameters:
+
+- `$path` (string): The path to the field (e.g., "0.author.id").
+- `$default` (null|int): (Optional) The default value to return if the field doesn't exist. Defaults to null.
+- `$charNestedKey` (string): the character separator for nested field names.  The default is ".".
+
+Example usage:
+```php
+$data1->getInt("0.author.id"); // Returns the field value as an integer, for example 678434
+$data1->getInt("0.author.idx"); // Returns null because the field doesn't exists
+$data1->getInt("0.author.idx", 44); // Returns 44 because the field doesn't exists, and you set a default, in this case 44
+```
+
+
 ### 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/Block.php

@@ -12,6 +12,7 @@
 use HiFolks\DataType\Traits\FormattableBlock;
 use HiFolks\DataType\Traits\IteratableBlock;
 use HiFolks\DataType\Traits\LoadableBlock;
+use HiFolks\DataType\Traits\TypeableBlock;
 use HiFolks\DataType\Traits\ValidableBlock;
 use Iterator;
 
@@ -31,6 +32,7 @@ final class Block implements Iterator, ArrayAccess, Countable
     use IteratableBlock;
     use ValidableBlock;
     use FormattableBlock;
+    use TypeableBlock;
 
 
     /** @var array<int|string, mixed> */

src/Traits/TypeableBlock.php

@@ -0,0 +1,23 @@
+<?php
+
+declare(strict_types=1);
+
+namespace HiFolks\DataType\Traits;
+
+trait TypeableBlock
+{
+    /**
+     *
+     * @param non-empty-string $charNestedKey
+     */
+    public function getInt(int|string $key, ?int $defaultValue = null, string $charNestedKey = "."): ?int
+    {
+        $returnValue = $this->get($key, null, $charNestedKey);
+
+        if (is_scalar($returnValue)) {
+            return intval($returnValue);
+        }
+
+        return $defaultValue;
+    }
+}

tests/Unit/Traits/TypeableBlockTest.php

@@ -0,0 +1,17 @@
+<?php
+
+use HiFolks\DataType\Block;
+
+test(
+    'Testing getInt()',
+    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");
+
+        expect($data1->getInt("0.author.id"))->toBeInt()->toBe(678434);
+        expect($data1->getInt("0.author.idx"))->toBeNull();
+        expect($data1->getInt("0.author.idx", 44))->toBeInt()->toBe(44);
+
+    },
+);