Weave Code
Phpclickhouse Laravel Package
smi2/phpclickhouse
PHP client for ClickHouse with sync and async queries, native parameter binding, bulk inserts, generators, gzip compression, cluster support, streaming, and progress callbacks. Requires PHP 8.1+, ext-curl, ext-json.
php ClickHouse wrapper
Frequently asked questions about Phpclickhouse
- How do I install smi2/phpclickhouse in a Laravel application?
- Run composer require smi2/phpclickhouse on a runtime with PHP 8.1+, ext-curl and ext-json enabled. Then register a service provider and facade in Laravel and keep host, port, username, password and database in your .env file. At the code level you instantiate ClickHouseDB\Client with those credentials and call $db->database('default') before issuing queries.
- Which PHP and Laravel versions does smi2/phpclickhouse support?
- Current releases require PHP 8.1+ along with ext-curl and ext-json. Projects still on PHP 8.0 must pin to 1.26.4 or earlier, while PHP 7.3, 7.2 and 5.6 are capped at 1.5.x, 1.3.10 and 1.1.2 respectively. Because it is a framework-agnostic HTTP client, it works with Laravel 9 and 10+ on PHP 8.1 through a service provider and facade rather than being tied to one Laravel release.
- Is phpClickHouse a native Eloquent driver for ClickHouse?
- No. It is a zero-dependency PHP client, not an Eloquent driver, so model-level query building and relationship support are not provided. The recommended pattern is to treat ClickHouse as a secondary analytical store beside PostgreSQL or MySQL, wiring it in through a service provider, facade and query builder macros. ClickHouse DDL and advanced column types still need application-level handling with custom casts, accessors and Artisan commands.
- How does phpClickHouse protect against SQL injection in Laravel queries?
- Use native query parameters with server-side {name:Type} binding, which makes injection impossible for those values, or the binding and SQL template helpers. The newer type wrappers such as StringType and the numeric types with fromString() validation are escaped by ValueFormatter before they reach the SQL string. Legacy Type objects are still interpolated unescaped, so audit any existing raw Type usage and migrate untrusted input to the validated wrappers.
- How do I run async or parallel ClickHouse queries without blocking Laravel requests?
- The client supports both sync and async parallel SELECT queries, but Laravel's synchronous request cycle can still block on slow ClickHouse calls. Offload heavy inserts and long-running analytics to Laravel Queues or PHP-CLI workers, and set per-query timeouts such as max_execution_time. Generators, streaming read/write, gzip insert compression and progress callbacks help keep memory and throughput under control.
- How do I map ClickHouse types like DateTime64, Decimal, Enum and UUID to Laravel models?
- Use the package's type wrappers at the query boundary: StringType, FixedString(N), Date, DateTime, Enum8/Enum16, Int8 through Int256, UInt8 through UInt256, Float32/64 and Decimal32 through Decimal256. Then add custom Eloquent casts and accessors so attributes surface as Carbon instances, native PHP scalars or backed enums. This keeps type safety in the application while ClickHouse keeps its own wider type system.
- How do I read ClickHouse Decimal values in PHP without losing precision?
- PHP's json_decode loses precision for decimals beyond roughly 16 significant digits, which matters for financial and high-precision analytics columns. Select those columns with toString() so they arrive as strings, then process them with bcmath or a dedicated decimal library. Identify the affected columns up front rather than relying on default numeric decoding.
- How should I manage ClickHouse schema migrations in a Laravel project?
- There is no built-in migration support, because ClickHouse DDL and its engines, codecs and materialized views differ from Laravel migrations. Write custom Artisan commands or explicit schema-management scripts and run them as a deployment step. Keeping ClickHouse schema changes separate from transactional database migrations avoids coupling the two systems.
- How do I get ClickHouse error details and server stack traces from phpClickHouse?
- The package throws structured exceptions carrying the ClickHouse error name and query ID, and DatabaseException exposes getServerVersion() and getServerStackTrace(). The server stack trace is not included in getMessage() by default and requires opting in per query with ['stacktrace' => 1]. Log those getters where diagnostics matter and avoid enabling stack traces globally to keep response sizes and overhead down.
- Does phpClickHouse support ClickHouse clusters, replicas and connection pooling?
- Cluster support covers auto-discovery, health checks and replicas, along with HTTPS, SSL CA and IPv6 connectivity. There is no built-in Laravel connection pooling for ClickHouse, so pair the client with queue-based writes, PHP-CLI workers and Redis or cache for hot dashboard reads. Benchmark the HTTP client latency against your expected QPS and cache frequent analytics responses before scaling traffic.
Weaver
How can I help you explore Laravel packages today?