Download the PHP package lts/phpxq without Composer

phpxq: jq and yq in pure PHP

phpxq is a command-line equivalent of jq (JSON) and yq (YAML and friends), written in pure PHP 8.5 with no production dependencies. One executable provides both tools:

It targets jq 1.8.2 and mikefarah/yq v4.54.1. The goal is equivalence, not invention: where jq or yq defines a behaviour, phpxq matches it, and the upstream test suites are run against it to prove that.

Quick start

1. Install a release binary (no PHP needed; see Install for the other ways):

2. Query JSON with the jq language:

3. Query and edit YAML with the yq language:

If you already know jq or yq you already know phpxq: the filters, flags, exit codes and error messages are the same (differences).

Goals

• Equivalence, not invention. No new functionality, no new query language.
• Fast. A PHP CLI that starts quickly (about 70 ms for a small filter from the PHAR, about 30 ms from the static binary) and processes input as efficiently as PHP allows.
• Verified against upstream. The upstream jq and yq test suites run in CI, with every known gap listed and justified.
• No production dependencies. composer.json declares the PHP version and required extensions (ext-ctype, ext-json, ext-mbstring) and nothing else.

Install

Release binary (no PHP needed)

Releases ship static binaries for Linux (x86_64, aarch64) and, best effort, macOS, plus a PHAR and a SHA256SUMS file. The installer verifies the SHA-256 checksum before installing anything:

Options: --version X.Y.Z, --dir DIR, --links, --phar (see install.sh --help). You can also download an asset by hand and check it with sha256sum -c SHA256SUMS.

PHAR (needs PHP 8.5)

Download phpxq.phar from the releases page, make it executable and run it. It works under any name; a link named jq or yq selects that tool.

Composer

Needs PHP 8.5 with ctype, json and mbstring.

The package is on Packagist as lts/phpxq.

Composer places phpxq in its global bin directory.

From a checkout

Use as a library

The Composer package can be required by another project and called from PHP code, without spawning a process:

docs/LIBRARY.md lists the supported public classes (everything else is internal and may change), with executed examples for JSON, jq, YAML and yq, the exceptions raised, and the memory limits.

Usage

The executable dispatches on its name, busybox style. Either name the tool as the first argument or call it through a link named jq or yq:

jq

Takes the same filters, options, exit codes and error messages as jq 1.8.2:

yq

Follows mikefarah/yq v4 (eval is the default command, eval-all loads every document first):

Formats: YAML, JSON, XML, CSV, TSV, properties, TOML, HCL, INI, Lua, base64 and URI, plus shell and KYAML as output formats (as in yq 4.54.1; yq --help lists the flags).

Common tasks

Everything reads standard input when no file is given, so it works in pipelines (kubectl get pods -o json | phpxq jq -r '.items[].metadata.name').

Version

Differences from upstream and known gaps

phpxq passes every upstream test it can: jq 878 of 879 cases and yq 565 of 572 (two further yq examples, whose expected output is a Go-seeded shuffle, are skipped because ours is random), and all of the upstream shell suites. The remainder are deliberate, justified, and enforced (a gap that starts passing or an unlisted failure breaks the build):

• jq known gaps: one case, an artefact of the upstream test runner (it has no input callback), not of the CLI.
• yq known gaps: seven documentation examples. Three depend on a frozen clock, two use the system operator, which is intentionally unsupported (it spawns processes), and two are damaged upstream fixtures.

Other differences you may notice:

• phpxq --version is an addition; jq --version and yq --version print exactly what upstream prints.
• phpxq is a PHP program, so it starts slower than the native tools; see Performance.

Performance

phpxq is not a replacement for a native binary when startup time matters (a shell loop calling jq thousands of times). It is competitive on larger inputs, where startup is a rounding error.

What it costs to start. PHP itself takes 45 to 56 ms of CPU just to launch, so a trivial filter is about 70 ms from a checkout or the PHAR and about 30 ms from the static binary, against about 40 ms (jq 1.6) for the native jq.

Xdebug. It slows every PHP call, so when it is loaded with an active mode bin/phpxq re-runs itself with XDEBUG_MODE=off (this needs ext-pcntl; without it the run carries on as is). Set PHPXQ_ALLOW_XDEBUG=1 to keep it on, for example to debug phpxq itself. With Xdebug kept on, yq accepts YAML nested up to 5,000 levels instead of 10,000, because Xdebug uses far more native stack per call.

