Development

Tests

composer test

The suite runs with Pest and covers several layers:

• Spec snapshots for every geom, feature, statistics helper, and gallery example, in tests/.pest/snapshots/. After an intended change, run vendor/bin/pest --update-snapshots and review the diff.
• Validation of every specification against the pinned Vega-Lite 6.1.0 JSON schema in tests/fixtures/.
• Numerical checks of quantiles, least squares, smoothing bands, and predictions against values from R.
• Blade component tests on Orchestra Testbench.
• When vl-convert is available, a render of every gallery example to SVG. Some specifications pass the schema but fail to compile, and this smoke test catches them.

The statistics tests build model designs with Phit\model_matrix(). They run on the phit extension when it is loaded and on phpstats/phit-polyfill, a development dependency, when it is not. The saved fits in tests/fixtures/fits.json let them check results against R.

CI runs the suite on PHP 8.3, 8.4, and 8.5. The tests in tests/Pipes/ use the pipe operator, so phpunit.xml runs them only on PHP 8.5. Code in src/ must parse on PHP 8.3.

Gallery

php examples/gallery.php [output.html] [--svg=dir]

The gallery writes an HTML page of every example in examples/catalog.php, with each example’s code. The catalog is a plain PHP array, so other projects can reuse it.

Documentation

The documentation is a Quarto website in docs/. The pages include generated fragments for their examples:

1. Each file in docs/examples/ returns a chart. An example that uses the pipe operator has a method-chain twin, {name}.chain.php, and the page shows the two in tabs labeled “PHP 8.5+” and “PHP 8.3–8.4”.
2. php scripts/docs-examples.php runs every example and checks that each twin builds the same specification. For each example it writes the code and the specification to docs/_generated/, and an SVG to docs/figures/ when vl-convert is found. It also writes the gallery fragment from examples/catalog.php.
3. php scripts/docs-reference.php writes the API reference fragments from the signatures and docblocks in src/.
4. quarto render docs builds the site into docs/_site/.
5. scripts/render-docs runs steps 2 to 4, then copies the site into docs/.

phpstats.org imports the committed HTML in docs/ and publishes it at https://phiz.phpstats.org/docs, so commit the rendered pages with their sources. GitHub Pages serves the gh-pages branch, which holds only redirects from the old phpstats.github.io/phiz/ addresses to the same pages on phpstats.org. The pipe examples need PHP 8.5, and the SVGs need vl-convert 1.9.0, the version the committed figures were made with:

PHP=php8.5 PHIZ_VL_CONVERT=/path/to/vl-convert scripts/render-docs

A render rewrites every lastmod in docs/sitemap.xml from the file times on the rendering machine. Keep the committed dates, and change the date only for pages whose content changed.

Some statistics examples build designs from model formulas with Phit\model_matrix(). phit-polyfill provides it when the phit extension is not loaded, so the documentation build needs no extension.

Design notes and plans that are not user documentation live in notes/.