Getting Started

itul/larabuilder is a small, undocumented utility package intended to help you inspect Laravel query builders while debugging — it wraps the standard Illuminate\Database\Eloquent\Builder (and typically the underlying query builder) so you can introspect the SQL, bindings, and execution context of a query without manually wiring up DB::listen or toSql()/getBindings() everywhere.

Because the package lives on a private-style Bitbucket remote (bmooreitul/larabuilder), with no Packagist presence, zero dependents, and no README, treat this as an internal package, not a community dependency. The realistic path to "getting started" is:

Confirm the source is reachable. Add the VCS repository to composer.json explicitly, since it will not resolve from Packagist:
```
{
  "repositories": [
    { "type": "vcs", "url": "https://bitbucket.org/bmooreitul/larabuilder.git" }
  ],
  "require-dev": {
    "itul/larabuilder": "dev-main"
  }
}
```
You will likely need Bitbucket credentials (app password or SSH key) configured, otherwise Composer will fail with a 404/403 rather than a version error.
Look in src/ first. With no docs, the fastest orientation is:
- composer.json → autoload.psr-4 tells you the root namespace and where classes live.
- The service provider (if present) → tells you whether anything is auto-registered or config is published.
- Any class whose name ends in Builder → that is the thing you actually use.
Check whether a service provider is auto-discovered. If composer.json has an extra.laravel.providers entry, php artisan vendor:publish --provider="..." will expose any config file; if not, you may need to register it manually in config/app.php.

First use case: drop it into an artisan tinker session against a model you're debugging and dump the builder state rather than chasing a full integration:

// tinker
$q = \App\Models\Order::where('status', 'paid')->whereBetween('created_at', [$from, $to]);
// whatever the package exposes — try class_exists / get_class_methods to discover
dump(get_class_methods(get_class($q)));

The single most important first step is to decide whether this package is still maintained for your Laravel version. If the code targets Laravel 5.x/6.x style Builder internals, it will likely break on Laravel 9+/10+ where the query builder's property visibility and method signatures have shifted. Run a smoke test on a dev branch before letting it anywhere near production code paths.

Implementation Patterns

Since the package is a debugging aid rather than a framework component, useful patterns cluster around isolating it from production and using it as a diagnostic layer rather than an architectural dependency.

Dev-only dependency with a guard

Keep it in require-dev and never let it into a shipped artifact. If the package hooks into the container or registers a listener, guard the registration:

// AppServiceProvider::register()
if ($this->app->environment('local') && class_exists(\Itul\LaraBuilder\ServiceProvider::class)) {
    $this->app->register(\Itul\LaraBuilder\ServiceProvider::class);
}

This pattern protects you when a colleague runs composer install --no-dev on a staging box and the class silently disappears.

Wrapping a query you're debugging

The typical workflow with a builder-debugging package is: capture the builder, inspect the SQL and bindings, then either run or discard it.

$query = Order::query()
    ->where('status', 'paid')
    ->whereHas('customer', fn ($q) => $q->where('vip', true));

// Inspect without executing
[$sql, $bindings] = [$query->toSql(), $query->getBindings()];
// Interpolated form is usually what the package surfaces for you

If the package exposes an interpolation helper (common in these micro-libraries), use it to get a copy-pasteable SQL string — then paste it into your DB client of choice. This is the highest-value pattern: it turns "why is this returning nothing?" into a directly executable query.

Pairing with `DB::listen` for the surrounding context

The builder alone does not tell you when the query ran or how long it took. Combine it with the framework listener so you get both the statement and the runtime behaviour:

DB::listen(function ($q) {
    if ($q->time > 100) {
        logger()->warning('Slow query', [
            'sql' => $q->sql,
            'bindings' => $q->bindings,
            'ms' => $q->time,
        ]);
    }
});

Use the package to build/refine the query, and the listener to catch it in the wild. This split keeps the debugging tool out of your hot path.

Scoped debugging helper

If you find yourself dumping builders often, wrap the discovery in your own tiny helper so the package is swappable:

if (! function_exists('debug_sql')) {
    function debug_sql($builder): string
    {
        $sql = $builder->toSql();
        foreach ($builder->getBindings() as $binding) {
            $value = is_numeric($binding) ? $binding : "'" . addslashes($binding) . "'";
            $sql = preg_replace('/\?/', $value, $sql, 1);
        }
        return $sql;
    }
}

This is the extension point worth building: it means if itul/larabuilder turns out to be unusable or abandoned, you have not coupled your debugging workflow to it.

Use it during test-driven query building

When writing a feature test that asserts a query shape, build the query outside the test, dump the interpolated SQL once to confirm it matches expectations, then assert on results rather than SQL strings in the committed test. Never assert against raw SQL — it couples tests to the query builder version.

Gotchas and Tips

Distribution and availability. Zero stars and zero dependents on a Bitbucket repo is a strong signal this is a personal/internal artifact. Do not expect Packagist version constraints (^1.0) to resolve; pin to a branch (dev-main, dev-master) or better, a commit hash in composer.json so builds are reproducible:

"itul/larabuilder": "dev-main#a1b2c3d4"

No documentation means no compat guarantee. There is no README, no changelog, no issue tracker you can rely on. Before adopting, read composer.json for the laravel/framework constraint (or absence of one) and check the source for calls to query-builder internals that are known to have changed across major versions — $builder->getQuery()->bindings, $query->wheres, and toSql() interpolation all behave differently on Laravel 9+/10+.

Version drift in query builder internals. Laravel moved to Illuminate\Database\Query\Builder with stricter typing and added Expression values for raw bindings. Any hand-rolled preg_replace interpolation will misbehave with:

Named bindings (:foo) vs positional (?)
DateTimeInterface bindings (need ->format('Y-m-d H:i:s'))
Raw expressions that contain ? inside literal strings

Always prefer toSql() + getBindings() and interpolate yourself, or accept that the package's output may be lossy.

Environment leakage. If the package registers a service provider globally, its debug output (which may dd()/dump()/write to log) can fire in production or, worse, in a queue worker where the output is swallowed. Confirm there is an enabled config flag or wrap registration in an environment check as shown above. Search the source for dd(, dump(, var_dump(, and error_log( before merging.

Autoload and namespace discovery. With no docs, the namespace is guessable from PSR-4 but the public entry point is not. Use composer dump-autoload -o and php -r "require 'vendor/autoload.php'; print_r(get_declared_classes());" filtered by the package namespace to enumerate what you actually got. get_class_methods() on any Builder-suffixed class is faster than reading unannotated source.

Do not extend the package's builder in models. If the package provides a custom builder that models should newQuery() through, resist wiring it into Model::newEloquentBuilder() — it couples your domain models to a debugging tool. Keep the package at the call site (debug_sql($query)), not at the model base class.

Extension point. The only clean extension point is your own wrapper function (above). If the package is useful enough to keep, fork it into your org's monorepo (or a packages/ path repository) so you own the Laravel-version compatibility and can drop the dd()s. Given the zero-dependency, single-repo nature, this is low cost and removes the Bitbucket-credential-availability risk from your build pipeline entirely.

Debugging the debugger. If nothing appears to happen after install, the three usual causes are: (1) the service provider was never registered because auto-discovery isn't configured; (2) you're calling the helper on a non-builder (e.g. a Collection or a Model instance); (3) output is being buffered by a queue/artisan context — run the same snippet in tinker to confirm the code path works before blaming the package.

Larabuilder Laravel Package