jq throughput (CPU milliseconds, lower is better; minimum of 3 runs; reference is jq 1.6, the version available on the benchmark host):

yq throughput (CPU milliseconds; minimum of 3 runs; production-like build):

On medium YAML files a wall-clock comparison against mikefarah yq v4.54.1 on the same (busy) host put phpxq between 0.64x and 0.96x of its time; startup and many-small-files workloads are 2 to 5x slower.

How to read these numbers: they come from a shared, loaded machine, so only CPU time (user plus system, minimum of several runs) is reported, and differences under about 5 percent are noise. "Medium" is about 640 KB and "large" is tens of MB of generated data. Absolute numbers depend on your hardware; run the benchmark suite below to measure your own. The full results, what each optimisation bought, and the ones that were tried and rejected are in CLAUDE/Plan/Completed/00007-performance-optimisation-round (results.md, results-yq.md, results-binary.md, hot-spots.md).

Development

The project is developed in a CCY container; the PHP 8.5 environment is defined in .claude/ccy/Dockerfile.

The project has no production dependencies, so php-qa-ci's Safe-function Rector lane and its thecodingmachine/safe require-checker scan files are overridden in qaConfig/, and the #[\SensitiveParameter] check is disabled in qaConfig/qa.php.

Conformance

scripts/conformance.bash [jq|yq|all] runs the vendored upstream suites (the jq .test files, the jq shtest shell driver, the yq documentation examples and acceptance scripts) and checks the results against tests/Conformance/<Tool>/known-gaps.txt. It prints CONFORMANCE: OK on success and exits non-zero on an unexpected failure or on a known gap that now passes. The same suites are available as PHPUnit suites (--testsuite jq, --testsuite yq), and PHPXQ_BINARY=dist/phpxq-linux-x86_64 scripts/conformance-shell.bash all runs the shell suites against a built binary.

Vendored fixtures keep their own licences: see tests/Conformance/Jq/fixtures/NOTICE.md and COPYING (jq, MIT), and tests/Conformance/Yq/fixtures/NOTICE.md and LICENSE (yq, MIT). scripts/refresh-upstream-fixtures.bash re-fetches them from the pinned upstream tags.

Benchmarks

scripts/bench/bench.bash measures startup time and throughput (small and medium JSON and YAML by default, large with --sizes; representative filters) for phpxq and, when installed, the real jq and mikefarah yq.

Inputs are generated deterministically and never committed. Results record the PHP, OPcache/JIT, CPU and kernel configuration; only compare results taken on the same machine. Methodology: CLAUDE/Plan/Completed/00005-benchmarking-suite/BENCHMARKS.md.

Defence Before Fix

Bugs found in this project are handled with the Defence Before Fix method: a defect is attributed to its class, a static-analysis rule that catches the whole class is built and proven to fire, every other instance is found and fixed, and only then is the original bug fixed with a regression test. The rules, what each one catches and how to run it are in docs/defence-before-fix.md (vendor/bin/rules lists every active defence, vendor/bin/phpstan-rule <identifier> <path> proves one on one path).

Claude Code hooks

This repository uses the Claude Code Hooks Daemon for deterministic guardrails on agent tool calls; configuration lives in .claude/hooks-daemon.yaml.

Releasing

Releases are cut from the changelog; nobody picks a version or tags by hand. Record every user-visible change under ## Unreleased in CHANGELOG.md (QA enforces it); the headings choose the next SemVer version. When main is green and has unreleased entries, a bot opens a release pull request into the release branch. Merging it runs the release workflow: full QA and conformance, the PHAR and static binaries, smoke tests, the tag vX.Y.Z and the GitHub Release. A back-merge pull request then brings VERSION and the changelog on main in line. The flow, the version rules and the one-off GitHub settings are in docs/RELEASING.md.

Sponsor

phpxq's development, including the AI tokens used to build it, is paid for by Edmonds Commerce, a digital agency that builds and maintains e-commerce platforms and bespoke web applications. Thank you.

Licence

phpxq is released under the MIT licence. Vendored upstream test fixtures are covered by their own licences, noted above.