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