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

> jmespath.php is a PHP implementation of the JMESPath query language that extracts elements from nested PHP arrays using declarative path expressions. It provides two runtimes with different performance profiles: AstRuntime for general use and CompilerRuntime that emits and caches PHP source code.

**jmespath/jmespath.php** — Declaratively specify how to extract elements from a JSON document, in PHP

- Repository: https://github.com/jmespath/jmespath.php
- Stars: 2,011 · Forks: 57
- Language: PHP
- License: MIT
- Published: 2026-10-11 · Updated: 2026-10-11 · Language: en
- Canonical page: https://hysenlabs.com/projects/jmespath-jmespath-php

## 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:

```php
$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:

```php
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:

```php
$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:

```php
// 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:

```bash
make test
```

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

```bash
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.

## 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.

## FAQ

### What is jmespath.php?

jmespath.php is a PHP implementation of the JMESPath query language. It lets PHP applications extract values from nested arrays and objects using declarative path expressions and requires PHP 7.2.5 or greater.

### How do I install jmespath.php?

The README directs users to Composer and names the 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 return this package.

### What is the difference between AstRuntime and CompilerRuntime in jmespath.php?

AstRuntime parses each expression, caches the AST in memory, and evaluates it on each call. CompilerRuntime generates PHP source code from the AST and caches that file on disk, giving 7x to 60x better performance for expressions that are reused, but with a warm-up cost on the first execution of each unique expression.

### What PHP version does jmespath.php require?

jmespath.php requires PHP 7.2.5 or greater, as stated in the README.

### How do I enable CompilerRuntime in jmespath.php without changing PHP code?

Set the JP_PHP_COMPILE environment variable to "on" or to a directory path. When set to a directory path, JmesPath\search uses CompilerRuntime and writes compiled files to that directory.

## Sources

- [Issues](https://github.com/jmespath/jmespath.php/issues)
- [jmespath/jmespath.php on GitHub](https://github.com/jmespath/jmespath.php)
- [License: MIT](https://github.com/jmespath/jmespath.php/blob/master/LICENSE)
- [README](https://github.com/jmespath/jmespath.php/blob/master/README.md)
- [Releases](https://github.com/jmespath/jmespath.php/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jmespath-jmespath-php