Laravel Eloquent Guard Laravel Package

Getting Started

This is a small, low-adoption package (21 stars, no dependents), so treat the README and source as the source of truth before wiring it into anything important. The happy path is short:

composer require maxis/laravel-eloquent-guard

Laravel's package discovery should register the service provider automatically. Then publish and inspect the config:

php artisan vendor:publish --provider="Maxiz88\\EloquentGuard\\EloquentGuardServiceProvider"

Check config/eloquent-guard.php (or whatever the published filename is) for the enable flag, slow-query threshold, and N+1 detection toggle. Enable it in local and staging first — not production — and drive one slow page or one feature test through it.

Where to look first:

1. The package README for the exact config keys and output channel.
2. vendor/maxis/laravel-eloquent-guard/src/ — confirm how it hooks into the query event and where it writes findings.
3. Your config/logging.php — most lightweight monitors report through a log channel, so make sure the channel it targets actually exists.

First use case: open a page you suspect is query-heavy, then tail the log. If N+1 detection works, you should see grouped/repeated query signatures or a warning naming the offending model/relation. That single loop — hit page, read finding, add with() — is the core value.

Implementation Patterns

Environment-scoped activation. Keep it on in local, staging, and CI; off (or heavily sampled) in production. Runtime query listeners add overhead per query, and a monitor that fires on every request in production can generate more noise than signal.

// config/eloquent-guard.php (shape will vary — verify against README)
'enabled' => env('ELOQUENT_GUARD_ENABLED', app()->environment(['local', 'staging'])),
'slow_query_threshold_ms' => env('ELOQUENT_GUARD_SLOW_MS', 200),
'detect_n_plus_one' => true,

CI as a regression gate. The highest-leverage pattern for a package like this is running it during feature tests. If it exposes a throw/exception mode, enable that in phpunit.xml so a newly introduced N+1 fails the build instead of quietly shipping:

<env name="ELOQUENT_GUARD_ENABLED" value="true"/>
<env name="ELOQUENT_GUARD_THROW" value="true"/>

If it only logs, wrap your test assertions around the log or add a small custom assertion in your base TestCase.

Pair with a profiler, don't replace one. Use this as the always-on tripwire and Telescope/Debugbar/Blackfire for drill-down when it fires. The guard tells you that a request has an N+1; the profiler tells you which line and how to fix it.

Threshold tuning per environment. Staging on slower hardware will trip slow-query warnings that local won't. Set the threshold from an env var and override it in staging/CI rather than hardcoding. Keep N+1 detection aggressive (it's structural) and slow-query thresholds conservative (they're hardware-dependent).

Exclusion list for known-noisy queries. Health checks, session writes, migration runs, and queue polling produce repetitive queries that can look like N+1. Whatever ignore/except mechanism the package offers, populate it early — otherwise the first week of output is mostly false positives.

Refactor workflow. When you touch a controller or resource, run the relevant endpoint with the guard on and diff the query count before/after. It's a cheap way to prove an eager-loading change actually removed queries rather than just moving them.

Gotchas and Tips

• Audit before trusting. With 21 stars and zero dependents, read the source for how it hooks in (query listener vs. middleware vs. Eloquent events), what it does on failure, and whether it swallows exceptions. Pin the version in composer.json.
• State leakage in long-running processes. Queue workers, Horizon, and Octane reuse the process across jobs/requests. If the package accumulates query history on a singleton without resetting, N+1 detection will report cross-request false positives. Verify there's a per-request/per-job reset, or disable it under Octane/workers.
• Double instrumentation. Running alongside Telescope, Debugbar, or Laravel's own DB::listen means multiple listeners per query. If you see duplicated findings or unexpected slowdowns, disable the others while diagnosing.
• Config caching. After publishing or editing the config, run php artisan config:clear (or config:cache in deployed environments). A stale cached config is the usual reason "the enable flag isn't working."
• Log volume. A single bad page can emit hundreds of findings. Route to a dedicated channel with rotation, or the default log will bury everything else. Consider sampling or deduplicating by query signature.
• N+1 heuristics are heuristics. Intentional loops (batch inserts, per-item lookups against a cache miss) will trip detection. Read each finding before "fixing" it; a whitelist beats rewriting correct code.
• Slow-query detection is not a profiler. It tells you a query was slow, not why. Follow up with EXPLAIN, index checks, and a real profiler. Don't treat a clean guard report as proof of performance.
• Test isolation. If the guard throws in CI, it can fail unrelated tests that hit fixtures with repetitive queries. Scope it to the suites where you want the gate, or configure a higher threshold for the test environment.
• Extension points to check for: custom log channel/reporter binding, an ignore-list contract, and any published config for model/connection exclusions. If those don't exist, you'll be editing vendor code — a good reason to keep this as an advisory tool rather than a hard dependency.
• Version constraints. Confirm the package supports your Laravel and PHP versions in its composer.json before adopting; small packages often lag behind major framework releases.