Logs Laravel Package

Getting Started

litermi/logs is a low-signal package (no stars, no dependents, no published docs surfaced), so treat the first hour as source audit rather than integration.

1. Install and pin:

   composer require litermi/logs
   

   Because there are no dependents and no score, require an explicit version constraint and commit composer.lock. Avoid dev-main in anything you intend to deploy.

2. Read the package before wiring it up. In order:

   • vendor/litermi/logs/composer.json — PHP and illuminate/* constraints are your first compatibility gate on Laravel 10/11/12.
   • vendor/litermi/logs/src/ — find the service provider, then look for DB::listen(...), a Log facade call, or a custom channel/monolog handler. That one file tells you whether this is a query logger (listens to the connection) or a routine logger (a wrapper you call explicitly).
   • config/ inside the package — if a config file ships, publish it: php artisan vendor:publish --provider="Litermi\Logs\...ServiceProvider". If nothing is publishable, the package is likely zero-config and hardcoded to a channel, which is a strong signal about how much control you'll have.

3. First use case — verify behavior against a single query before trusting it anywhere:

   // routes/web.php or a throwaway artisan command
   DB::enableQueryLog();
   \App\Models\User::where('id', 1)->first();
   // inspect storage/logs for whatever the package emitted
   

   Confirm three things in that one run: (a) the destination file/channel, (b) the format of bindings and timings, (c) whether it logs on every connection or only the default one.

Only after that should you decide whether it replaces or supplements Laravel's native DB::listen / DB::enableQueryLog().

Implementation Patterns

Wrap the routine, not the framework. A package that logs "routines and SQL queries" is almost always meant to bracket a unit of work. Put it around scheduled commands, imports, and report jobs so you get a correlated block of queries:

// app/Console/Commands/ImportOrders.php
public function handle()
{
    // package entry point — check src/ for the actual class/method name;
    // commonly something like Logs::start('import-orders') / Logs::end()
    $runId = uniqid('import-', true);

    OrderImporter::run();

    // then correlate: any query rows should carry $runId
}

If the package has no start/stop API, the pragmatic pattern is to layer it under your own logger: keep a RoutineLogger service of your own that writes a header/footer and lets the package dump queries in between.

Scope it to non-production or to explicit channels. The highest-value integration is usually a dedicated channel plus a config toggle:

// config/logging.php
'channels' => [
    'sql_audit' => [
        'driver' => 'daily',
        'path' => storage_path('logs/sql-audit.log'),
        'level' => 'debug',
        'days' => 7,
    ],
],

Then ensure the package's internal Log::channel(...) or handler target matches. If it hardcodes single/stack, override via a published config or wrap the provider — see Gotchas.

Use it as a query-budget instrument in tests. The most defensible day-to-day use for a query logger is N+1 detection. If the package exposes a way to read back collected queries, assert on the count in a feature test; if it doesn't, keep the package for humans and use Laravel's DB::enableQueryLog() + assertDatabaseCount for assertions. Don't build CI gates on an unmaintained package's output format.

Integration tip — middleware for request-scoped correlation. Bind a request ID in middleware, then have your routine logs include it. This turns a flat query dump into something you can grep per request:

// app/Http/Middleware/CorrelationId.php
public function handle($request, Closure $next)
{
    $id = $request->header('X-Request-Id', (string) Str::uuid());
    Context::add('request_id', $id); // Laravel 11 context
    return $next($request);
}

Queue jobs. Query logging across queued workers produces interleaved noise by default. Either run a dedicated worker for jobs you want traced, or inject the correlation ID into the job payload and have the job re-add it to context at handle(). Also verify whether the package logs in php artisan queue:work at all — some query loggers only register on HTTP.

Gotchas and Tips

• Nothing is verified. With 0 stars, 0 dependents, and no score, assume no security review, no Laravel-version matrix, and no upgrade path. Read every line of src/ before it touches production, and check for eval, extract, dynamic class instantiation, or outbound HTTP.

• SQL bindings are a data-leak vector. A query logger writing to storage/logs will happily record emails, tokens, and card fragments in bound parameters. If the package has no redaction config, add a masking layer or restrict it to non-production. This is the single most common way these packages go wrong.

• Volume and performance. DB::listen inside a loop is cheap; the Log::info call per query is not. On a page issuing 400 queries you will get 400 file writes. Use a buffered/daily channel and raise the level to debug, or gate the whole thing behind APP_DEBUG.

• Config caching. If you publish a config, run php artisan config:clear after edits — the classic "I changed the channel and nothing happened" is a stale bootstrap/cache/config.php. Same for queue:restart if workers hold an old provider.

• Hardcoded channels are the main extension point problem. If the service provider does Log::info(...) unconditionally, you cannot redirect it via config. Options, in order of preference: publish the config; override the binding in your own provider (register yours after the package provider, or use $this->app->extend(...)); as a last resort, fork. Never patch vendor/ — it disappears on composer update.

• Version constraints matter more than usual. Check composer.json for a laravel/framework or illuminate/support requirement. A package with no dependents often declares ^8.0 and silently installs on Laravel 11 via loose constraints, where DB::listen internals and Log handling changed. If you're on 11/12, test explicitly.

• Debugging checklist when nothing appears: (1) is the provider auto-discovered — check vendor/composer/installed.json for the extra.laravel.providers key; (2) is APP_DEBUG/the config toggle off; (3) is LOG_CHANNEL pointing somewhere you're not watching; (4) does it only hook the mysql driver while you're on sqlite in tests; (5) php artisan about confirms the provider is actually loaded.

• Have an exit plan. DB::listen in AppServiceProvider::boot() gives you query logging and timing in ~10 lines with full control over formatting and redaction:

  DB::listen(function ($q) {
      Log::channel('sql_audit')->debug($q->sql, [
          'time_ms' => $q->time,
          'bindings' => $q->bindings,
      ]);
  });
  

  Given the package's maturity signals, build your routine logging on top of this abstraction from day one so swapping litermi/logs out is a one-file change rather than a refactor.