PHPackages                             borislav/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. borislav/clickhouse

ActiveLibrary[Database & ORM](/categories/database)

borislav/clickhouse
===================

ClickHouse implementation for PHP projects

1.0.0(3y ago)14MITPHP

Since Oct 10Pushed 3y ago1 watchersCompare

[ Source](https://github.com/Borislavv/clickhouse)[ Packagist](https://packagist.org/packages/borislav/clickhouse)[ RSS](/packages/borislav-clickhouse/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)Dependencies (3)Versions (2)Used By (0)

ClickHouse
==========

[](#clickhouse)

1. **Сущность/Entity**

    1. Каждая сущность = отдельная таблица
    2. Название сущности = inTheLowerCase(название таблицы)
    3. Название свойств сущности = название столбцов
    4. Каждая сущность, которая работает через ClickHouse, должна имплементировать интерфейс [ClickHouseEntityInterface](./src/Entity/Interfaces/ClickHouseEntityInterface.php) (*необходимо для нормализации и денормализации*).
2. **Репозиторий/Repository**

    1. Каждый репозиторий должен наследоваться от [ClickHouseRepository](./src/ClickHouseRepository.php) (*является базовым репозиторием и имеет дефолтный функционал*) и интерфейс репозитория, аналогично, должен быть унаследован от [ClickHouseRepositoryInterface](./src/Repository/Interfaces/ClickHouseRepositoryInterface.php).
    2. (Perhaps) *Конструктор базового/абстрактного репозитория принимает 3 аргумента: `normalizer, denormalizer, entityClass`. Если в процессе работы возникают ошибки при записи, возможно, вам стоит изменить формат данных или же проверить, как ваша сущность выглядит в нормализованном виде и правильно ли она маппится на таблицу. При необходимости, смотреть в [ClickHouseEntityNormalizer](./src/Serializer/Normalizer/ClickHouseEntityNormalizer.php).*
3. **Клиент/Adapter**

    1. Паттер адаптер, который закрывает взаимодствеие с ClickHouse через [интерфейс](./src/Client/Adapter/Interfaces/ClickHouseClientAdapterInterface.php) с методами select, insert, query и ping. Реализует прямой доступ к HTTP интерфейсу ClickHouse.
    2. **!!!Важно**: в коде, мы должны везде закрываться не реализацией, т.е. типом самого [класса адаптера](./src/Client/Adapter/ClickHouseClientAdapter.php), а его [интерфейсом](./src/Client/Adapter/Interfaces/ClickHouseClientAdapterInterface.php), для возможности подмены реализации.
    3. **!!!Важно**: в частности, [ClickHouseClientAdapter](./src/Client/Adapter/ClickHouseClientAdapter.php) реализует метод `query`, который третьим аргументом(`isAwaitableQuery`) принимает логическое значение и если оно истинно, то добавляет в запрос уникальный ключ и возвращает как результат инстас [ClickHouseSyncResponse](./src/Client/Response/ClickHouseSyncResponse.php) (подробнее о Response|SyncResponse в следующем пункте #4).
4. **Ответ/Response**

    Из любого метода адаптера, кроме метода `ping` мы получаем экземпляр класса [ClickHouseResponse](./src/Client/Response/ClickHouseResponse.php) или же [ClickHouseSyncResponse](./src/Client/Response/ClickHouseSyncResponse.php).

    1. [ClickHouseSyncResponse](./src/Client/Response/ClickHouseSyncResponse.php) - обертка для класса [Statement](./vendor/smi2/phpclickhouse/src/Statement.php), реализующая дополнительный функционал по ожиданию запросов (`ALTER TABLE t DELETE|UPDATE` - в ClickHouse выполняются в background-e, т.е. операция полностью не завершена, но ответ уже пришел). Данный класс позволяет вам с помощью методов `await` и `isDone` явно дождаться ответа и фиксации данных.
        1. `await` - ожидает, пока запрос не завершится, залипает в цикле, максимум на 10 минут (*конфигурируется через параметр*).
        2. `isDone` - единоразовая проверка без залипания, полезно, если ждем фиксацию + выполняем какую-то доп. обработку или т.п..
    2. [ClickHouseResponse](./src/Client/Response/ClickHouseResponse.php) - простая обертка для ответа из ClickHouse, является родителем для ClickHouseSyncResponse (советуется использовать метод `isSyncable` для определения, является ли экземляр сихронизируемым). Простой proxy-класс скрывающий реализацию.
5. **Примесь/Trait**

    1. [ClickHouseClientTrait](./src/Traits/ClickHouseClientTrait.php) - единственный функционал, который позволяет получить вышеописанный [Adapter](./src/Client/Adapter/ClickHouseClientAdapter.php) для работы с ClickHouse.
    2. Требования для использования trait-a:

        1. Класс, в котором подключается trait, должен имплементировать интерфейс [ClickHouseClientTraitInterface](./src/Traits/Interfaces/ClickHouseClientTraitInterface.php), либо же вы получите соответствующее [исклчюение](./src/Exception/ClickHouseNotImplementedException.php).
6. **Миграция/Migration**

    1. Должна имплементировать [ClickHouseMigrationInterface](./src/Migrations/Interfaces/ClickHouseMigrationInterface.php) и использовать вышеописанный trait явно (`$this->clickhouse()->(select|insert|query|ping)(...);`).
7. **Тест/Test**

    1. Если тест нуждается/взаимодействует с ClickHouse, то данный тест нужно унаследовать от [ClickHouseSetUpTestCase](./tests/_support/ClickHouseSetupTestCase.php), далее, использовать по усмотрению, явно через trait или же через репозиторий, который можно получить черзе EntityManager в любом тесте.
    2. **!!!Важно:** если вы переопределяете методы `setUp` или `tearDown`, нужно вызвать родительский метод (`parent::(tearDown|setUp)();`), либо явно очистить таблицы в тестовой БД в ClickHouse (`$this->clearTables();`). **!!!Важно:** очистка таблиц не произойдет и будет выброшено [исключение](./src/Exception/ClickHouseBadRequestException.php), если вы пытаетесь использовать этот метод не в тестовой среде.
    3. На данный момент для сущностей, которые работают с ClickHouse нельзя создать фикстуры (в дальнейшем, возможно, этот функционал будет реализован). Загрузку данных, можно реализовать явно, создав отдельный метод в тесте.
8. **Исключение/Exception**

    1. [Все исключения](./src/Exception), которые возникают при работе с ClickHouse, имплементируют [ClickHouseExceptionInterface](./src/Exception/Interfaces/ClickHouseExceptionInterface.php) и наследуются от [ClickHouseException](./src/Exception/ClickHouseException.php). Соответственно, могут быть перехвачены базовым интефейсом `\Throwable`.
9. **Запрос/Request (only syncable)**

    1. В данном кейсе нужно отметить, что если вы попытаетесь отправить запрос типа `Sync`, т.е. указав `isAwaitableQuery` параметр в значение `true` и в переданом SQL-e не будет условия `WHERE`, то получите соотвествующее [исклчюение](./src/Exception/ClickHouseBadRequestException.php) и том, что запросы данного вида не разрешены. Вы должны всегда явно указывать `WHERE {condition}` для запросов типа `Sync`.

###  Health Score

21

—

LowBetter than 19% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity5

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity46

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

1315d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/740f5a1cc81be1791f8b8dcd104762810010c32ba68c7cfa0fad119670bab3ce?d=identicon)[Borislavv](/maintainers/Borislavv)

---

Top Contributors

[![Borislavv](https://avatars.githubusercontent.com/u/50691459?v=4)](https://github.com/Borislavv "Borislavv (1 commits)")

---

Tags

adapterclickhouselibraryphprepositorysymfony

### Embed Badge

![Health badge](/badges/borislav-clickhouse/health.svg)

```
[![Health](https://phpackages.com/badges/borislav-clickhouse/health.svg)](https://phpackages.com/packages/borislav-clickhouse)
```

###  Alternatives

[laravel-doctrine/orm

An integration library for Laravel and Doctrine ORM

8425.3M87](/packages/laravel-doctrine-orm)[dunglas/doctrine-json-odm

An object document mapper for Doctrine ORM using JSON types of modern RDBMS.

6285.0M10](/packages/dunglas-doctrine-json-odm)[kimai/kimai

Kimai - Time Tracking

4.6k7.4k1](/packages/kimai-kimai)[glushkovds/phpclickhouse-laravel

Adapter of the most popular library https://github.com/smi2/phpClickHouse to Laravel

2031.2M2](/packages/glushkovds-phpclickhouse-laravel)[bolt/core

🧿 Bolt Core

585142.5k54](/packages/bolt-core)[cybercog/laravel-clickhouse

ClickHouse migrations for Laravel

163166.8k](/packages/cybercog-laravel-clickhouse)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)