Druid Bundle Laravel Package

Technical Evaluation

Architecture fit

The first thing a TPM must flag: this is not a Laravel package. thomask/druid-bundle is a Symfony bundle (TmkDruidBundle), built for the Symfony 2.x bundle/DI-container model — DependencyInjection/, Resources/config/services.yml, TmkDruidBundle.php convention. It will not autodiscover or service-provide into a Laravel application without a hand-written wrapper. If the assumption behind this evaluation is "drop into a Laravel codebase," the architecture fit is zero without adaptation, and moderate only if the target is a legacy Symfony 2.8/3.x service.

Functionally, the package is a thin client around Apache Druid's HTTP query API (broker endpoint, JSON native queries) plus some console-command scaffolding for Druid-related operations. That is inherently a small amount of logic: build a JSON query body, POST it, decode the response. The architectural surface is narrow, which is the one point in its favour — nothing here is deeply entangled with application domain code.

Integration feasibility

Feasible only in one of two shapes:

• Target is Symfony 2.x/3.x — the bundle can be installed via Composer, registered in AppKernel, and configured with a broker host/port. Low effort, but pins you to an EOL framework.
• Target is Laravel or modern PHP — you are not integrating the package; you are reading it as a reference implementation and writing ~200–400 lines of your own client using Guzzle/Laravel HTTP. This is the realistic path and is genuinely cheap.

Either way, expect to write the Druid query DSL yourself; the bundle predates most of Druid's current SQL layer and later native query features.

Technical risk

High, and concentrated in provenance rather than complexity:

• Unmaintained. The project is a decade-class artifact from the Symfony 2 era. Its transitive dependencies (old Guzzle, old Symfony components) will conflict with any modern PHP 8 stack and carry known CVEs.
• Zero adoption signal. 0 stars, 0 dependents, score 0. There is no production evidence, no issue history to mine, no community to escalate to. Every defect is yours.
• API drift. Druid's query surface (SQL endpoint, query/sql, newer ingestion specs, security/auth layers added in later versions) has moved substantially; the bundle's request shapes are unlikely to cover authentication, TLS, or modern broker routing.
• Licensing/abandonment uncertainty. Verify the licence file and that the author has not archived it; a hard fork is the likely end state.

Key questions

1. Is the actual target runtime Symfony 2.x legacy, or a current Laravel/PHP 8+ app? (This single answer changes the recommendation from "wrap it" to "don't.")
2. What Druid version is in the cluster, and does it require auth/TLS that the bundle's client cannot express?
3. Is the required functionality query-only, or do you also need ingestion task submission and supervisor management?
4. Who owns the fork when a CVE lands in a transitive dependency?
5. Is there an existing internal Druid client already, making this duplicative?

Integration Approach

Stack fit

Poor as-is. The bundle assumes Symfony's kernel, DI container, and config tree. In Laravel you would keep the bundle out of composer.json entirely and instead vendor the ~3 classes that matter (query builder / client / response decoder) into app/Services/Druid/, exposed through a DruidServiceProvider and a config/druid.php. In a modern Symfony app, the same treatment applies but with a first-party bundle or a plain service — a Symfony 2 bundle is not the right unit for Symfony 6/7.

Migration path

Recommended sequence:

1. Spike (1–2 days). Stand up a Druid broker (or point at staging), reproduce one native JSON query using a hand-rolled Guzzle call. Do not install the bundle.
2. Extract, don't depend. Read the bundle's query-building code as a specification. Reimplement behind a narrow internal interface (DruidClient::query(array $nativeQuery): array) so the transport is swappable.
3. Add the operational concerns the bundle lacks: timeouts, retries with backoff, connection pooling, structured error mapping (Druid returns HTTP 200 with an error body in some failure modes — handle it), and observability hooks.
4. If a Symfony 2 target is genuinely required, install the bundle directly and accept dependency freeze; treat that application as legacy and isolate it from new work.

Compatibility

Composer resolution is the likely first blocker: the bundle's constraints will conflict with modern symfony/*, guzzlehttp/guzzle, and PSR standards. PHP 8 typed properties and return types are not present, so static analysis will be noisy. If you must include it, plan on replace/inline aliasing or a maintained fork under your own vendor namespace.

Sequencing

Land the internal Druid client interface before any dashboard or analytics feature depends on it. Analytics consumers should never see Druid's JSON shapes directly; put a typed query object in between.

Operational Impact

Maintenance

Effectively 100% internal ownership from day one. There is no upstream to patch, no release cadence, no maintainer response. Budget a small but permanent maintenance line: dependency bumps on the fork, Druid API compatibility checks on every Druid upgrade, and PHP version migrations. The consolation is that the code volume you actually depend on is small enough that "maintenance" means rewriting a few hundred lines every couple of years rather than nursing a framework.

Support

No vendor, no community, no documentation beyond the README and the source. On-call engineers will be reading PHP to understand query failures. Mitigate by writing the runbook and the query examples yourself as part of integration — do not defer this.

Scaling

The package is not the scaling bottleneck; the Druid cluster is. The client is stateless HTTP, so horizontal scaling of the PHP tier is straightforward provided you replace the bundle's default client with one that has connection reuse, sane timeouts, and circuit-breaking. Risks to watch:

• Unbounded result sets. Thin clients invite SELECT *-style native queries that pull millions of rows into PHP memory. Enforce row limits and thresholds at the client layer.
• Synchronous query latency. Druid queries can take seconds to tens of seconds. Any user-facing path must be async (queued job, cached result), not a blocking request.
• No caching layer. Add one; repeated identical dashboard queries against a broker are the common cost driver.

Failure modes

• Broker unavailable or slow → PHP request pile-up. Needs timeout + circuit breaker + degraded-mode UI.
• HTTP 200 with an error payload → silent empty datasets if you only check status codes. Parse the body.
• Query rejected due to schema drift (dimension renamed, datasource reloaded) → hard failures at read time; validate against a known schema contract.
• Dependency conflict at deploy time → install-time failure only, but it can block unrelated releases if the package is in the shared root composer.json.
• Abandonware supply-chain risk → an unpatched transitive dependency becomes an audit finding; pin and audit.

Ramp-up

Low for anyone comfortable with HTTP clients and Druid's native query JSON; the bundle's concepts are not deep. Expect half a day to understand what the package does — it is small — and two to four days for an engineer to produce a production-grade replacement client with tests, retries, and observability. The harder ramp is Druid itself: datasource modelling, granularity, and query tuning are where the real learning cost sits, and this package teaches none of it.

Bottom line for the TPM: treat thomask/druid-bundle as reference material, not a dependency. The zero score, zero dependents, and Symfony 2-era provenance make it unsuitable for a Laravel or modern PHP product. The functional gap it fills is small enough that a maintained in-house client is cheaper than the ownership risk of adopting it.