Phpclickhouse Laravel Package

Product Decisions This Supports

• Build vs. Buy Decision:

  • Buy: Continue with phpClickHouse. Release 1.26.925 materially strengthens the case — the client now ships typed wrappers for strings, dates, enums, and the full numeric scalar range (Int8–Int256, UInt8–UInt256, Float32/64, Decimal32–Decimal256), plus structured server-side error metadata. That is a validation and type-mapping layer we would otherwise build and maintain ourselves.
  • Build: Only if requirements exceed the package's scope (custom ClickHouse extensions/UDFs, proprietary auth flows, or a formal support contract). Note the package remains a low-level client — any API/service layer is still ours to build.
  • Re-evaluate: Teams on PHP 8.0 — 8.1 is now the floor. Decision is either "upgrade PHP" (preferred) or "pin 1.26.4 and freeze", which carries security-patch exposure since the injection-hardening work landed after that tag.

• Feature Roadmap:

  • Analytics Pipeline: Async queries and generators remain the backbone for real-time processing of large datasets (log aggregation, clickstream).
  • Data Warehousing / ETL: Bulk inserts (arrays/CSV/streams) and cluster support for scalable loads.
  • Input Safety (upgraded): Two distinct protections now exist — native typed parameters ({name:Type}) at the protocol level, and validated + escaped type wrappers (fromString() enforces ^-?\d+$ for integers, is_numeric() for floats/decimals; new StringableType values are escaped by ValueFormatter, bindings, and native parameters). This closes the historic SQL-injection vector where Type values were interpolated unescaped.
  • Migration work item: legacy Type objects do not get the new escaping. Any existing code interpolating Type values into SQL must be migrated to the new wrappers — treat this as a security backlog item, not a nice-to-have.
  • Financial / Billing Reporting: Decimal32–Decimal256 with exact arithmetic is now first-class. Standardize on Decimal for money and anything auditable; Float is only appropriate for approximate metrics. Be aware of the documented json_decode() precision trap for >16-digit decimals — exact reads must go through toString().
  • Observability / Supportability: DatabaseException::getServerVersion() and getServerStackTrace() (opt in per query with ['stacktrace' => 1]) give support and on-call engineers real server context. The stack trace is deliberately excluded from getMessage(), so we must decide explicitly whether to log it — and must not surface it to end users or API responses.
  • Cost Optimization: HTTP compression for inserts and per-query settings (e.g. max_execution_time, max_block_size) for tuning without touching global server config.

• Use Cases:

  • High-Volume Data Ingestion: Stream inserts (IoT telemetry, ad-click tracking) with progress callbacks.
  • Reporting Dashboards: Async SELECTs for concurrent multi-tenant fetching.
  • Microservices: Lightweight client for PHP services querying ClickHouse (recommendation, personalization).
  • Data Migration: Bulk INSERT INTO ... SELECT with structured error handling for large moves.
  • Compliance-Sensitive Ingestion: Untrusted-input paths (partner feeds, user-submitted dimensions) now have validated, escaped type objects to lean on.

• Platform / Upgrade Decision: The PHP 8.1 requirement is a roadmap dependency. Confirm PHP 8.1–8.4 coverage across our services (the project's CI now tests exactly that range against ClickHouse 21.9 / 26.3 / 26.9) so the upgrade is a schedule item rather than a surprise.

When to Consider This Package

Adopt if:

• Your stack is PHP 8.1+ (8.4 supported) and you need a production-ready ClickHouse client with no external dependencies beyond ext-curl/ext-json.
• You need async/parallel queries, cluster support, or memory-efficient generators for large result sets.
• Security is critical: native typed parameters plus validated, escaped type wrappers (StringType, FixedString(N), Date/DateTime, Enum8/16, full numeric coverage) defend at the protocol and value level.
• You handle money or audit-grade numbers: Decimal types with documented IEEE 754 caveats and exact-arithmetic guidance.
• You want server-side diagnosability: server version and ClickHouse stack traces on failures, opt-in per query.
• You require bulk operations (CSV/stream inserts) or real-time progress tracking for INSERT/SELECT.

Look elsewhere if:

• You are pinned to PHP 8.0 or below and cannot upgrade — pin 1.26.4, but accept that the injection-hardening and type-wrapper work is unavailable.
• You need a service layer (GraphQL/REST) over ClickHouse; this is a low-level client, not an API abstraction.
• Your use case demands custom ClickHouse extensions (e.g. UDFs) not exposed by this wrapper.
• You need sub-millisecond request latency at the driver level (consider native drivers or Rust/Go clients).
• You require a formal support contract, LTS branch, or vendor SLA — releases are frequent (1.26.610 → 1.26.925) but versioning is date-based rather than semantic, so pin exact tags and read release notes before upgrading.
• You need strongly typed ORM/query-builder ergonomics; this remains a thin client over SQL.

How to Pitch It (Stakeholders)

For Executives: "phpClickHouse is a battle-tested, MIT-licensed PHP client for ClickHouse, and the new 1.26.925 release closes the gap that would have forced us to build our own type and validation layer. It now covers the complete ClickHouse scalar type set — including exact Decimal for financial reporting — with input validation and escaping that removes a known SQL-injection vector for untrusted data. Failures now carry server version and server-side stack traces, which shortens incident diagnosis. Cost: one PHP 8.1 upgrade (8.0 support was dropped) and a small migration of legacy type usage. We still build our own API layer on top, but we avoid owning and maintaining a database client."

For Engineering: *"Upgrade to 1.26.925 (minimum PHP 8.1; last 8.0-compatible tag is 1.26.4). What you get:

• Type wrappers: StringType, FixedString(N) (strict byte-length validation), Date, DateTime (optional non-mutating timezone conversion), Enum8/Enum16, and Int8–Int256 / UInt8–UInt256 / Float32–Float64 / Decimal32–Decimal256.
• Security: fromString() validates input (integers ^-?\d+$, floats/decimals is_numeric()); new StringableType values are escaped by ValueFormatter, bindings, and native parameters. Legacy Type values are still interpolated unescaped — migrate them.
• Structured exceptions: getServerVersion(), getServerStackTrace() via per-query ['stacktrace' => 1]; trace is kept out of getMessage() so it won't leak into logs/UI unless you opt in.
• Numeric correctness: IEEE 754 mantissa limits tested (Float32 2^24, Float64 2^53, BFloat16 2^8); 0.1 + 0.2 != 0.3; Decimal for exact math; inf/nan → null in JSON; the json_decode() precision trap for >16-digit decimals — read those via toString().

Trade-offs:

• Breaking: PHP 8.0 dropped from composer.json and CI.
• Not a service layer — REST/GraphQL abstraction is still ours.
• Date-based versioning, no LTS; pin tags and review notes on upgrade.

Recommendation: Standardize on 1.26.925 for analytics pipelines, data warehousing, high-volume ingestion, and any Decimal-bearing reporting. Schedule the PHP 8.1 upgrade first, then migrate legacy Type usage to the escaped wrappers as a security task."*