Laravel Query Inspector Laravel Package

Getting Started

Update the dependency to pick up 1.0.1:

composer update vendor/package

Look first at the package README section covering query builder support, then the changelog entry for 1.0.1. Check whether the package exposes a config file or service provider binding that controls the accepted query source.

The first practical use case is a read-only report or export where you want joins, aggregates, or selectRaw without hydrating Eloquent models. Build the query with Laravel’s query builder and hand it to the package:

use Illuminate\Support\Facades\DB;

$query = DB::table('orders')
    ->join('customers', 'customers.id', '=', 'orders.customer_id')
    ->select('customers.name', DB::raw('SUM(orders.total) as revenue'))
    ->where('orders.created_at', '>=', now()->subMonth())
    ->groupBy('customers.name');

$result = Package::for($query)->get();

If the package previously required an Eloquent model or array, 1.0.1 removes the need to wrap or convert those inputs for query-builder-based workflows.

Implementation Patterns

Prefer DB::table() for reporting paths. Query builder support is most useful when you do not need model events, accessors, casts, or relationships. Keep reporting queries in dedicated classes or services and pass the builder into the package at the last responsible moment.

Use Model::query()->getQuery() when you need Eloquent scopes but the package only accepts a query builder. This preserves global scopes and soft-delete constraints while still satisfying the package’s query-builder contract. Verify this in your version of the package before relying on it broadly.

Compose package filters around a base builder. A common workflow is:

$base = DB::table('invoices')->where('tenant_id', $tenantId);

$filtered = Package::for($base)
    ->apply($request->only(['status', 'date_from', 'date_to']))
    ->paginate(25);

Keep the base builder immutable where possible; clone it before handing it to the package if you need to reuse it for counts or exports.

Test with an in-memory SQLite connection. Query-builder paths are easy to exercise without factories or model setup. Seed a few rows with DB::table(...)->insert(...), then assert the package’s output. This also catches column ambiguity and binding issues early.

Integrate at the service boundary. If you expose the package through a controller, resolve the query builder in a form request or action class rather than in the controller. That keeps HTTP concerns separate from query construction and makes the new query-builder path reusable in jobs and commands.

Gotchas and Tips

• Query builder returns stdClass, not models. Downstream code that expects accessors, casts, relationships, or save() will break. Normalize results or keep model-dependent logic on the Eloquent path.
• Global scopes and soft deletes are not applied by DB::table(). Add whereNull('deleted_at') and tenant constraints manually, or use Model::query()->getQuery() when you need Eloquent’s global scope behavior.
• Qualify columns in joins. Query builder does not infer table prefixes. Use orders.status rather than status to avoid ambiguous-column errors.
• Watch bindings when the package clones or modifies the builder. If the package rewrites the query internally, raw expressions and bindings can drift. Dump ->toSql() and ->getBindings() before and after passing the builder when debugging.
• Pagination and aggregate methods differ between builders. Confirm that the package calls methods supported by Illuminate\Database\Query\Builder in your Laravel version. If you pass an Eloquent builder, check whether the package unwraps it correctly.
• Debug with DB::listen() and toSql(). The query builder path is less observable than model events. Log the final SQL and bindings in local development to catch missing constraints.
• Extension point: if the package exposes a resolver or factory, bind your own query-builder-aware implementation in a service provider. This is the cleanest place to add tenant scoping or default filters across all package usages.