- Aligned the query runner and lexer with the JSONPath comparison suite: JSON documents are now decoded as objects to preserve {} vs [], unsupported selectors no longer abort the runner, and dot-notation now accepts quoted keys with dots/spaces/leading @.

SoftCreatR · SoftCreatR · commit 23d04a306a46 · 2026-01-15T01:02:45.000+01:00
- Hardened filter parsing: boolean-only filters (`?(true|false|null)`), literal short-circuiting (`&amp;&amp; false`, `|| true`), and empty filters now return the expected collections instead of throwing.
- Slice filters gracefully skip non-countable objects.

Signed-off-by: Sascha Greuel &lt;github@1-2.dev&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,10 @@
 # Changelog
 
+### 1.0.1
+- Aligned the query runner and lexer with the JSONPath comparison suite: JSON documents are now decoded as objects to preserve `{}` vs `[]`, unsupported selectors no longer abort the runner, and dot-notation now accepts quoted keys with dots/spaces/leading `@`.
+- Hardened filter parsing: boolean-only filters (`?(true|false|null)`), literal short-circuiting (`&& false`, `|| true`), and empty filters now return the expected collections instead of throwing.
+- Slice filters gracefully skip non-countable objects.
+
 ### 1.0.0
 - Rebuilt the test suite from scratch: removed bulky baseline fixtures and added compact unit/integration coverage for every filter (index, union, query, recursive, slice), lexer edge cases, and JSONPath core helpers. Runs reflection-free and deprecation-free.
 - Achieved and enforced 100% code coverage across AccessHelper, all filters, lexer, tokens, and JSONPath core while keeping phpstan and coding standards clean.
