phpClickHouse: Instructions file for Claude Code

CLAUDE.md — phpClickHouse

Project Overview

PHP client library for ClickHouse (smi2/phpclickhouse). Pure PHP, no dependencies beyond ext-curl and ext-json. Supports PHP 8.1+.

Principles

• Follow existing patterns in surrounding code — the codebase uses Doctrine coding standard (phpcs.xml.dist)
• Write tests for new functionality — all tests require a running ClickHouse instance
• Keep changes focused — avoid over-engineering, this is a lightweight HTTP client
• Security: all user-supplied values must go through ValueFormatter::formatValue() or bindings (:param), never raw string interpolation into SQL
• Use declare(strict_types=1) in every PHP file
• PSR-4 autoloading: ClickHouseDB\ namespace maps to src/
• Backward compatibility is sacred: NEVER rename, remove, or change signatures of public methods. Public API must remain fully compatible across versions. New parameters — only with default values. Deprecate, but don't break.

Architecture

Client (API) → Http (transport) → CurlerRequest/CurlerRolling (curl) → Statement (results)
                ↑                        ↑
            Settings              Query + Degenerations (SQL generation)

• Client.php — user-facing API: select(), write(), insert(), selectAsync()
• Statement.php — result wrapper with lazy parsing, implements Iterator
• Settings.php — connection config (timeouts, compression, HTTPS, readonly)
• Transport/Http.php — HTTP layer, auth methods (header/basic/query string), URL construction
• Transport/CurlerRolling.php — async execution via curl_multi_*
• Query/Query.php — SQL + format management, degeneration pipeline
• Query/Degeneration/Bindings.php — parameter binding (:param → escaped value)
• Query/Degeneration/Conditions.php — conditional SQL template blocks
• Quote/ValueFormatter.php — type-aware value escaping for SQL safety
• Cluster.php — multi-node cluster support with health checks

Key Notes

Running Tests