[Release] 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.
- Added a lightweight manual query runner with curated examples to exercise selectors quickly without external datasets.
- Major compatibility push toward the unofficial JSONPath standard: unions support slices/queries/wildcards, trailing commas parse correctly, negative indexes and bracket-escaped keys (quotes, brackets, wildcards, special chars) are honored, filters compare path-to-path and root references, equality/deep-equality/regex/in/nin semantics align with expectations, and null existence/value handling follows RFC behavior.
- New feature highlights from this cycle:
  - Multi-key unions with and without quotes: `$[name,year]` and `$["name","year"]`.
  - Robust bracket notation for special/escaped keys, including `']'`, `'*'`, `$`, backslashes, and mixed punctuation.
  - Trailing comma support in unions/slices (e.g. `$..books[0,1,2,]`).
  - Negative index handling aligned with spec (short arrays return empty; -1 works where valid).
  - Filter improvements: path-to-path/root comparisons, deep equality across scalars/objects/arrays/null/empties, regex matching, `in`/`nin`/`!in`, tautological expressions, and `?@` existence behavior per RFC.
  - Unions combining slices/queries/wildcards now return complete results (e.g. `$[1:3,4]`, `$[*,1]`).

This fixes #72, fixes #61, fixes #60, fixes #59, fixes #58, fixes #51, fixes #44, fixes #41, fixes #40, fixes #39, fixes #38, fixes #37, fixes #36, fixes #35, fixes #34, fixes #33, fixes #32, fixes #31, fixes #30, fixes #29, fixes #9, closes #3

Signed-off-by: Sascha Greuel <[email protected]>

Author: SoftCreatR

.editorconfig

@@ -1,22 +1,35 @@
 # Changelog
 
-### 0.11.0
-🔻 Breaking changes ahead:
-
-- Dropped support for PHP < 8.5
-- `JSONPathToken` now uses a `TokenType` enum and the constructor signature changed accordingly.
-- `JSONPath` options flag is now an `int` bitmask (was `bool`), requiring callers to pass integer flags.
-- `SliceFilter` returns an empty result for non-positive step values (previously iterated indefinitely).
-- `QueryResultFilter` now throws a `JSONPathException` for unsupported operators instead of silently proceeding.
-- Access helper behavior is stricter: `arrayValues` throws on invalid types; ArrayAccess lookups check `offsetExists` before reading; traversables and objects are handled distinctly.
-- Adopted PHP 8.5 features: `TokenType` enum, readonly value object for tokens, typed flags/options, and `#[\Override]` usage.
-- CI now runs on PHP 8.5 with required extensions; code style workflow updated accordingly.
-- Added coverage for AccessHelper edge cases (magic getters, ArrayAccess, traversables, negative indexes), QueryResultFilter arithmetic branches, and SliceFilter negative/null bounds.
-- Fixed empty-expression handling in lexer and improved safety in AccessHelper traversable lookups.
-- Added PHPStan static analysis to the toolchain and addressed its findings.
-
-### 0.10.1
-- Fixed ignore whitespace after comparison value in filter expression
+### 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.
+- Added a lightweight manual query runner with curated examples to exercise selectors quickly without external datasets.
+- Major compatibility push toward the unofficial JSONPath standard: unions support slices/queries/wildcards, trailing commas parse correctly, negative indexes and bracket-escaped keys (quotes, brackets, wildcards, special chars) are honored, filters compare path-to-path and root references, equality/deep-equality/regex/in/nin semantics align with expectations, and null existence/value handling follows RFC behavior.
+- New feature highlights from this cycle:
+  - Multi-key unions with and without quotes: `$[name,year]` and `$["name","year"]`.
+  - Robust bracket notation for special/escaped keys, including `']'`, `'*'`, `$`, backslashes, and mixed punctuation.
+  - Trailing comma support in unions/slices (e.g. `$..books[0,1,2,]`).
+  - Negative index handling aligned with spec (short arrays return empty; -1 works where valid).
+  - Filter improvements: path-to-path/root comparisons, deep equality across scalars/objects/arrays/null/empties, regex matching, `in`/`nin`/`!in`, tautological expressions, and `?@` existence behavior per RFC.
+  - Unions combining slices/queries/wildcards now return complete results (e.g. `$[1:3,4]`, `$[*,1]`).
+
+### 0.11.0
+🔻 Breaking changes ahead:
+
+- Dropped support for PHP < 8.5
+- `JSONPathToken` now uses a `TokenType` enum and the constructor signature changed accordingly.
+- `JSONPath` options flag is now an `int` bitmask (was `bool`), requiring callers to pass integer flags.
+- `SliceFilter` returns an empty result for non-positive step values (previously iterated indefinitely).
+- `QueryResultFilter` now throws a `JSONPathException` for unsupported operators instead of silently proceeding.
+- Access helper behavior is stricter: `arrayValues` throws on invalid types; ArrayAccess lookups check `offsetExists` before reading; traversables and objects are handled distinctly.
+- Adopted PHP 8.5 features: `TokenType` enum, readonly value object for tokens, typed flags/options, and `#[\Override]` usage.
+- CI now runs on PHP 8.5 with required extensions; code style workflow updated accordingly.
+- Added coverage for AccessHelper edge cases (magic getters, ArrayAccess, traversables, negative indexes), QueryResultFilter arithmetic branches, and SliceFilter negative/null bounds.
+- Fixed empty-expression handling in lexer and improved safety in AccessHelper traversable lookups.
+- Added PHPStan static analysis to the toolchain and addressed its findings.
+
+### 0.10.1
+- Fixed ignore whitespace after comparison value in filter expression
 
 ### 0.10.0
 - Fixed query/selector Filter Expression With Current Object

