Phpclickhouse Laravel Package

Technical Evaluation

Architecture Fit

• High Fit for Laravel analytics workloads: The package remains a zero-dependency PHP ClickHouse client, suitable for Laravel applications needing OLAP, real-time analytics, time-series data, event sourcing, CQRS, or dashboarding.
• Laravel Integration: Still integrates through a Service Provider / facade, Query Builder macros, and custom Eloquent casts/accessors; it is not a native Eloquent driver, so ClickHouse DDL and advanced types require application-level handling.
• Hybrid Architecture: Best positioned as a secondary analytical store alongside PostgreSQL/MySQL rather than a transactional replacement.
• Release 1.26.925 strengthens type safety: New string/date/enum wrappers, full numeric scalar types, and structured exceptions reduce several integration risks, especially around untrusted input and diagnostics.

Integration Feasibility

• Laravel Service Provider / Facade: Still feasible via package registration and a ClickHouse facade over the client.
• Typed value objects: New StringType, FixedString(N), Date, DateTime, Enum8, Enum16, Int8–Int256, UInt8–UInt256, Float32/64, and Decimal32–Decimal256 can be used at the application boundary before passing values into queries.
• Security improvement: StringableType values are escaped by ValueFormatter, bindings, and native parameters; numeric fromString() validation closes an SQL-injection vector for untrusted input when these wrappers are adopted.
• Structured exceptions: DatabaseException::getServerVersion() and getServerStackTrace() improve production diagnostics, but the server stack trace is not included in getMessage() and requires per-query ['stacktrace' => 1].
• Eloquent fit remains partial: Custom casts/accessors are still needed for ClickHouse DateTime64, UUID, decimals, and enum types.

Technical Risk

Key Questions for TPM

1. Runtime baseline: Are all Laravel apps, CI runners, and production containers on PHP 8.1+? If not, which services must pin 1.26.4?
2. Security exposure: Are any user-supplied values currently passed through legacy Type objects rather than the new validated/escaped wrappers?
3. Precision requirements: Do any analytics use cases require exact decimals beyond 16 digits, requiring string-based reads instead of JSON numeric decoding?
4. Observability: Will the team capture getServerVersion() and getServerStackTrace() in logs? Will per-query stacktrace be enabled selectively?
5. ClickHouse version: Production is on which ClickHouse version? The package now tests against CH 21.9 / 26.3 / 26.9, but the deployed version still needs validation.
6. Use case: Is ClickHouse read-only analytics, write-heavy event ingestion, or hybrid? This determines queueing, batching, and caching design.

Integration Approach

Stack Fit

Migration Path

1. Phase 0: Runtime and security compatibility
   • Confirm PHP 8.1+ across Laravel apps and CI.
   • Pin 1.26.4 only for services still on PHP 8.0.
   • Audit existing Type usage and identify untrusted inputs that should move to StringableType / ScalarNumericType.
2. Phase 1: Read-only analytics
   • Introduce ClickHouse as a secondary connection.
   • Move PostgreSQL-heavy reporting queries to ClickHouse.
   • Use DB::connection('clickhouse') or a facade for read queries.
3. Phase 2: Write support with safe typing
   • Implement bulk inserts via queued jobs.
   • Use new string/numeric/date/enum wrappers at ingestion boundaries.
   • Handle decimal reads carefully; use toString() where precision matters.
4. Phase 3: Hybrid transactions
   • Keep PostgreSQL/MySQL as the transactional source of truth.
   • Dispatch async ClickHouse sync jobs after application events or transactions.
5. Phase 4: Expand analytical ownership
   • Migrate read-heavy analytical tables where appropriate.
   • Keep transactional workloads out of ClickHouse unless explicitly validated.

Compatibility

Sequencing

1. Upgrade dependency and runtime
   • Set Composer constraint appropriately.
   • Ensure CI covers PHP 8.1–8.4 and the production ClickHouse version.
2. Register ClickHouse connection and facade
   • Add secondary connection config.
   • Register package service provider and optional facade.
3. Add safe type usage
   • Use new string/numeric/date/enum wrappers for untrusted values.
   • Replace raw legacy Type interpolation where possible.
4. Implement async writes
   • Create queued jobs for bulk inserts.
   • Add retry/backoff and idempotency handling.
5. Add observability
   • Log getServerVersion() and getServerStackTrace().
   • Enable per-query stack traces selectively.
   • Add query timing and failure metrics.
6. Validate precision and ClickHouse version
   • Test decimal-heavy queries against production ClickHouse.
   • Confirm JSON decoding behavior for high-precision decimals.

Operational Impact

Maintenance

Support

• Improved diagnostics: Structured exceptions provide server version and optional server stack trace.
• Support caveat: Server stack traces are not in the exception message; support runbooks must explicitly log/read them.
• Runtime caveat: PHP 8.0 services will fail Composer resolution on 1.26.925 and must pin 1.26.4.
• Type safety caveat: Security benefit depends on adopting new wrappers; legacy unescaped Type usage remains a risk.

Scaling

• Read scaling: Use Redis/cache for repeat analytics queries; keep ClickHouse queries bounded with timeouts.
• Write scaling: Prefer queued bulk inserts over synchronous per-request writes.
• Connection management: The client does not provide Laravel-native pooling; plan worker-based or queue-based access patterns.
• Precision scaling: For high-precision decimals, read as strings to avoid JSON decoding precision loss.

Failure Modes

Ramp-Up

• TPM / engineering effort: Medium.
• Team learning needs: ClickHouse type system, decimal precision behavior, async ingestion patterns, and structured exception handling.
• Recommended first milestone: Upgrade runtime compatibility, adopt safe type wrappers for untrusted inputs, and add structured exception logging before expanding ClickHouse usage.