jmespath.php: querying PHP data structures with JMESPath path expressions

JMESPath expressions in PHP: the use case and the minimum PHP requirement

JMESPath is a query language for extracting values from JSON and JSON-equivalent structures. jmespath.php brings it to PHP applications, operating on PHP arrays rather than raw JSON strings. The library requires PHP 7.2.5 or greater and installs through Composer.

The primary use case is PHP code that receives complex nested data and needs to extract specific values without writing custom traversal code. AWS SDK for PHP uses jmespath.php as a transitive dependency for filtering API responses, so any PHP project already depending on that SDK has the library available. Teams working with other nested data sources add it through Composer directly.

The README links to a JMESPath tutorial at jmespath.org/tutorial.html and to the formal grammar at jmespath.org/specification.html. Those resources cover the full expression syntax; jmespath.php does not reproduce the specification in its own README.

Which runtime to choose: AstRuntime for single runs, CompilerRuntime for repeated queries

The two runtimes differ in what they do with a parsed expression. AstRuntime, the default, parses an expression into an AST, holds the parse result in memory, and evaluates that AST on each call to the same expression. Repeated calls skip re-parsing but still walk the AST every time.

CompilerRuntime converts the AST into PHP source code and writes that file to a cache directory on disk. Subsequent calls to the same expression execute the compiled file directly. The README puts the speed gain at 7x to 60x over AstRuntime for high-reuse scenarios. That range is wide: expression complexity and how many times the same expression runs both affect the result.

The trade-off is the warm-up cost. Generating and writing the PHP file takes longer than a single AST evaluation, so the very first execution of each unique expression is slower with CompilerRuntime. Any setup that pre-compiles expressions before live traffic arrives eliminates that per-expression cost. A CLI tool or script that runs each expression once and exits gets no benefit from CompilerRuntime.

Instantiating AstRuntime directly:

$runtime = new JmesPath\AstRuntime();
$runtime('foo.bar', ['foo' => ['bar' => 'baz']]);
// > 'baz'

Installing through Composer and running the first search

The README names the Composer package as `mtdowling/jmespath.php`. The vendor name `mtdowling` differs from the GitHub organization name `jmespath`, so searching Packagist for `jmespath/jmespath.php` will not find this package.

Once Composer has installed the library and the autoloader is in place, `JmesPath\search` is the main entry point:

require 'vendor/autoload.php';

$expression = 'foo.*.baz';

$data = [
    'foo' => [
        'bar' => ['baz' => 1],
        'bam' => ['baz' => 2],
        'boo' => ['baz' => 3]
    ]
];

JmesPath\search($expression, $data);
// Returns: [1, 2, 3]

`JmesPath\search` uses AstRuntime by default. For applications requiring PSR-4 compliance, the equivalent call uses `JmesPath\Env::search($expression, $data)`. Both accept an expression string and a PHP array. The README shows both forms:

$result = JmesPath\search($expression, $data);

// or, if you require PSR-4 compliance.
$result = JmesPath\Env::search($expression, $data);

CompilerRuntime's optional cache path and what happens when it is omitted

Instantiating CompilerRuntime requires a path for the compiled PHP files:

// Note: The cache directory argument is optional.
$runtime = new JmesPath\CompilerRuntime('/path/to/compile/folder');
$runtime('foo.bar', ['foo' => ['bar' => 'baz']]);
// > 'baz'

The code comment marks the argument as optional, but the README does not document where compiled files go when no path is given. Production environments with restricted filesystem access or defined writable partitions should supply an explicit path to avoid writing to an undocumented location.

For server-side applications, pre-compiling expressions before deployment is achievable by instantiating CompilerRuntime and calling each expression once in a setup step. After that warm-up, compiled files exist on disk before any live request arrives, and the per-expression cost does not appear in production latency. The README recommends CompilerRuntime specifically for server-side use and for applications that can pre-compile before accepting traffic.

JP_PHP_COMPILE activates CompilerRuntime without modifying PHP code

Setting the `JP_PHP_COMPILE` environment variable to "on" activates CompilerRuntime inside `JmesPath\search()`. Setting it to a directory path activates CompilerRuntime and directs compiled files to that path.

That separation means the runtime choice stays outside the application source code. A development environment runs without the variable, defaulting to AstRuntime and its PHP 7.2.5-compatible behavior. A production environment sets `JP_PHP_COMPILE` to a known writable path. Teams relying on the "on" value should verify which directory the library writes to, since the README does not document that fallback location.

Security issues follow the process in SECURITY.md at the repository root, linked from the README to github.com/jmespath/jmespath.php/security/policy.

Compliance tests at tests/compliance and cross-implementation consistency

A compliance test suite lives at `tests/compliance` in the repository. The README describes these tests as ensuring consistency with other JMESPath implementations, so jmespath.php is verified against the same expected outputs as the Python library at github.com/jmespath/jmespath.py. Both libraries implement the same specification, so the same expression must produce the same result regardless of which implementation runs it.

The tests run through PHPUnit. Two Makefile targets are available:

make test

That runs the full test suite after Composer-installed dependencies are present. A separate performance test also uses the Makefile:

make perf

The `make perf` target runs `bin/perf.php` with the PHP binary.

The compliance test files at `tests/compliance` also serve as working examples of JMESPath expressions. For teams unfamiliar with the syntax, reading those fixtures gives a concrete picture of what each expression returns on a given input, covering edge cases the README does not address in prose.

No streaming and null on missing keys: where jmespath.php ends

jmespath.php holds the entire PHP data structure in memory before any query runs. There is no streaming mode. For large JSON files, the PHP application must fully decode the document before passing it to a query. Memory usage scales with input size, not query scope.

When an expression references a missing key, jmespath.php returns null rather than raising an exception. That is JMESPath specification behavior. Applications distinguishing between an absent optional field and a missing required field must add that check outside the query. Schema validation is also outside the library's scope.

Version 2.9.2 was released on 2026-07-06, and the repository is not archived. The Python library at github.com/jmespath/jmespath.py is the reference implementation for teams working outside PHP; the two share a specification and a compliance test suite but are maintained separately.

Editorial conclusion

jmespath.php is a good fit for PHP applications that query deeply nested arrays or JSON-decoded responses and need a tested, specification-compliant JMESPath implementation. AstRuntime handles low-reuse queries without configuration; switch to CompilerRuntime when the same expressions run repeatedly in a long-lived process. Setting JP_PHP_COMPILE to a writable directory is the configuration step to take before deploying to production. Before adopting, verify the PHP version meets the 7.2.5 floor and confirm the Composer package is mtdowling/jmespath.php, not jmespath/jmespath.php.

Frequently asked questions

Official sources

1. Issues
2. jmespath/jmespath.php on GitHub
3. License: MIT
4. README
5. Releases