Laravel Sense Laravel Package

Getting Started

This is a pre-1.0 package, and 0.6.1 is a bug-fix release rather than a feature release — so treat your first step as establishing a known-good baseline rather than learning new API surface.

• Require ^0.6.1 explicitly. If you are on Postgres (#26), Laravel 7 or 8 (#27), or you bind DateTime/Carbon values into your queries (#29), earlier 0.6.x releases have known-incorrect behaviour and there is no reason to start on them.
• Publish the package config (php artisan vendor:publish) and read it before touching code — the config file is the primary surface area for this package, and the defaults are aimed at local debugging, not production.
• Smoke-test with a single, obviously slow query in php artisan tinker or a throwaway route. You want to confirm three things work on your stack before wiring it into anything: the connection is detected (MySQL vs Postgres differ meaningfully here), the query is captured, and the explanation renders.
• First real use case: take one slow endpoint, run its queries through the package, and read the explanation output. That loop — slow query in, plan out — is the whole value proposition. Everything else is convenience.

Because 0.6.1 fixes rendering (#28) and binding serialisation (#29), compare output against EXPLAIN run directly in psql/mysql on your first few queries. If the rendered plan and the raw plan disagree, you are almost certainly on a pre-0.6.1 version.

Implementation Patterns

Keep it environment-scoped. Register or enable the package only in local/staging. The most common integration is a conditional in a service provider or a config flag driven by APP_ENV, so the package never loads in production.

The tinker/REPL loop is the primary workflow. For day-to-day use, developers rarely wire this into application code. They reproduce a slow path in tinker, run the query, and read the explanation. Optimise for that: keep a scratch file or tinker session with realistic bindings so you are not hand-typing parameters each time.

Use it as a before/after instrument for index changes. Add an index, re-run the same query, compare plans. This is where the package earns its place in a workflow — it turns "the page feels faster" into a visible plan diff. Keep the query and bindings fixed across the comparison, or the diff is meaningless.

Lean on the DateTime binding fix for real-world queries. Most non-trivial queries filter on timestamps. Prior to 0.6.1 the rendered SQL for DateTime/Carbon bindings was wrong, which meant plans were being generated against subtly different queries than the ones actually executing. If you have any existing explain output captured on 0.6.0 that involves date ranges, discard it and re-capture.

Postgres-specific integration. On Postgres, confirm the package is issuing EXPLAIN (or EXPLAIN ANALYZE) against the correct connection — applications with a read/write split will otherwise explain the wrong replica. If you use multiple connections, test the non-default one explicitly rather than assuming it is picked up.

Pair with your existing tooling rather than replacing it. This complements Telescope/Debugbar-style query logging, which tells you which queries ran and how long they took; this package tells you why they were slow. The natural pattern is: find the slow query in your logger, then paste it here.

In tests, assert on plans sparingly. Plan output is version- and data-dependent. If you assert anything, assert the query was captured and the explanation rendered without error — not the plan contents.

Gotchas and Tips

• Upgrade is the fix, not a workaround. If you are on Postgres, Laravel 7/8, or using date bindings, 0.6.1 is the supported floor. There is no config toggle that compensates for the pre-0.6.1 bugs in #26, #27, #28, #29.
• EXPLAIN ANALYZE executes the statement. On Postgres and MySQL, ANALYZE runs the query for real. Never point this at UPDATE/DELETE/INSERT ... SELECT outside a throwaway database, and be aware that a long-running SELECT will actually run to completion. If the package exposes an analyze flag, know its current setting before you paste in a write statement.
• Rendering != execution. The package renders a plan; it does not guarantee the rendered SQL is byte-identical to what the driver sent. That gap is exactly what #29 was about. When a plan looks wrong, verify the rendered SQL against your query log before blaming the database.
• Postgres EXPLAIN permissions and settings differ from MySQL. You may need elevated privileges for EXPLAIN ANALYZE, and plan shape is sensitive to work_mem, random_page_cost, and whether the planner uses generic or custom plans for prepared statements. Do not compare plans across machines with different settings.
• Small datasets produce misleading plans. On a dev database with a few hundred rows, the planner will choose sequential scans almost everywhere. Plans captured locally are frequently not the plans production will use — capture on a production-like dataset or a restored anonymised dump when the answer actually matters.
• Pre-1.0 means minor bumps can break you. Pin with ~0.6.1 or a lockfile and read release notes on every bump. The 0.x version signals the API is not yet stable, and 0.6.1's changelog is entirely fixes — expect behaviour changes in 0.7.
• Debugging checklist when nothing renders: confirm the package's service provider is registered for your environment, confirm the config was actually published (a cached config will mask edits — php artisan config:clear), confirm you are on the connection you think you are, and confirm the query has no bindings the package cannot serialise.