Kit Soar Bundle Laravel Package

Technical Evaluation

Architecture fit. The headline claim and the artifact disagree, and that gap is the first thing a TPM must resolve. The description markets this as a "drop-in Laravel bundle" with "auto-discovered service providers" and "publishable config" — but the repository is a Symfony bundle (Bundle subclass, DI extension, compiler passes). Laravel's container cannot register it. There is no service provider, facade, or config/kit_soar.php to publish. What actually exists is a thin process wrapper that shells out to XiaoMi's soar Go binary, pipes SQL in, and parses CLI text out. The architectural question is therefore not "do we adopt this package" but "do we want soar in our toolchain, and are we willing to own ~200 lines of glue?" The wrapper is negligible; the binary is the asset.

Integration feasibility. Prototyping is genuinely cheap — a Laravel engineer can reproduce the bundle's behavior in a day using Laravel's Process facade. But two hard prerequisites gate any real use, and both are ops problems, not PHP problems: (1) the soar binary must be present in every environment the feature touches, delivered as a pinned, checksummed artifact since it is not installable via Composer; (2) the target MySQL instance must accept EXPLAIN connections with usable credentials. If either fails, no amount of wrapper quality saves the initiative.

Technical risk. High, and skews toward vendor and ownership risk rather than code risk:

• Adoption signal is effectively zero — 1 star, 0 dependents, score 0.005, no downstream validation, bus factor of one. A security/license review will likely flag it on adoption provenance alone.
• Upstream health is the real exposure. XiaoMi/soar itself has been dormant for years. Adopting it means inheriting unmaintained SQL parsing and MySQL-version assumptions — verify MySQL 8.x syntax support (CTEs, window functions) against your actual workload before committing.
• Supply chain. A prebuilt Go binary in the runtime path is an artifact you must pin, checksum, and vendor. No signature or provenance story exists here.
• Data handling. SQL text and, for EXPLAIN mode, DSNs/credentials cross into a subprocess. That is a new exfiltration-adjacent surface requiring explicit sign-off.
• Fragility. Output parsing is against human-oriented CLI text with no test coverage on your side; a binary bump can silently break parsing and produce false "clean" passes.

Key questions. What is the concrete outcome — index advisory in CI, SQL linting for developers, or runtime query rewriting? (Only the first two are plausible; the third should be rejected on principle.) Which MySQL/MariaDB versions and dialects must be covered, and does a pinned binary demonstrably handle them? Does compliance permit third-party binaries in production containers? Is there a named engineer willing to own a hard fork? What is the measurable success criterion for a spike — a blocked merge, an added index, a fixed slow query — and by when?

Recommendation: do not adopt as a Composer dependency. If the capability is wanted, wrap the soar binary directly in a small, owned Artisan command — or evaluate PHP-native parsers (greenlion/php-sql-parser, phpmyadmin/sql-parser) for the linting subset, which removes the binary entirely.

Integration Approach

Stack fit. Poor as-is, adequate after a thin adapter. Port the bundle's ~100 lines of invocation/config logic behind a Laravel SoarServiceProvider that binds a config object (binary path, timeout, DSN env vars) and a single SoarRunner service. Treat the repo as reference implementation, not a dependency — this also removes the Symfony version-constraint problem entirely.

Migration path. Three tiers, ascending commitment:

1. CI-only (recommended). Install soar in the CI image; add a pipeline stage that lints changed queries or runs report-type checks against a scratch schema. Zero production footprint, no Composer dependency, no credential exposure beyond CI's ephemeral DB. This captures roughly 80% of the value for roughly 20% of the ownership cost.
2. Artisan command (if developers need local access). php artisan db:soar-advise wrapping the Process facade, gated to local/testing. About a day including tests.
3. Fork the bundle. Justified only if you need its specific parsing/output shaping. Budget ongoing maintenance nobody else will provide.

Compatibility. If you fork, verify PHP version support (older Symfony bundles often cap below 8.2/8.3), transitive Symfony component constraints, and the binary's OS/arch matrix — linux-amd64 for CI/prod, darwin-arm64 for Apple Silicon laptops. Pin the binary digest in the Dockerfile or CI image and treat upgrades as reviewed changes. If you go the port route, none of the PHP-side constraints apply.

Sequencing.

1. Spike gate: run soar against a representative slice of your real slow-query log and measure signal quality. This gate decides whether the capability is worth anything — do not skip it.
2. If positive, implement tier 1 (CI stage) in report-only mode for 2–4 weeks.
3. Evaluate noise: if advisors are actionable, promote to advisory gating on new/changed queries only.
4. Only then consider in-app integration, and default to tier 2.
5. Reassess annually against upstream health; document the exit (drop the stage) up front.

Operational Impact

Maintenance. Ownership is the headline cost. Assume no maintainer capacity upstream and that you own every fix. Minimum viable hygiene: pinned binary, checksum verification, a smoke test asserting the binary runs and emits parseable output, and a documented upgrade procedure. If you fork, add CHANGELOG discipline and a CODEOWNERS entry.

Support. No vendor, no SLA, no security response channel. Upstream issue tracker is the only external channel, with the expectation of no reply. Internal expertise is your only support tier — document the two or three people who understand the tool, because bus factor is real on both the package and your usage of it.

Scaling. Subprocess-per-invocation: a Go cold start plus a MySQL connection for EXPLAIN, on the order of 10²–10³ ms. Fine for CI and CLI; not acceptable in a request path (per-request latency, process fan-out under concurrency, connection-pool pressure). If anyone proposes runtime rewriting in middleware, that is the failure mode to push back on. For batch use, cap concurrency, reuse a single DSN, and expect to shard large query logs.

Failure modes.

• Binary missing or wrong arch → hard failure; must be caught at boot, not at first use.
• Binary version drift → silently malformed output; mitigated by pinning plus smoke test.
• EXPLAIN unreachable (network policy, credentials, read-replica vs primary) → mode-specific failure; needs a distinct error path and a documented skip-vs-fail policy.
• Timeout/hang on pathological SQL → wrap with an explicit timeout and kill the process.
• Unsupported SQL dialect → false negatives, the most dangerous class because it looks like a clean pass.
• Credential leakage via process arguments → pass DSNs through env, never argv; redact in logs.

Ramp-up. Low for a competent Laravel engineer — a day to read the wrapper, a day to build the adapter, a day for CI wiring. The non-obvious cost is domain judgment: interpreting soar's index recommendations requires someone who can distinguish a genuine missing index from a bad suggestion on a write-heavy table. Budget reviewer time for the first month of report-only output, or the team will either ignore the tool or apply harmful indexes.

Bottom line for the roadmap. Frame this as a capability evaluation (SQL advisory in CI), not a dependency adoption. The Laravel-vs-Symfony mismatch, 1-star/0-dependent profile, and dormant upstream make the package a reference implementation at best. Fund a two-week, time-boxed spike that shells out to soar directly; if the signal is good, own a ~200-line Artisan command and keep the dependency off your manifest entirely.