CHANGELOG.md

@@ -4,32 +4,32 @@
 [![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE) [![Plant Tree](https://img.shields.io/badge/dynamic/json?color=brightgreen&label=Plant%20Tree&query=%24.total&url=https%3A%2F%2Fpublic.ecologi.com%2Fusers%2Fsoftcreatr%2Ftrees)](https://ecologi.com/softcreatr?r=61212ab3fc69b8eb8a2014f4)
 [![Codecov branch](https://img.shields.io/codecov/c/github/SoftCreatR/JSONPath)](https://codecov.io/gh/SoftCreatR/JSONPath)
 
-This is a [JSONPath](http://goessner.net/articles/JsonPath/) implementation for PHP based on Stefan Goessner's JSONPath script.
+This is a [JSONPath](http://goessner.net/articles/JsonPath/) implementation for PHP that targets the de facto comparison suite/RFC semantics while keeping the API small, cached, and `eval`-free.
 
-JSONPath is an XPath-like expression language for filtering, flattening and extracting data.
+## Highlights
 
-This project aims to be a clean and simple implementation with the following goals:
-
- - Object-oriented code (should be easier to manage or extend in future)
- - Expressions are parsed into tokens using code inspired by the Doctrine Lexer. The tokens are cached internally to avoid re-parsing the expressions.
- - There is no `eval()` in use
- - Any combination of objects/arrays/ArrayAccess-objects can be used as the data input which is great if you're de-serializing JSON in to objects or if you want to process your own data structures.
+- 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.
+- Tokenized parsing with internal caching; lightweight manual runner to try bundled examples quickly.
 
 ## Installation
 
 Requires PHP 8.5 or newer.
 
 ```bash
-composer require softcreatr/jsonpath:"^0.11"
+composer require softcreatr/jsonpath:"^1.0"
 ```
 
 ## Development
 
-Static analysis is done with PHPStan.
+Useful commands:
 
 ```bash
-composer require --dev phpstan/phpstan
-./vendor/bin/phpstan analyse --no-progress
+composer exec phpunit
+composer phpstan
+composer cs
 ```
 
 ## JSONPath Examples
@@ -43,6 +43,7 @@ JSONPath                  | Result
 `$..books[(@.length-1)]`  | the last book in order.
 `$..books[-1:]`           | the last book in order.
 `$..books[0,1]`           | the first two books
+`$..books[title,year]`    | multiple keys in a union
 `$..books[:2]`            | the first two books
 `$..books[::2]`           | every second book starting from first one
 `$..books[1:6:3]`         | every third book starting from 1 till 6
@@ -64,8 +65,8 @@ 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 script expression
-`()`                  | Uses the result of a script expression as the index
+`?()`                 | Filters a result set by a comparison expression
+`()`                  | Uses the result of a comparison expression as the index
 
 ## PHP Usage
 
@@ -116,8 +117,6 @@ stdClass Object
 */
 ```
 
-More examples can be found in the [Wiki](https://github.com/SoftCreatR/JSONPath/wiki/Queries)
-
 ### Magic method access
 
 The options flag `JSONPath::ALLOW_MAGIC` will instruct JSONPath when retrieving a value to first check if an object
@@ -127,40 +126,47 @@ not very predictable as:
 -  wildcard and recursive features will only look at public properties and can't smell which properties are magically accessible
 -  there is no `property_exists` check for magic methods so an object with a magic `__get()` will always return `true` when checking
    if the property exists
--   any errors thrown or unpredictable behaviour caused by fetching via `__get()` is your own problem to deal with
+-   any errors thrown or unpredictable behavior caused by fetching via `__get()` is your own problem to deal with
 
 ```php
+<?php
+
 use Flow\JSONPath\JSONPath;
 
 $myObject = (new Foo())->get('bar');
 $jsonPath = new JSONPath($myObject, JSONPath::ALLOW_MAGIC);
 ```
 
-For more examples, check the JSONPathTest.php tests file.
-
 ## Script expressions
 
-Script expressions are not supported as the original author intended because:
+Script execution is intentionally **not** supported:
 
--   This would only be achievable through `eval` (boo).
--   Using the script engine from different languages defeats the purpose of having a single expression evaluate the same way in different
-    languages which seems like a bit of a flaw if you're creating an abstract expression syntax.
+- It would require `eval`, which we avoid.
+- Behavior would diverge across languages and defeat having a portable expression syntax.
 
-So here are the types of query expressions that are supported:
+Supported filter/query patterns (200+ cases covered in the comparison suite):
 
-	[?(@._KEY_ _OPERATOR_ _VALUE_)] // <, >, <=, >=, !=, ==, =~, in and nin
-	e.g.
-	[?(@.title == "A string")] //
-	[?(@.title = "A string")]
-	// A single equals is not an assignment but the SQL-style of '=='
-	[?(@.title =~ /^a(nother)? string$/i)]
-	[?(@.title in ["A string", "Another string"])]
-	[?(@.title nin ["A string", "Another string"])]
-	
-## Known issues
-
-- This project has not implemented multiple string indexes e.g. `$[name,year]` or `$["name","year"]`. I have no ETA on that feature, and it would require some re-writing of the parser that uses a very basic regex implementation.
+```
+[?(@._KEY_ _OPERATOR_ _VALUE_)]
+  Operators: ==, =, !=, <>, !==, <, >, <=, >=, =~, in, nin, !in
+
+Examples:
+[?(@.title == "A string")]      // equality
+[?(@.title = "A string")]       // SQL-style equals
+[?(@.price < 10)]               // numeric comparisons
+[?(@.title =~ /^a(nother)?/i)]  // regex
+[?(@.title in ["A","B"])]       // membership
+[?(@.title nin ["A"])]          // not in
+[?(@.title !in ["A"])]          // alternate not in
+[?(@.key == @.other)]           // path-to-path comparison
+[?(@.key == $.rootValue)]       // root reference
+[?(@)] or [?(@==@)]             // truthy/tautology
+[?(@.length)]                   // existence checks
+[?(@['weird-key']=="ok")]       // bracket-escaped keys and negative indexes
+```
 
+A full list of (un)supported filter/query patterns can be found in the [JSONPath Comparison Cheatsheet](https://cburgmer.github.io/json-path-comparison/).
+	
 ## Similar projects
 
 [FlowCommunications/JSONPath](https://github.com/FlowCommunications/JSONPath) is the predecessor of this library by Stephen Frank

README.md

@@ -2,7 +2,7 @@
   "name": "softcreatr/jsonpath",
   "description": "JSONPath implementation for parsing, searching and flattening arrays",
   "license": "MIT",
-  "version": "0.11.0",
+  "version": "1.0.0",
   "authors": [
     {
       "name": "Stephen Frank",

composer.json

@@ -38,11 +38,14 @@ public static function keyExists(mixed $collection, int|string|null $key, bool $
             return true;
         }
 
-        if (\is_int($key) && $key < 0) {
-            $key = \abs($key);
-        }
-
         if (\is_array($collection)) {
+            if (\is_int($key) && $key < 0) {
+                $keys = \array_keys($collection);
+                $index = \count($keys) + $key;
+
+                return $index >= 0 && \array_key_exists($index, $keys);
+            }
+
             return \array_key_exists($key ?? '', $collection);
         }
 
@@ -76,7 +79,8 @@ public static function getValue(mixed $collection, int|string|null $key, bool $m
             $return = $collection->offsetExists($key) ? $collection->offsetGet($key) : null;
         } elseif (\is_array($collection)) {
             if (\is_int($key) && $key < 0) {
-                $return = \array_slice($collection, $key, 1)[0] ?? null;
+                $index = \count($collection) + $key;
+                $return = $index >= 0 && \array_key_exists($index, $collection) ? $collection[$index] : null;
             } else {
                 $return = $collection[$key] ?? null;
             }
@@ -128,7 +132,6 @@ public static function setValue(mixed &$collection, int|string|null $key, mixed
         }
 
         if ($collection instanceof ArrayAccess) {
-            /** @noinspection PhpVoidFunctionResultUsedInspection */
             $collection->offsetSet($key, $value);
 
             return $value;

src/AccessHelper.php

@@ -17,11 +17,18 @@ abstract class AbstractFilter
 {
     protected bool $magicIsAllowed;
 
+    protected mixed $rootData = null;
+
     public function __construct(protected JSONPathToken $token, int $options = 0)
     {
         $this->magicIsAllowed = ($options & JSONPath::ALLOW_MAGIC) === JSONPath::ALLOW_MAGIC;
     }
 
+    public function setRootData(mixed $root): void
+    {
+        $this->rootData = $root;
+    }
+
     /**
      * @param array<array-key, mixed>|object $collection
      * @return array<array-key, mixed>

src/Filters/AbstractFilter.php

@@ -23,6 +23,7 @@ public function filter(array|object $collection): array
     {
         if (\is_array($this->token->value)) {
             $result = [];
+
             foreach ($this->token->value as $value) {
                 if (AccessHelper::keyExists($collection, $value, $this->magicIsAllowed)) {
                     $result[] = AccessHelper::getValue($collection, $value, $this->magicIsAllowed);
@@ -38,7 +39,7 @@ public function filter(array|object $collection): array
             ];
         }
 
-        if ($this->token->value === '*') {
+        if ($this->token->value === '*' && !$this->token->quoted) {
             return AccessHelper::arrayValues($collection);
         }
 

src/Filters/IndexFilter.php

@@ -11,17 +11,55 @@
 namespace Flow\JSONPath\Filters;
 
 use Flow\JSONPath\AccessHelper;
+use Flow\JSONPath\JSONPath;
+use Flow\JSONPath\JSONPathException;
+use Flow\JSONPath\JSONPathToken;
+use Flow\JSONPath\TokenType;
 
 class IndexesFilter extends AbstractFilter
 {
     /**
      * @inheritDoc
+     *
+     * @throws JSONPathException
      */
     public function filter(array|object $collection): array
     {
         $return = [];
 
         foreach ($this->token->value as $index) {
+            if (\is_array($index) && ($index['type'] ?? null) === 'slice') {
+                $sliceToken = new JSONPathToken(TokenType::Slice, $index['value']);
+                $sliceFilter = new SliceFilter(
+                    $sliceToken,
+                    $this->magicIsAllowed ? JSONPath::ALLOW_MAGIC : 0
+                );
+                $sliceFilter->setRootData($this->rootData ?? $collection);
+
+                $return = \array_merge($return, $sliceFilter->filter($collection));
+
+                continue;
+            }
+
+            if (\is_array($index) && ($index['type'] ?? null) === 'query') {
+                $queryToken = new JSONPathToken(TokenType::QueryMatch, $index['value']);
+                $queryFilter = new QueryMatchFilter(
+                    $queryToken,
+                    $this->magicIsAllowed ? JSONPath::ALLOW_MAGIC : 0
+                );
+                $queryFilter->setRootData($this->rootData ?? $collection);
+
+                $return = \array_merge($return, $queryFilter->filter($collection));
+
+                continue;
+            }
+
+            if ($index === '*' && !$this->token->quoted) {
+                $return = \array_merge($return, AccessHelper::arrayValues($collection));
+
+                continue;
+            }
+
             if (AccessHelper::keyExists($collection, $index, $this->magicIsAllowed)) {
                 $return[] = AccessHelper::getValue($collection, $index, $this->magicIsAllowed);
             }