Phpclickhouse Laravel Package

Breaking Changes

• Minimum PHP raised to 8.1 — composer.json now requires php: ^8.1 and the CI matrix drops 8.0. PHP 8.0 users should pin 1.26.4 (last 8.0-compatible release); the typed >= 1.24.406 line already targets 8.1+

New Features

• String, date and enum type wrappers (#269, @sander-hash) — StringType (PHP reserves String), FixedString(N) with strict byte-length validation, Date, DateTime (with optional non-mutating timezone conversion), Enum8, Enum16. All implement the new StringableType interface: unlike legacy Type objects, their values are escaped by ValueFormatter, bindings, and native parameters
• Full numeric scalar type coverage (#271, @RemcoSmitsDev) — Int8–Int256, UInt8–UInt256, Float32/Float64, Decimal32–Decimal256 via the new ScalarNumericType interface (Bool maps to the existing Boolean class). fromString() validates input — integers require ^-?\d+$, floats/decimals require is_numeric() — closing an SQL-injection vector for untrusted input, since Type values are interpolated into SQL unescaped
• Structured exceptions enriched (#270, @sander-hash) — DatabaseException::getServerVersion() and getServerStackTrace() (populate with per-query ['stacktrace' => 1]); reworked error-response parsing in Statement. The server stack trace is kept out of getMessage() — it is available only via the dedicated getter

Testing

• IEEE 754 mantissa test suite (tests/Type/Ieee754MantissaTest.php, 31 cases) — significand limits and overflow collapse for Float32 (2^24), Float64 (2^53), BFloat16 (2^8, CH 24.11+); 0.1 + 0.2 != 0.3 vs exact Decimal arithmetic; inf/nan → null in JSON; scale-0 truncation toward zero; Decimal arriving as an unquoted JSON number on every supported server; the json_decode() precision trap for >16-digit decimals (exact reads need toString())
• ClickHouse 26.9 test matrix — third container clickhouse-26-9 (26.9.1.1629, port 8125), phpunit-ch269.xml, CI job PHP 8.1–8.4 × CH 26.9. Suites for 21.9 / 26.3 / 26.9 run separately
• Per-query settings integration test for CH 26 (#272, @sander-hash) — verifies per-query max_execution_time is visible to getSetting() without touching global settings

Documentation

• IEEE 754 references — Float sections in README.md, doc/types.md, and the Pages site now link the IEEE 754 standard and the ClickHouse Float reference, with a verified 0.1 + 0.2 != 0.3 example and the exact-Decimal counterpart
• todo.md translated to English (#268, @sander-hash)
• Fixed the version-compatibility table in README.md and the Pages site (docs/index.md)

CI / Chore

• Scrutinizer integration removed — the GitHub Actions matrix already covers tests, PHPStan, and PHPCS
• .gitignore now covers .DS_Store, .idea/, vim swap files, and local ClickHouse data directories

Merged PRs

• #268 — Translate todo from russian to english (@sander-hash)
• #269 — Add string and date type support (@sander-hash)
• #270 — Added structuredExceptions (@sander-hash)
• #271 — Add more numeric types (@RemcoSmitsDev)
• #272 — Improve per query settings tests (@sander-hash)

Bug Fixes

• Distributed DDL (ON CLUSTER) formatting reworked (#241, #263, #262) — Http::prepareWrite() no longer appends FORMAT JSON to the SQL of ON CLUSTER queries. Instead the response format is requested via the default_format=JSON query setting:
  • CREATE USER / GRANT / ALTER ... ON CLUSTER no longer fail with SYNTAX_ERROR from a stray FORMAT JSON (#241)
  • CREATE / ALTER ... ON CLUSTER results are now parseable JSON again — no more Can't find meta when reading the per-host execution status (#263)
  • a bare ON CLUSTER substring inside INSERT data (e.g. 'REGION CLUSTER') is no longer mistaken for the keyword — \b word boundaries match the real keyword only (#262)
• False-positive error detection on large JSON responses (#261) — Statement::hasErrorClickhouse() now confirms a tail-regex match with json_validate() (PHP 8.3+) before flagging an error, so valid JSON whose data legitimately contains ClickHouse exception text is not reported as a failure (@jradtilbrook)

Testing

• New tests/ClickHouse26/OnClusterTest.php — distributed DDL regression tests (CREATE / ALTER / CREATE USER ... ON CLUSTER); skips gracefully when no Keeper/ZooKeeper backend is configured
• Embedded ClickHouse Keeper added to the test environment (tests/clickhouse-latest-config/keeper.xml, mounted in docker-compose.yaml and copied in CI) so the single-node default cluster can execute ON CLUSTER queries
• testInsertWithOnClusterInData added to both CH 21 and CH 26 client tests (#262)

Merged PRs

• #261 — Fix false positive error detection when JSON data contains ClickHouse exception text (@jradtilbrook)

Closed Issues

• #241 — ALTER / CREATE / DROP / RENAME queries fail when using ON CLUSTER
• #262 — extra FORMAT JSON in the query when inserting a record (superseded by the default_format fix)
• #263 — "Can't find meta" error since 1.24.406

2026-04-23 [Release 1.26.423]

Bug Fixes

• Escape single quotes and backslashes in scalar string native params (#258, #259) — convertParamValue() now escapes \ → \\ and ' → \' for scalar String params in selectWithParams() / writeWithParams(). Previously strings like hello\ caused CANNOT_PARSE_ESCAPE_SEQUENCE in ClickHouse (@sander-hash, @tom-on-the-internet)

Testing

• 5 new native-params tests — scalar strings with trailing backslash, embedded backslash, single quote, injection attempt, and writeWithParams with backslash

Merged PRs

• #259 — Added escape for scalar string (@sander-hash)

Closed Issues

• #258 — Scalar string params are not escaped, causing CANNOT_PARSE_ESCAPE_SEQUENCE

2026-04-17 [Release 1.26.417]

Bug Fixes

• Correctly encode arrays for native param binding (#257) — convertParamValue() now produces ClickHouse-compatible array literals ['foo','bar'] (single quotes) instead of JSON format ["foo","bar"]. Previously any Array(String) parameter in selectWithParams() / writeWithParams() failed with a parse error (@sander-hash)
• Escape single quotes and backslashes in array strings — follow-up to #257. Strings containing ' or \ are now properly escaped (e.g. "it's" → 'it\'s'), preventing query errors and array-element injection

Testing

• 6 new native-params tests — cover Array(UInt32), Array(String), empty arrays, strings with single quotes, strings with backslashes, and injection attempts

Merged PRs

• #257 — Correctly encode array for native param binding (@sander-hash)

2026-04-12 [Release 1.26.412]

Bug Fixes

• Fix bindParams() TypeError with numeric keys (#256) — bindParams() now casts integer array keys to string before passing to bindParam(string $column), restoring backward compatibility with numerically-indexed arrays. Affected downstream packages like phpclickhouse-laravel (@yehezkel-fullpath)

Testing

• Flaky tests excluded from default runs — testConnectTimeout, testStreamInsert, testStreamInsertFormatJSONEachRow marked [@group](https://github.com/group) flaky and excluded via PHPUnit config. Run separately with ./vendor/bin/phpunit --group flaky
• 2 new binding tests — testBindParamsWithNumericKeys, testBindParamsWithMixedKeys covering #256 regression

Closed Issues

• #256 — Breaking change: strict string type on Bindings::bindParam() rejects integer keys

2026-04-10 [Release 1.26.410]

New Features

• readWithParams() (#254) — stream query results with native ClickHouse typed parameters ({name:Type} syntax), combining server-side parameter binding with streaming output (@sander-hash)

Code Quality

• Stringable interfaces (#252) — all Type classes now explicitly implement Stringable for consistency (@sander-hash)
• PHPStan test fixes (#253) — removed redundant assertions in static tests, improved assertion quality (@sander-hash)
• Documentation sync — updated GitHub Pages (docs/) with readWithParams() in native-params, streaming, and per-query-settings guides

Merged PRs

• #252 — Add Stringable interfaces for types (@sander-hash)
• #253 — Fix phpstan errors in test files (@sander-hash)
• #254 — Added native params for read function (@sander-hash)

2026-04-06 [Release 1.26.406]

WARNING : PHP 8.1+

New Features

• Boolean Type (#251) — new ClickHouseDB\Type\Boolean class with fromString(), fromBool(), getValue(), __toString() (@sander-hash)

Code Quality

• PHP 8.1+ native type declarations — full migration across all 33 src/ files: property types, parameter types, return types. Interfaces (Degeneration, IStream, Type) unchanged for backward compatibility
• PR Security Review rules — added supply-chain attack detection checklist to CLAUDE.md (outbound network calls, data exfiltration, obfuscation, credential leakage patterns)
• Security audit — full code audit of src/, results saved in secure-scan.md. All clean: no backdoors, exfiltration, or obfuscation found

Testing

• 153 new static unit tests — run without ClickHouse server:
  • ValueFormatterTest (28) — SQL escaping, types, DateTimeInterface, Expression
  • StrictQuoteLineTest (32) — CSV/TSV/Insert formatting, encodeString
  • SettingsTest (24) — get/set/is, sessions, timeouts, readonly
  • WriteToFileTest (15) — file validation, formats, gzip
  • TypesTest (26+5) — UInt64, DateTime64, MapType, TupleType, Boolean and more
  • BindingsUnitTest (16) — compile_binds, Conditions {if}/{else}
  • CurlerRequestResponseTest (35) — headers, auth, URL, JSON, dump
• Total: 313+ tests (CH 21.9 + CH 26.3 + static), all passing

Merged PRs

• #251 — feat: Add Boolean type (@sander-hash)

2026-04-04 [Release 1.26.4]

Many changes see change.log

2025-01-14 [Release 1.6.0]

• Support php 8
• And some pr & fixes

2024-01-18 [Release 1.5.3]

• Fix release 1.5.2
• Support php 7
• Update Statement.php #204
• fix(#202): Fix converting boolean when inserting into int and fix(#194): Fix unexpected readonly mode with specific string in query #203
• Update README.md #199
• remove dev files for --prefer-dist #192

2024-01-16 [Release 1.5.2]

• Update Statement.php #204
• fix(#202): Fix converting boolean when inserting into int and fix(#194): Fix unexpected readonly mode with specific string in query #203
• Update README.md #199
• remove dev files for --prefer-dist #192

BREAKING CHANGES

• Post type bindings support

SELECT number+{num_num:UInt8} as numbe_r, {xpx1:UInt32} as xpx1,{zoza:String} as zoza FROM system.numbers LIMIT 6

2022-12-21 [Release 1.5.0]

• Change exceptionCode in Clickhouse version 22.8.3.13 (official build) #180

• Fix Docker for tests, Change the correct Docker image name #177

• Some type fix

• Fix types: max_execution_time & setConnectTimeOut, undo: Support floats in timeout and connect_timeout #173

• add mbstring to composer require #183

• fixed progressFunction #182

• Add allow_plugins setting since Composer 2.2.x #178

• Re upload 1.5.0 - hot fix types error

2022-06-22 [Release 1.4.6]

• Return type of ClickHouseDB\Statement::current() should either be compatible with Iterator::current() #170

2022-06-09 [Release 1.4.5]

• Migrate setTimeout from Float to Int
• Add Statement Iterator

2022-04-23 [Release 1.4.4]

• Fix ping() for windows users
• ping(true) throw TransportException if can`t connect/ping

2022-04-20 [Release 1.4.3]

• Fix: prevent enable_http_compression parameter from being overridden #164
• For correct work with utf-8 . I am working on server with PHP 5.6.40 Update CurlerRequest.php #158
• Add curl setStdErrOut, for custom StdOutErr.
• Fix some test for check exceptions

2022-02-11 [Release 1.4.2]

• Fixed issue with non-empty raw data processing during init() on every fetchRow() and fetchOne() call - PR #161

2021-01-19 [Release 1.4.1]

• Add support php 7.3 & php 8

2019-09-29 [Release 1.3.10]

Add two new types of authentication #139 Fixed typo in streamRead exception text #140 fix the exception(multi-statement not allow) when sql end with ';' #138 Added more debug info for empty response with error #135

2020-02-03 [Release 1.3.9]

• #134 Enhancement: Add a new exception to be able to distinguish that ClickHouse is not available.

2020-01-17 [Release 1.3.8]

• #131 Fix: async loop breaks after 20 seconds
• #129 Add client certificate support to able to work with Yandex ClickHouse cloud hosting
• Delete dropOldPartitions
• Fix error : The error of array saving #127
• More test

2019-09-20 [Release 1.3.7]

• #125 WriteToFile: support for JSONEachRow format

2019-04-29 [Release 1.3.6]

• #122 Add function fetchRow()
• Use X-ClickHouse-User by headers
• Add setDirtyCurler() in HTTP
• Add more tests

2019-04-29 [Release 1.3.4]

• #118 Fix Error in Conditions & more ConditionsTest
• Fix phpStan warnings in getConnectTimeOut() & max_execution_time()

2019-04-25 [Release 1.3.3]

• fix clickhouse release 19.5.2.6 error parsing #117
• chore(Travis CI): Enable PHP 7.3 testing #116

2019-03-18 [Release 1.3.2]

• fix: add CSVWithNames to supported formats #107
• Upgraded Expression proposal #106 -> UUIDStringToNum
• Correct query format parsing #108
• Can not use numbers() function in read requests #110
• #109 Do not use keep-alive or reuse them across requests

2018-09-25 [Release 1.3.1]

• Pull request #94 from simPod: Uint64 values
• Pull request #95 from simPod: Bump to php 7.1

2018-09-11 [Release 1.2.4]

• Fix #91 ,Does not work inserting with the database name in the table
• pull request #90 from simPod: Refactor partitions()

2018-08-30 [Release 1.2.3]

• Escape values in arrays, pull request #87 from simPod/fix-escape
• fix-bindings: pull request #84 from simPod/fix-bindings
• Added quotes arount table and column names in the insert wrapper.
• Docker Compose in tests

• Connection without port

Release 1.2.1

• New $client->getServerVersion()
• Rewrite method $client->ping()
• Fix include.php - ClickHouseException before exceptions
• Add CHANGELOG.md
• New interface ClickHouseException