Added ValueNotFound object

If a value is queried it is possible that the value is null, '' or false. These
are all valid return values that the user might want to use. To distinct these
falsey values from a value that was effectifely not found, the ValueNotFound
object was introduced in this commit.

Author: tobias-kuendig

src/JsonQueriable.php

@@ -5,6 +5,7 @@
 use Nahid\JsonQ\Exceptions\ConditionNotAllowedException;
 use Nahid\JsonQ\Exceptions\FileNotFoundException;
 use Nahid\JsonQ\Exceptions\InvalidJsonException;
+use Nahid\JsonQ\Results\ValueNotFound;
 use Nahid\JsonQ\Condition;
 
 trait JsonQueriable
@@ -339,13 +340,13 @@ protected function getFromNested($map, $node)
             }
 
             if ($terminate) {
-                return false;
+                return new ValueNotFound();
             }
 
             return $map;
         }
 
-        return false;
+        return new ValueNotFound();
     }
 
     /**
@@ -383,7 +384,7 @@ protected function processConditions()
                     }
 
                     $value = $this->getFromNested($val, $rule['key']);
-                    $return = $value === null || $value !== '' ? call_user_func_array($function, [$value, $rule['value']]) : false;
+                    $return = $value instanceof ValueNotFound ? false :  call_user_func_array($function, [$value, $rule['value']]);
                     $tmp &= $return;
                 }
                 $res |= $tmp;

src/Results/ValueNotFound.php

@@ -0,0 +1,9 @@
+<?php
+
+namespace Nahid\JsonQ\Results;
+
+/**
+ * This class represents a query result where a given
+ * value was queried but did not exist.
+ */
+class ValueNotFound {}

tests/JsonQueriableTest.php

@@ -5,6 +5,7 @@
 use Nahid\JsonQ\Jsonq;
 use Nahid\JsonQ\Exceptions\FileNotFoundException;
 use Nahid\JsonQ\Exceptions\InvalidJsonException;
+use Nahid\JsonQ\Results\ValueNotFound;
 
 class JsonQueriableTest extends AbstractTestCase
 {
@@ -62,6 +63,18 @@ class JsonQueriableTest extends AbstractTestCase
             ]
         ]
     ];
+
+    protected static $testDataNesting = [
+        'level1' => [
+            'level2' => [
+                'level3-1' => 'data31',
+                'level3-2' => 32,
+                'level3-3' => false,
+                'level3-4' => null,
+                'level3-5' => '',
+            ]
+        ]
+    ];
 
     protected function createFile()
     {
@@ -193,6 +206,39 @@ public function testGetDataFromFile($file, $result)
         }
     }
 
+    /**
+     * @param mixed $path
+     * @param mixed $expected
+     *
+     * @dataProvider getFromNestedProvider
+     */
+    public function testGetFromNested($path, $expected)
+    {
+        $method = $this->makeCallable($this->jsonq, 'getFromNested');
+        
+        $input = [self::$testDataNesting, $path];
+
+        $result = $method->invokeArgs($this->jsonq, $input);
+
+        if ($result instanceof ValueNotFound) {
+            $result = ValueNotFound::class;
+        }
+
+        $this->assertEquals($expected, $result);
+    }
+    
+    public function getFromNestedProvider()
+    {
+        return [
+            ['level1.level2.level3-1', 'data31'], 
+            ['level1.level2.level3-2', 32], 
+            ['level1.level2.level3-3', false], 
+            ['level1.level2.level3-4', null], 
+            ['level1.level2.level3-5', ''], 
+            ['level1.level2.not-existing', ValueNotFound::class], 
+        ];
+    }    
+
     public function getDataFromFileProvider()
     {
         return [