Development · phpolars

Building

git clone https://github.com/phpstats/phpolars && cd phpolars
PHP=$(which php) PHP_CONFIG=$(which php-config) cargo build --release
php -d extension=$PWD/target/release/libphp_polars.so script.php   # .dylib on macOS

The build needs a stable Rust toolchain and libclang. Set PHP and PHP_CONFIG to a PHP 8.3, 8.4, or 8.5 installation, because ext-php-rs builds against that PHP’s headers, and a build for one PHP version does not load in another. On macOS with Homebrew, also set LIBCLANG_PATH=$(brew --prefix llvm)/lib. cargo build --profile dist builds the smaller library that releases ship.

Testing

scripts/test        # build and run tests/dataframe.php, expr.php, io.php, regressions.php, and pyfixtures.php
scripts/check       # release gate: rustfmt, clippy, the suites, tests/memory.php, stub freshness, and API compatibility with the latest tag
PHIBBLE=path/to/phibble/vendor/autoload.php scripts/test   # also the phibble round-trip

CI runs scripts/check with PHP 8.3, 8.4, and 8.5 on Ubuntu 24.04 and macOS 15.

Comparing with py-polars

scripts/pyfixtures.py builds 314 cases with py-polars and writes tests/fixtures/py/expected.json. tests/pyfixtures.php builds the same cases with phpolars and compares column names, data types, and values. Regenerate the fixtures with:

uv run --with 'polars==1.43.2' --with numpy python scripts/pyfixtures.py

py-polars 1.43.2 is the release whose Rust core is closest to the pinned Polars 0.55.2.

Documentation

scripts/render-docs

This runs every docs/examples/*.php against the release build and embeds its output, regenerates the reference signatures from the extension (scripts/docs-reference.php), renders the site with Quarto, and copies it into docs/. phpolars.phpstats.org imports the rendered HTML from main:/docs, so commit it. GitHub Pages serves only redirects to phpolars.phpstats.org, from .github/workflows/pages.yml.

Stubs

stubs/phpolars.php holds signatures for IDEs and static analysis. Regenerate it after changing the API:

php -d extension=target/release/libphp_polars.so scripts/stubs.php > stubs/phpolars.php