Getting Started

Minimal Steps

Installation:

composer require fitztrev/query-tracer

Add the service provider to config/app.php:

'providers' => [
    Fitztrev\QueryTracer\Providers\QueryTracerServiceProvider::class,
],

First Use Case: Enable debugging mode in .env:
```
APP_DEBUG=true
```
Run your Laravel application and trigger database queries. The package will automatically inject backtrace information into WHERE clauses for all queries.
View Results: Check your database logs or query results directly in the database. The injected WHERE clauses will show the file, line, and method where the query originated.

Implementation Patterns

Basic Workflow

Enable/Disable Globally: The package is enabled by default when APP_DEBUG=true. Override this behavior by publishing the config:
```
php artisan vendor:publish --provider="Fitztrev\QueryTracer\Providers\QueryTracerServiceProvider"
```
Then configure config/query-tracer.php:
```
'enabled' => env('QUERY_TRACER_ENABLED', false),
```
Model-Specific Control: Add enableQueryTracer() to a model to enable/disable tracing dynamically:
```
public function enableQueryTracer()
{
    return app()->environment('local');
}
```
Query Filtering: Use the tracer:filter command to exclude specific queries or models from tracing:
```
php artisan tracer:filter add "select * from users"
```

Integration Tips

Pair with Debugbar/Clockwork: Use alongside Laravel Debugbar or Clockwork for richer query visualization. QueryTracer adds backtrace context to these tools.

Logging Queries: Log traced queries to a file or external service for long-term debugging:

// In a service provider or event listener
QueryTracer::trace(function ($query, $backtrace) {
    Log::debug("Query traced: {$query->toSql()}", $backtrace);
});

Conditional Tracing: Enable tracing only for specific environments or user roles:

public function enableQueryTracer()
{
    return Auth::check() && Auth::user()->isAdmin();
}

Gotchas and Tips

Pitfalls

Performance Overhead: QueryTracer modifies queries by adding WHERE clauses, which can impact performance in production. Always disable it in non-debug environments:
```
APP_DEBUG=false
QUERY_TRACER_ENABLED=false
```
Query Plan Changes: The injected WHERE clauses may alter query execution plans. Test thoroughly in staging before relying on traced queries for optimization.
Model Events: Tracing may not work as expected for queries triggered by model events (e.g., booted, saved). Explicitly enable tracing in event handlers if needed:
```
protected static function booted()
{
    static::addGlobalScope(new QueryTracerScope());
}
```
Raw Queries: QueryTracer only traces Eloquent queries and query builder instances. Raw queries (e.g., DB::select()) are unaffected. Use DB::enableQueryLog() for raw query tracing.

Debugging

Missing Backtraces: If backtraces are empty, ensure:
- APP_DEBUG=true.
- The query is not cached (e.g., via remember() or Redis).
- The query is not a raw statement or stored procedure.
Filter Conflicts: If filters are not applied, clear the filter cache:
```
php artisan tracer:filter clear
```
Config Overrides: Verify config values in config/query-tracer.php are not being overridden by environment variables or other config files.

Extension Points

Custom Backtrace Format: Override the backtrace format by extending the Fitztrev\QueryTracer\QueryTracer class and binding your version in the service provider:
```
$this->app->bind('query-tracer', function ($app) {
    return new CustomQueryTracer($app);
});
```

Query Modification: Extend the Fitztrev\QueryTracer\QueryTracer class to modify how queries are altered:

public function modifyQuery(Builder $query, array $backtrace)
{
    // Custom logic here
    return parent::modifyQuery($query, $backtrace);
}

Event Listeners: Listen for query-traced events to react to traced queries:

Event::listen('query-traced', function ($query, $backtrace) {
    // Handle traced query
});

Query Tracer Laravel Package