diff --git a/README.md b/README.md
@@ -11,7 +11,7 @@ This is a [JSONPath](http://goessner.net/articles/JsonPath/) implementation for
 - PHP 8.5+ only, with enums/readonly tokens and no `eval`.
 - Works with arrays, objects, and `ArrayAccess`/traversables in any combination.
 - Unions cover slices/queries/wildcards/multi-key strings (quoted or unquoted); negative indexes and escaped bracket notation are supported.
-- Filters support path-to-path/root comparisons, regex, `in`/`nin`/`!in`, deep equality, and RFC-style null existence/value handling.
+- Filters support path-to-path/root comparisons, regex, `in`/`nin`/`!in`, deep equality, RFC-style null existence/value handling, and literal-only short-circuiting (e.g., `?(true)`, `?(false)`, `&& false`, `|| true`).
 - Tokenized parsing with internal caching; lightweight manual runner to try bundled examples quickly.
 
 ## Installation
@@ -65,7 +65,7 @@ Symbol                | Description
 `*`                   | Wildcard. All child elements regardless their index.
 `[,]`                 | Array indices as a set
 `[start:end:step]`    | Array slice operator borrowed from ES4/Python.
-`?()`                 | Filters a result set by a comparison expression
+`?()`                 | Filters a result set by a comparison expression (constant expressions like `?(true)`/`?(false)` are allowed; unsupported/empty filters evaluate to an empty result)
 `()`                  | Uses the result of a comparison expression as the index
 
 ## PHP Usage
diff --git a/composer.json b/composer.json
@@ -2,7 +2,7 @@
   "name": "softcreatr/jsonpath",
   "description": "JSONPath implementation for parsing, searching and flattening arrays",
   "license": "MIT",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "authors": [
     {
       "name": "Stephen Frank",
diff --git a/src/Filters/QueryMatchFilter.php b/src/Filters/QueryMatchFilter.php
@@ -58,6 +58,18 @@ public function filter(array|object $collection): array
             $filterExpression = $negationMatches['logicalexpr'];
         }
 
+        $literalResult = $this->evaluateLiteralExpression($filterExpression, $collection);
+
+        if ($literalResult !== null) {
+            return $literalResult;
+        }
+
+        $shortCircuitResult = $this->evaluateExpressionWithTrailingLiteral($filterExpression, $collection);
+
+        if ($shortCircuitResult !== null) {
+            return $shortCircuitResult;
+        }
+
         $filterGroups = [];
 
         if (
@@ -315,6 +327,60 @@ private function evaluateConstantExpression(string $expression): ?bool
         };
     }
 
+    /**
+     * @param array<int, mixed>|object $collection
+     * @return array<int, mixed>|null
+     * @throws JSONPathException
+     */
+    private function evaluateLiteralExpression(string $expression, array|object $collection): ?array
+    {
+        $trimmed = \trim($expression);
+
+        if ($trimmed === '') {
+            return [];
+        }
+
+        $literalValue = $this->decodeLiteral($trimmed);
+        $literalIsBool = \is_bool($literalValue);
+
+        if (!$literalIsBool && $literalValue !== null) {
+            return null;
+        }
+
+        return $this->isTruthy($literalValue) ? AccessHelper::arrayValues($collection) : [];
+    }
+
+    /**
+     * @param array<int, mixed>|object $collection
+     * @return array<int, mixed>|null
+     * @throws JSONPathException
+     */
+    private function evaluateExpressionWithTrailingLiteral(
+        string $expression,
+        array|object $collection
+    ): ?array {
+        if (
+            !\preg_match(
+                '/^(?<left>.+?)\s*(?<op>&&|\|\|)\s*(?<literal>true|false|null)\s*$/i',
+                $expression,
+                $matches
+            )
+        ) {
+            return null;
+        }
+
+        $leftFilter = '$[?(' . $matches['left'] . ')]';
+        $leftResult = new JSONPath($collection)->find($leftFilter)->getData();
+        $literalValue = $this->decodeLiteral($matches['literal']);
+        $literalIsTrue = $this->isTruthy($literalValue);
+
+        return match ($matches['op']) {
+            '&&' => $literalIsTrue ? $leftResult : [],
+            '||' => $literalIsTrue ? AccessHelper::arrayValues($collection) : $leftResult,
+            default => [],
+        };
+    }
+
     private function decodeLiteral(string $literal): mixed
     {
         $literal = \trim($literal);
diff --git a/src/Filters/SliceFilter.php b/src/Filters/SliceFilter.php
@@ -19,6 +19,14 @@ class SliceFilter extends AbstractFilter
      */
     public function filter(array|object $collection): array
     {
+        if (
+            !\is_array($collection)
+            && !$collection instanceof \Countable
+            && !$collection instanceof \ArrayAccess
+        ) {
+            return [];
+        }
+
         $length = \count($collection);
         $start = $this->token->value['start'];
         $end = $this->token->value['end'];
diff --git a/src/JSONPathLexer.php b/src/JSONPathLexer.php
@@ -54,7 +54,7 @@ public function __construct(string $expression)
             return;
         }
 
-        if ($expression[0] === '$') {
+        if ($expression[0] === '$' || $expression[0] === '@') {
             $expression = \substr($expression, 1);
         }
 
@@ -83,11 +83,17 @@ public function parseExpressionTokens(): array
         $tokenValue = '';
         $tokens = [];
         $inBracketQuote = null;
+        $inQuote = null;
 
         for ($i = 0; $i < $this->expressionLength; $i++) {
             $char = $this->expression[$i];
 
-            if (($squareBracketDepth === 0) && $char === '.') {
+            if ($squareBracketDepth === 0 && ($char === "'" || $char === '"')) {
+                $escaped = $this->isEscaped($tokenValue);
+                $inQuote = $inQuote === $char && !$escaped ? null : ($inQuote ?? $char);
+            }
+
+            if (($squareBracketDepth === 0) && $inQuote === null && $char === '.') {
                 if ($this->lookAhead($i) === '.') {
                     $tokens[] = new JSONPathToken(TokenType::Recursive, null);
                 }
@@ -140,7 +146,10 @@ public function parseExpressionTokens(): array
              */
             $tokenValue .= $char;
 
-            if ($this->atEnd($i) || \in_array($this->lookAhead($i), ['.', '['], true)) {
+            if (
+                $inQuote === null
+                && ($this->atEnd($i) || \in_array($this->lookAhead($i), ['.', '['], true))
+            ) {
                 $tokens[] = $this->createToken($tokenValue);
                 $tokenValue = '';
             }
@@ -179,7 +188,7 @@ protected function createToken(string $value): JSONPathToken
     {
         // The IDE doesn't like, what we do with $value, so let's
         // move it to a separate variable, to get rid of any IDE warnings
-        $tokenValue = $value;
+        $tokenValue = \trim($value);
 
         /** @var JSONPathToken|null $ret */
         $ret = null;
@@ -197,6 +206,15 @@ protected function createToken(string $value): JSONPathToken
                 $hasQuery = false;
 
                 foreach ($parts as $part) {
+                    if (
+                        \preg_match('/^' . static::MATCH_INDEX_IN_SINGLE_QUOTES . '$/xu', $part, $matches)
+                        || \preg_match('/^' . static::MATCH_INDEX_IN_DOUBLE_QUOTES . '$/xu', $part, $matches)
+                    ) {
+                        $union[] = $this->decodeQuotedIndex($matches[1] ?? '', $matches[0][0]);
+
+                        continue;
+                    }
+
                     if (\preg_match('/^-\\d+$/', $part)) {
                         $union[] = (int)$part;
 
@@ -228,8 +246,21 @@ protected function createToken(string $value): JSONPathToken
                     }
                 }
 
-                if (($hasSlice || $hasQuery) && \count($union) === \count($parts)) {
-                    return new JSONPathToken(TokenType::Indexes, $union);
+                if (\count($union) === \count($parts)) {
+                    $quotedPattern = '/^(' . static::MATCH_INDEX_IN_SINGLE_QUOTES . '|'
+                        . static::MATCH_INDEX_IN_DOUBLE_QUOTES . ')$/xu';
+
+                    $quotedCallback = static function (string $part) use ($quotedPattern): bool {
+                        return \preg_match($quotedPattern, $part) === 1;
+                    };
+
+                    $quotedParts = \array_filter($parts, $quotedCallback);
+
+                    $allQuoted = \count($quotedParts) === \count($parts);
+
+                    $tokenType = ($hasSlice || $hasQuery || !$allQuoted) ? TokenType::Indexes : TokenType::Index;
+
+                    return new JSONPathToken($tokenType, $union, $allQuoted);
                 }
             }
         }
@@ -238,21 +269,25 @@ protected function createToken(string $value): JSONPathToken
             return new JSONPathToken(TokenType::Index, (int)$tokenValue);
         }
 
+        if ($tokenValue === '') {
+            return new JSONPathToken(TokenType::Indexes, []);
+        }
+
+        if (
+            ($tokenValue[0] === "'" || $tokenValue[0] === '"')
+            && $tokenValue[\strlen($tokenValue) - 1] === $tokenValue[0]
+        ) {
+            $tokenValue = $this->decodeQuotedIndex(\substr($tokenValue, 1, -1), $tokenValue[0]);
+
+            return new JSONPathToken(TokenType::Index, $tokenValue, true);
+        }
+
         if (\preg_match('/^(' . static::MATCH_INDEX . ')$/xu', $tokenValue, $matches)) {
             if (\preg_match('/^-?\d+$/', $tokenValue)) {
                 $tokenValue = (int)$tokenValue;
             }
 
             $ret = new JSONPathToken(TokenType::Index, $tokenValue);
-        } elseif (\preg_match('/^' . static::MATCH_INDEXES . '$/xu', $tokenValue, $matches)) {
-            $tokenValue = \explode(',', \trim($tokenValue, ','));
-
-            foreach ($tokenValue as $i => $v) {
-                $v = \trim($v);
-                $tokenValue[$i] = $v === '*' ? '*' : (int)$v;
-            }
-
-            $ret = new JSONPathToken(TokenType::Indexes, $tokenValue);
         } elseif (\preg_match('/^' . static::MATCH_SLICE . '$/xu', $tokenValue, $matches)) {
             $tokenValue = $this->parseSlice($tokenValue);
 
@@ -261,6 +296,8 @@ protected function createToken(string $value): JSONPathToken
             $tokenValue = \substr($tokenValue, 1, -1);
 
             $ret = new JSONPathToken(TokenType::QueryResult, $tokenValue);
+        } elseif ($tokenValue === '?()') {
+            $ret = new JSONPathToken(TokenType::QueryMatch, '', shorthand: false);
         } elseif ($tokenValue === '?') {
             $ret = new JSONPathToken(TokenType::QueryMatch, '@', shorthand: true);
         } elseif (\preg_match('/^\\?@/', $tokenValue)) {
@@ -272,27 +309,6 @@ protected function createToken(string $value): JSONPathToken
             $tokenValue = \substr($tokenValue, 2, -1);
 
             $ret = new JSONPathToken(TokenType::QueryMatch, $tokenValue);
-        } elseif (
-            \preg_match('/^' . static::MATCH_INDEX_IN_SINGLE_QUOTES . '$/xu', $tokenValue, $matches)
-            || \preg_match('/^' . static::MATCH_INDEX_IN_DOUBLE_QUOTES . '$/xu', $tokenValue, $matches)
-        ) {
-            if (isset($matches[1])) {
-                $tokenValue = $this->decodeQuotedIndex($matches[1], $matches[0][0]);
-
-                $possibleArray = false;
-                if ($matches[0][0] === '"') {
-                    $possibleArray = \explode('","', $tokenValue);
-                } elseif ($matches[0][0] === "'") {
-                    $possibleArray = \explode("','", $tokenValue);
-                }
-                if ($possibleArray !== false && \count($possibleArray) > 1) {
-                    $tokenValue = $possibleArray;
-                }
-            } else {
-                $tokenValue = '';
-            }
-
-            $ret = new JSONPathToken(TokenType::Index, $tokenValue, true);
         }
 
         if ($ret !== null) {
diff --git a/tests/JSONPathLexerTest.php b/tests/JSONPathLexerTest.php
@@ -198,6 +198,27 @@ public static function expressionProvider(): iterable
             ],
         ];
 
+        yield 'quoted index in dot notation preserves dots' => [
+            "$.'some.key'",
+            [
+                ['type' => TokenType::Index, 'value' => 'some.key', 'quoted' => true],
+            ],
+        ];
+
+        yield 'empty bracket notation yields empty index list' => [
+            '$[]',
+            [
+                ['type' => TokenType::Indexes, 'value' => []],
+            ],
+        ];
+
+        yield 'empty filter expression tokenizes to empty query match' => [
+            '$[?()]',
+            [
+                ['type' => TokenType::QueryMatch, 'value' => '', 'shorthand' => false],
+            ],
+        ];
+
         yield 'query result expression' => [
             '[(@.foo + 2)]',
             [
diff --git a/tests/QueryMatchFilterTest.php b/tests/QueryMatchFilterTest.php
@@ -243,6 +243,45 @@ public function testMalformedFilterThrowsRuntimeException(): void
         new JSONPath([1])->find('$[?(foo)]');
     }
 
+    /**
+     * @throws JSONPathException
+     */
+    public function testLiteralOnlyFilterExpressionsReturnWholeCollectionOrEmpty(): void
+    {
+        $data = [1, 2, 3];
+
+        self::assertSame($data, new JSONPath($data)->find('$[?(true)]')->getData());
+        self::assertSame([], new JSONPath($data)->find('$[?(false)]')->getData());
+    }
+
+    /**
+     * @throws JSONPathException
+     */
+    public function testLogicalExpressionsWithLiteralRightOperand(): void
+    {
+        $data = [
+            ['key' => 1],
+            ['key' => -1],
+        ];
+
+        self::assertSame(
+            [],
+            new JSONPath($data)->find('$[?(@.key>0 && false)]')->getData()
+        );
+        self::assertSame(
+            $data,
+            new JSONPath($data)->find('$[?(@.key>0 || true)]')->getData()
+        );
+    }
+
+    /**
+     * @throws JSONPathException
+     */
+    public function testEmptyFilterExpressionReturnsEmpty(): void
+    {
+        self::assertSame([], new JSONPath([1, 2])->find('$[?()]')->getData());
+    }
+
     /**
      * @throws JSONPathException
      */
diff --git a/tests/SliceFilterTest.php b/tests/SliceFilterTest.php
@@ -36,7 +36,7 @@ public function testFilterHandlesNegativeAndNullBounds(array $slice, array|objec
     }
 
     /**
-     * @return iterable<string, array{array<string, int|null>, array<array-key, mixed>, array<int, mixed>}>
+     * @return iterable<string, array{array<string, int|null>, array<array-key, mixed>|object, array<int, mixed>}>
      */
     public static function edgeCaseProvider(): iterable
     {
@@ -97,6 +97,12 @@ public static function edgeCaseProvider(): iterable
             ['a', 'b', 'c'],
             ['b', 'a'],
         ];
+
+        yield 'non countable object yields empty' => [
+            ['start' => 0, 'end' => null, 'step' => 1],
+            (object)['a' => 1],
+            [],
+        ];
     }
 
     /**
@@ -105,7 +111,7 @@ public static function edgeCaseProvider(): iterable
      * @param array<int, mixed> $expected
      */
     #[DataProvider('edgeCaseProvider')]
-    public function testEdgeCases(array $slice, array $input, array $expected): void
+    public function testEdgeCases(array $slice, array|object $input, array $expected): void
     {
         $token = new JSONPathToken(TokenType::Slice, $slice);
         $filter = new SliceFilter($token);

Original file line number	Diff line number	Diff line change
`@@ -2,7 +2,7 @@`
`2`	`2`	`"name": "softcreatr/jsonpath",`
`3`	`3`	`"description": "JSONPath implementation for parsing, searching and flattening arrays",`
`4`	`4`	`"license": "MIT",`
`5`		`- "version": "1.0.0",`
	`5`	`+ "version": "1.0.1",`
`6`	`6`	`"authors": [`
`7`	`7`	`{`
`8`	`8`	`"name": "Stephen Frank",`