Clickhouse Builder Laravel Package

Technical Evaluation

Architecture fit

• esazykin/clickhouse-builder is a standalone PHP fluent SQL builder, not a Laravel package. There is no service provider, facade, config file, or Eloquent integration, so "Laravel leverage" means manually constructing SQL strings inside your application code and executing them through a separate transport (HTTP interface, native client, or a PDO driver).
• It occupies the query-construction layer only. Any real integration still needs a connection/transport layer, a result hydrator, and a place to register it in the container — all of which we would own.
• Fit is therefore narrow: useful only where we generate ClickHouse SQL dynamically (filters, report builders, multi-tenant query composition). For static analytical SQL, a plain string or view is a better fit.

Integration feasibility

• Composer-requireable and PSR-4 autoloaded, which is the one genuinely low-friction element.
• The blocking issue is version constraints. The last release is December 2017, which places it in the PHP 5.6/7.0–7.1 era. On a modern Laravel 10/11 stack (PHP 8.2+), expect either a hard composer conflict or a --ignore-platform-reqs install that runs untested code paths.
• Because it has 1 star and 0 dependents, there is no signal that anyone has validated it against current PHP or current ClickHouse. We would be the first.

Technical risk

• Abandonment risk: high. Nearly eight years without a release, no maintainer activity, no issue triage, no security response.
• Correctness/security risk: high. The critical question is identifier and value escaping. If the builder interpolates values rather than emitting parameterized queries, every dynamic filter becomes an injection vector — unacceptable for a data platform used by internal analysts building ad-hoc queries.
• Feature-coverage risk: high. A 2017 builder predates most of what modern ClickHouse users depend on: window functions, LIMIT BY, FINAL, lightweight DELETE/UPDATE, JSON/Map/Tuple types, and modern SETTINGS clauses. Teams will hit the ceiling quickly and start patching vendor code.
• Score context: the 0.095 composite score and 14.38 opportunity score confirm this is a low-adoption, low-velocity artifact — a reference implementation, not a dependency.

Key questions

1. Does it emit parameterized queries, or does it string-interpolate values and identifiers?
2. What are the exact composer.json PHP and illuminate/* constraints (if any)?
3. Does it cover the ClickHouse version we run, or will the team be writing raw SQL for anything beyond basic SELECT/WHERE/GROUP BY?
4. Who owns it if we adopt — is there budget for an internal fork maintained by our team?
5. Is the actual need "fluent query building," or is it "a typed ClickHouse client"? These have very different build-vs-buy answers.

Integration Approach

Stack fit

• Clean fit only on legacy PHP 7.x / Laravel 5.x estates. On PHP 8.1+ or Laravel 9+, treat it as incompatible until proven otherwise by a spike.
• Its framework-agnosticism is an asset for extraction: no Laravel coupling means no upgrade lock-in if we later swap the builder out.

Migration path

• Recommended: do not take it as a production dependency. Use it as a reference implementation — read the source for SQL-generation patterns, then either:
  • adopt a maintained client (smi2/phpClickHouse, or the official ClickHouse HTTP interface behind a thin repository layer), or
  • vendor a forked copy under our org namespace with our own test suite and PHP 8 compatibility fixes.
• If it is already in a codebase, wrap it immediately behind an internal ClickHouseQueryBuilder interface so the concrete implementation is swappable without touching call sites.

Compatibility

• Verify PHP 8.2/8.3 runtime behavior for deprecated constructs and implicit-nullable parameter handling. Add a static analysis pass (PHPStan) plus a golden-file test that asserts generated SQL strings.
• Pin the dependency with an exact version and a replace/fork entry in composer.json so a transitive resolution can never silently move it.

Sequencing

1. Spike (1–2 days): install in an isolated branch, confirm composer resolution, generate a representative query set, diff output against expected SQL.
2. Security gate: audit escaping/parameterization before anything touches user-supplied filters.
3. Fork decision: if the spike passes, fork to an internal repo with CI (unit tests + PHPStan + PHP matrix).
4. Wrapper: ship the internal interface and migrate call sites to it.
5. Re-evaluate against a maintained alternative at the next architecture review; target full replacement within two quarters.

Operational Impact

Maintenance

• Effectively zero upstream maintenance. Adoption means permanent ownership: PHP upgrades, ClickHouse dialect drift, and bug fixes all land on our team. Budget roughly a small but recurring slice of an engineer's time, or accept the fork going stale.

Support

• No vendor, no active maintainer, no community. Internal escalation is the only path, which raises mean time to resolution for any query-generation bug to "however long it takes us to read the source."

Scaling

• The builder itself is not a throughput bottleneck — it produces strings, and cost is dominated by ClickHouse execution and transport.
• The real scaling constraint is ergonomics under complexity: as query requirements grow past 2017-era ClickHouse, engineers will drop to raw SQL, producing a mixed abstraction with no consistency guarantees and no central place to enforce limits, timeouts, or SETTINGS for resource governance.

Failure modes

• Composer resolution failure on framework upgrade (most likely, most disruptive — blocks the whole upgrade).
• Silent SQL injection via unescaped identifiers or values in dynamic filters.
• Unsupported syntax producing valid-looking but semantically wrong SQL (e.g., mis-rendered PREWHERE or GROUP BY ordering) — the worst class, because it fails quietly in analytics.
• PHP 8 runtime errors on rarely exercised code paths, discovered in production.

Ramp-up

• Low for engineers: the fluent API surface is small and familiar to anyone who has used Laravel's query builder.
• Higher for the team: because documentation is thin and the code is unmaintained, onboarding requires reading source. Pair this with an internal README and golden-SQL tests, or every new engineer re-derives the behavior independently.