Download the PHP package ysfkc/clickhouse without Composer

ysfkc/clickhouse

A lightweight, framework-agnostic ClickHouse HTTP client for PHP 8.1+ with a fluent QueryBuilder and an ORM-style model layer.

Table of Contents

• Architecture
• Installation
• Configuration
  • Step 1 — Configure
  • Step 2 — getInstance()
  • Step 3 — Usage
• QueryBuilder
  • SELECT
  • WHERE Conditions
  • JOIN
  • GROUP BY / HAVING
  • ORDER BY / LIMIT / OFFSET
  • INSERT
  • Raw Query — raw()
• Model System (ORM)
  • Defining a Model
  • Querying Records
  • Inserting Records
  • rawQuery / rawCommand
• ClickHouseResponse
• ClickHouseCollection
• Direct Client Usage
• Security
• ClickHouse Type Reference
• Phalcon Integration

Architecture

Installation

Requirements: PHP 8.1+, guzzlehttp/guzzle ^7.0, psr/log ^1|^2|^3

Configuration

Step 1 — Configure once at bootstrap

Call ClickHouseClientService::configure() once at application startup (service provider, bootstrap file, etc.):

With a PSR-3 logger:

Step 2 — Obtain the client via getInstance()

After configure() is called, retrieve the shared ClickHouseClient instance from anywhere in your application:

getInstance() creates the client lazily on the first call and returns the same instance on every subsequent call. Calling configure() again invalidates the old instance and forces a fresh one on the next getInstance() call.

⚠️ Calling getInstance() before configure() throws a \RuntimeException.

Step 3 — Use the client directly or via QueryBuilder / Model

Once configured, you can use any of the three layers — they all resolve the client internally via getInstance():

Optional — Inject a PSR-3 logger for models

QueryBuilder

QueryBuilder is started via the static table() method. All methods support fluent chaining.

SELECT

WHERE Conditions

Basic Equality

Comparison Operators

IN / NOT IN

BETWEEN (Date Range)

NULL Checks

whereRaw — Raw Condition

⚠️ Use only when where() cannot express the condition. Never embed user input directly — use QueryBuilder::raw() with parameters instead.

JOIN

GROUP BY / HAVING

ORDER BY / LIMIT / OFFSET

First Row

COUNT

INSERT

Single Row

Batch INSERT

Raw Query — raw()

For complex queries that cannot be expressed with the structured methods:

Debug — toSql()

Model System (ORM)

Defining a Model

Querying Records

all() — All Records

find() — Conditional Query

findFirst() — First Record

countBy() — Count

query() — Advanced Fluent Query

queryBetweenDates() — Date Range Shorthand

Inserting Records

insertRow() — Single Row

insertBatch() — Bulk Insert

rawQuery / rawCommand

rawQuery — Custom SELECT

⚠️ Pass only hardcoded strings as $query. All dynamic values must go through $params.

rawCommand — DDL Commands

ClickHouseResponse

ClickHouseCollection

Direct Client Usage

Security

Parameterized Queries

All user-supplied values are sent as param_* query string parameters, never interpolated into the SQL body:

Blocked Vectors

Rule: whereRaw / having / join Conditions

ClickHouse Type Reference

Note: The Array(…) wrapper is added automatically for IN / NOT IN. ->where('status', 'IN', ['ok', 'warning', 'error'], 'String') → status IN {p:Array(String)}

Phalcon Integration (Optional)

If you use this package inside a Phalcon application, bridge the Phalcon logger to PSR-3 using the included optional adapter:

License

MIT