README

phpolars is a PHP extension that wraps Polars, the Rust data frame library. It is written in Rust with ext-php-rs and calls the Polars crates directly. The API is modeled on py-polars, Polars' Python package: the same classes and methods, with camelCase method names and snake_case functions.

use function Phpolars\{col, len, read_csv};

// Palmer penguins: https://github.com/phpstats/datasets#penguins
$penguins = read_csv(
    'https://raw.githubusercontent.com/phpstats/datasets/main/csv/penguins.csv',
    nullValues: 'NA',
);

$summary = $penguins
    ->filter(col('body_mass_g')->isNotNull())
    ->groupBy(['species', 'island'], maintainOrder: true)
    ->agg(
        len()->alias('penguins'),
        col('body_mass_g')->mean()->round()->alias('mass_g'),
    )
    ->sort('mass_g', descending: true);

print_r($summary->toDicts());

phpolars works on its own or through phibble and phplyr. phibble's Phibble\Polars\PolarsTable adapter, part of phibble, runs phibble tables and phplyr pipelines on this extension with dplyr's semantics.

Features

• DataFrame and LazyFrame with py-polars' methods, including select, withColumns, filter, sort, groupBy/agg, join, pivot, and unpivot.
• Expressions with arithmetic, three-valued logic, aggregations, window functions, when/then/otherwise, and the str, dt, list, struct, arr, cat, and name namespaces.
• Series, with the same expression methods.
• CSV, Parquet, JSON, NDJSON, and Arrow IPC reading and writing, with lazy scans and streaming sinks, and reading and writing through PDO.
• SQL queries over data frames.
• A thread-pool cap for PHP-FPM (php_polars.max_threads).

Requirements

• PHP 8.3, 8.4, or 8.5
• A non-thread-safe (NTS) PHP build
• Linux or macOS
• PIE

Prebuilt binaries cover Linux with glibc 2.34 or later on x86_64 and arm64. Other platforms, including macOS, build from source, which needs a stable Rust toolchain and libclang.

Installation

pie install phpstats/phpolars
php -r 'echo phpversion("php_polars"), PHP_EOL;'

The second command prints the installed version. Restart PHP-FPM and queue workers after installing. Deployment covers manual installs, Ubuntu and Laravel Forge, Laravel Herd, threads under PHP-FPM, and memory.

Documentation

• Getting started
• Coming from py-polars
• phibble and phplyr, including how Polars' missing values differ from dplyr's
• Functions and methods
• Compatibility and limitations
• Performance

Binary size

Polars is large. Release builds use the dist profile, which applies fat LTO, one codegen unit, and symbol stripping. Optional Cargo features gate the formats and data that not every installation needs:

All features are on by default. Build a smaller extension with, for example, cargo build --profile dist --no-default-features --features parquet.

Development

Development covers building from a checkout, the test suites, the py-polars fixtures, the docs, and the IDE stubs in stubs/phpolars.php.

License

phpolars is released under the MIT license; see LICENSE. Polars and the other Rust libraries compiled into the extension keep their own licenses, which each release archive lists in THIRD_PARTY_NOTICES.txt.