Development

Tests

The test suite uses Pest and runs on PHP 8.3, 8.4, and 8.5. Tests that use the |> operator are in tests/Php85, which phpunit.xml loads only on PHP 8.5:

composer installphp vendor/bin/pest

CI runs the suite on Ubuntu with PHP 8.3, 8.4, and 8.5, against PostgreSQL 17 and MySQL 8.0. A second job runs tests/Polars on PHP 8.5 with a prebuilt php_polars extension, and a third runs composer lint. CI does not load the phit extension.

The tests that fit models or use the native CSV reader need the phit extension and are skipped without it. To run them, load the extension:

php -d extension=/path/to/libphit.dylib vendor/bin/pest

R comparisons

Many tests compare phibble with R. Scripts in tests/r/ run the same operations in R and write the expected results to tests/fixtures/:

The fixtures are committed, so the tests do not need R. tests/r/versions.json records the R and package versions that reproduce them byte for byte. After changing a script, regenerate its fixtures from the repository root, for example with Rscript tests/r/expr.R. The scripts need the tibble, readr, dplyr, tidyr, stringr, lubridate, and jsonlite packages.

Database tests

tests/SqlTest.php runs against an in-memory SQLite database. It also runs against PostgreSQL and MySQL when these environment variables hold PDO DSNs:

export PHIBBLE_TEST_PGSQL="pgsql:host=127.0.0.1;port=5432;dbname=postgres"export PHIBBLE_TEST_PGSQL_USER=postgresexport PHIBBLE_TEST_MYSQL="mysql:host=127.0.0.1;port=3306"export PHIBBLE_TEST_MYSQL_USER=root

PHIBBLE_TEST_PGSQL_PASSWORD and PHIBBLE_TEST_MYSQL_PASSWORD set passwords. The tests only run SELECT statements over inline data and create no tables.

Verification and benchmark records

phpstats.org renders the JSON records in site/verifications/ and site/benchmarks/. Scripts write both, and nothing is edited by hand.

bin/verify runs the test suite and writes one verification record per topic. Each case is one test, with the suite’s status and skip reason. Set the database variables above and load phit and php_polars to run every case:

bin/verify --php="php -d extension=phit.so -d extension=php_polars.so"

bin/bench-record runs the benchmarks in bench/ and writes their records. Each run is a fresh process under peakmem, built from phit’s bench/peakmem.c. Records come from the Linux benchmark machine only:

bin/bench-record --php="php -d extension=phit.so -d extension=php_polars.so"

bin/bench runs one backend in one process and prints its timings, for quick comparisons while working.

Functions and methods reference

bin/api-reference writes the pages in docs/reference/ from the public API by reflection: every function in Phibble and Phibble\Expr, and every public method of the table classes and the other public classes it lists. Text comes from the docblocks. The script fails when a public callable has no page or no docblock summary, and tests/SiteTest.php fails when the pages are out of date:

bin/api-reference

Documentation

The site is a Quarto project in docs/. Every example is a PHP file in docs/examples/. bin/docs-examples runs each example with docs/examples as the working directory and writes its code and output to docs/examples/_<name>.md, which the pages include. Quarto never runs PHP.

bin/render-docs refreshes the examples, renders the site, and copies the result into docs/. Commit the rendered HTML, because phpstats.org imports it from docs/ and never runs Quarto:

PHP=php85 bin/render-docs

bin/docs-examples name refreshes one example. Set QUARTO when the quarto command is not on the path.

The documentation is published at https://phibble.phpstats.org/docs. GitHub Pages serves only redirects there: the pages workflow runs bin/pages-redirects, which writes one redirect page for each page in docs/.