PHPackages                             iliaal/php\_clickhouse - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Database & ORM](/categories/database)
4. /
5. iliaal/php\_clickhouse

ActivePhp-ext[Database & ORM](/categories/database)

iliaal/php\_clickhouse
======================

Native PHP extension for ClickHouse using the official ClickHouse/clickhouse-cpp client. Connects over the native TCP protocol with LZ4 / ZSTD compression and optional TLS.

0.8.5(4w ago)108↓50%2PHP-3.01CPHP >=7.4CI passing

Since Apr 25Pushed 5d ago1 watchersCompare

[ Source](https://github.com/iliaal/php_clickhouse)[ Packagist](https://packagist.org/packages/iliaal/php_clickhouse)[ Docs](https://github.com/iliaal/php_clickhouse)[ RSS](/packages/iliaal-php-clickhouse/feed)WikiDiscussions master Synced 1w ago

READMEChangelog (6)DependenciesVersions (7)Used By (0)

php\_clickhouse
===============

[](#php_clickhouse)

[![Tests](https://github.com/iliaal/php_clickhouse/actions/workflows/tests.yml/badge.svg)](https://github.com/iliaal/php_clickhouse/actions/workflows/tests.yml)[![Version](https://camo.githubusercontent.com/b7b9e22836833f7b6c871f4d49ee7478f0f76f6aaed68f348d90af893a3f38db/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f696c6961616c2f7068705f636c69636b686f757365)](https://github.com/iliaal/php_clickhouse/releases)[![License: PHP-3.01](https://camo.githubusercontent.com/2d0c6e79d68e3ecde571be7a99c822e88c8379ff247dc40dddea7cad6872b8fb/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d5048502d2d332e30312d677265656e2e737667)](http://www.php.net/license/3_01.txt)[![Follow @iliaa](https://camo.githubusercontent.com/a54521c97521f05fbadec4bd9bcba96ff1eeaffe756a6d7338b47a628cdeb39b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f466f6c6c6f772d40696c6961612d3030303030303f7374796c653d666c6174266c6f676f3d78266c6f676f436f6c6f723d7768697465)](https://x.com/intent/follow?screen_name=iliaa)

[![php_clickhouse: native binary protocol vs HTTP](images/php_clickhouse-hero.jpg)](images/php_clickhouse-hero.jpg)

Native PHP extension for [ClickHouse](https://clickhouse.com/), built on the official [ClickHouse/clickhouse-cpp](https://github.com/ClickHouse/clickhouse-cpp) v2.6.1 client. Speaks the native binary TCP protocol with LZ4 / ZSTD compression and optional TLS, picking up where [SeasX/SeasClick](https://github.com/SeasX/SeasClick) left off in 2020. 30-40% faster than HTTP-based clients on heavy workloads, with modern types (Date32, Time64, Decimal128, LowCardinality, Map), multi-endpoint failover, and structured exceptions.

Why this fork?
--------------

[](#why-this-fork)

[SeasX/SeasClick](https://github.com/SeasX/SeasClick) was the canonical native PHP ClickHouse extension and stopped accepting PRs in 2020. Several follow-up PRs there have been pending for years. This fork:

- Renames the extension to `php_clickhouse` (module `clickhouse`, classes `ClickHouse` / `ClickHouseException`)
- Upgrades the vendored client from artpaul-fork v1.x to the official ClickHouse/clickhouse-cpp v2.6.1
- Adds Date32 / Time / Time64 / DateTime64 / Int128 / UInt128 / Decimal128 / LowCardinality / Map column types, multi-endpoint failover, ZSTD compression, query\_id propagation, and TLS
- Ships an updated test suite, CI, PIE-based packaging, and benchmarks

The original `SeasClick` and `SeasClickException` class names continue to work as deprecated aliases.

Method signatures, return types, and class properties are declared with PHP types via a stub-driven arginfo workflow (`clickhouse.stub.php` → `clickhouse_arginfo.h`). Reflection, IDE completion, and static analyzers (PHPStan, Psalm) see the typed surface without manual stubs.

🚀 Install
---------

[](#-install)

Via [PIE](https://github.com/php/pie) (the PHP Foundation's PECL successor):

```
pie install iliaal/php_clickhouse
```

With TLS support:

```
pie install iliaal/php_clickhouse --enable-clickhouse-openssl
```

> Bare `php:X.Y-cli` Docker images lack `/usr/bin/unzip`, which composer needs to extract PIE's prebuilt `.so` zip. Run `apt-get install -y unzip` before `pie install`, otherwise composer falls back to PHP's ZipArchive and PIE fails with `ExtensionBinaryNotFound`. Host installs that already have `unzip` are fine.

Building from source:

```
git clone https://github.com/iliaal/php_clickhouse.git
cd php_clickhouse
phpize
./configure                              # default build
./configure --enable-clickhouse-openssl  # with TLS, requires OpenSSL development headers
                                         #   (libssl-dev on Debian/Ubuntu, openssl-devel
                                         #    on RHEL/Fedora, openssl-dev on Alpine)
make && sudo make install
```

Add `extension=clickhouse.so` to your `php.ini`. The build needs a C++17-capable compiler (GCC 8+, Clang 7+, MSVC 2019+); LZ4, ZSTD, abseil-int128, and CityHash are vendored under `lib/clickhouse-cpp/contrib/`.

### Platforms

[](#platforms)

PlatformStatusNotesLinux NTSfirst-classPHP 7.4 through 8.5, CI matrixLinux ZTSfirst-classPHP 8.4 ZTS in CIWindows (NTS, TS)supportedPHP 8.4 x86 / x64 in CI; pre-built `.dll` released via PIEmacOSunverifiedshould build (POSIX path); no CI lanePer-Client state lives on the `zend_object` itself (custom `create_object` / `free_obj` handlers), so ZTS works without locking. There is no module-global state to thread-isolate.

### Test server

[](#test-server)

For development and integration tests, the simplest path is the official ClickHouse server image:

```
docker run -d --name clickhouse-test \
    --ulimit nofile=262144:262144 \
    -p 9000:9000 -p 8123:8123 -p 9440:9440 \
    -e CLICKHOUSE_USER=test \
    -e CLICKHOUSE_PASSWORD=test \
    clickhouse/clickhouse-server:latest
```

Stop and clean up: `docker rm -f clickhouse-test`.

🛠️ Quick example
----------------

[](#️-quick-example)

```