Audit — Laravel Smells

When to use

• The user wants an audit of an existing Laravel application — find facade abuse, missing FormRequests, sync queues in production, leaked .env secrets, or N+1 queries.
• The user wants to find N+1 query problems, eager-loading gaps, or a sync queue driver running in production across an existing Laravel codebase.
• The user wants to check a Laravel app for controllers that validate inline instead of using FormRequests, or for secrets and credentials leaked into a committed .env file.

When NOT to use

• Do not use this skill on a non-Laravel PHP app (Symfony, Bitrix, plain PHP); its checks target Laravel facades, FormRequests, Eloquent, and the queue config that only exist there.
• Do not run this audit when the user asks to implement one Laravel feature or fix one specific bug; make the minimal targeted change instead of scanning the whole app.

Core guidance

• Emit structured FINDINGS, not prose — Report each Laravel smell as a FINDING with id (AUD-LARAVEL-{nnn}), title, evidence (path:line), domain, severity, impact, effort (1-5), confidence (0.5-1.0), roi_score, remediation, and tags — never a free-form paragraph.
• Never emit a finding without evidence — Every finding MUST carry concrete evidence as path:line — a controller action, a config key, an .env entry, or an Eloquent loop you actually read; no location, no finding.
• Rank findings by ROI score — Compute roi_score = (impact * severity * confidence) / effort for every finding and sort the report descending, so leaked secrets and hot-path N+1 rise above cosmetic facade cleanups.

Decision Engine

Walk this section before choosing an implementation path.

For the smell you found, does it expose data or credentials (security), degrade
production behavior (reliability/performance), or is it purely a maintainability concern?

├── Pure maintainability concern: → Lower severity — facade abuse in domain code or business logic in controllers that hurts
testability but does not break production. Emit a finding with modest impact; remediation
is inject dependencies / move logic into services, ranked below security and reliability.

├── Degrades production behavior: → High impact — a sync queue driver in production or an N+1 query on a hot endpoint.
Emit a finding; remediation is switch to a real queue driver / add eager loading, scored
by request volume and user-facing latency.

└── Exposes data or credentials: → Highest severity — a leaked .env secret or a controller taking unvalidated input straight
from the request. Emit a security finding; remediation is rotate the secret / add a
FormRequest, and this outranks pure maintainability items at equal effort.

Full engine: references/decision-engine.md — Decision Tree, Priority Matrix, Decision Table.

Workflows

Workflow: Emit Report

Progress:
- [ ] Build one finding per confirmed smell with `id` (`AUD-LARAVEL-{nnn}`), `title`, `evidence`,
`domain`, `severity`, `impact`, `effort`, `confidence`, `remediation`, and `tags`, redacting
any secret values
- [ ] Compute `roi_score = (impact * severity * confidence) / effort` for each finding and sort
the report descending so leaked secrets and hot-path N+1 lead
- [ ] For each finding, write remediation that names the fix and links to the Laravel
implementation skill that performs it (queues, eloquent-relationships,
service-container), then hand the ranked report off as input to scoped fix tasks

1. Build one finding per confirmed smell with id (AUD-LARAVEL-{nnn}), title, evidence, domain, severity, impact, effort, confidence, remediation, and tags, redacting any secret values.
   • Verify: Every finding has all required fields populated, a path:line in evidence, and no live secrets echoed.
2. Compute roi_score = (impact * severity * confidence) / effort for each finding and sort the report descending so leaked secrets and hot-path N+1 lead.
   • Verify: The report is ordered by roi_score descending with the score shown on each finding.
3. For each finding, write remediation that names the fix and links to the Laravel implementation skill that performs it (queues, eloquent-relationships, service-container), then hand the ranked report off as input to scoped fix tasks.
   • Verify: Each remediation names a next step; queue and N+1 items reference the matching implementation skill.

Workflow: Scan Laravel

Progress:
- [ ] Grep controllers for `$request->all()` / inline validation, domain classes for facade
calls, config and .env for `QUEUE_CONNECTION` and committed secrets, and Eloquent loops
for per-row relation access
- [ ] Open each candidate and confirm the smell — read the controller, check the production
config value, verify the secret is real (not a placeholder), and measure the N+1 with the
query log — recording the exact path:line
- [ ] Walk the Decision Engine to classify each confirmed smell as security, reliability, or
maintainability, then set severity and impact from that class and estimate effort and
confidence

1. Grep controllers for $request->all() / inline validation, domain classes for facade calls, config and .env for QUEUE_CONNECTION and committed secrets, and Eloquent loops for per-row relation access.
   • Verify: You have candidate locations for missing FormRequests, facade abuse, sync queues, secrets, and N+1.
2. Open each candidate and confirm the smell — read the controller, check the production config value, verify the secret is real (not a placeholder), and measure the N+1 with the query log — recording the exact path:line.
   • Verify: Every retained candidate has a confirmed path:line and, for N+1, a measured query count.
3. Walk the Decision Engine to classify each confirmed smell as security, reliability, or maintainability, then set severity and impact from that class and estimate effort and confidence.
   • Verify: Each candidate has severity, impact, effort (1-5) and confidence (0.5-1.0) grounded in its evidence.

Best practices

• Assess queue, cache, session, and debug settings against the production config and environment, not the local .env.example
• Confirm a suspected N+1 by observing the query count — Laravel Debugbar, Telescope, or DB::enableQueryLog() — rather than assuming a loop over a relation is always N+1; some relations are already eager-loaded upstream or resolved once
• In each finding's remediation, point to the implementation skill that performs the fix — the queues skill for sync-in-prod, the eloquent-relationships skill for N+1, the service-container skill for facade injection — so the reader knows exactly how to act

Anti-patterns

See references/anti-patterns.md.

Debugging

1. Flagging .env.example placeholders as leaks — The template file is meant to be committed; only real values that grant access are actual leaks. Fix: Confirm the file is a real committed .env (not .env.example) and that the value is a working credential before raising a secret-leak finding.
2. Flagging idiomatic facade use as abuse — Facade abuse is about global state leaking into domain logic, not the framework's intended HTTP and CLI glue. Fix: Scope facade-abuse findings to domain and service classes where injection would improve testability; leave idiomatic glue-layer usage alone or note it at low severity.
3. Reporting local sync queue as a prod issue — The finding measures production risk, so the deployed config is what matters, not a developer's machine. Fix: Verify the production environment or deployment config before flagging sync-in-prod; if production uses a real driver, drop the finding or downgrade it to an informational note.

Performance notes

• Confirm N+1 with the query log, not by eye — Confirm a suspected N+1 by observing the query count — Laravel Debugbar, Telescope, or DB::enableQueryLog() — rather than assuming a loop over a relation is always N+1; some relations are already eager-loaded upstream or resolved once.

Production checklist

• Every finding carries concrete path:line evidence pointing at code or config that was actually read.
• Queue, cache, session, and debug findings are assessed against the deployed production config, not local defaults.
• The pass produces findings and remediation guidance only; it does not apply fixes or edit the app as a side effect.
• Each finding's remediation names a concrete next step and, where one exists, the Laravel implementation skill that performs it.
• The report lists findings sorted descending by roi_score with impact, severity, effort, and confidence shown.
• Any committed or hard-coded secret is raised as a high-severity finding whose remediation includes rotation, not just removal.

Version notes

• preventLazyLoading available from Laravel 8 (PHP >=7.4) — Model::preventLazyLoading() for surfacing N+1 in non-production has been available since Laravel 8 and works across the 9.x–12.x range this audit targets; on older apps rely on the query log or Telescope instead.

Security

• Prioritise input validation and secret exposure — Treat missing FormRequests and leaked secrets as the security core of the audit: unvalidated request input is an injection and mass-assignment vector, and a committed credential is an immediate breach. Cite the file:line, redact secret values, and always recommend rotation for exposed credentials, never mere deletion.

Testing

• Activation and decision behavior are verified in eval/scenarios/audit/laravel.yaml.

Additional resources

• references/anti-patterns.md
• references/core.md
• references/decision-engine.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Related: audit/project-analysis, laravel/eloquent-relationships, laravel/queues

Skill contract

Produces: audit.laravel-findings
Requires: repo.laravel-app
Risk: medium · Confidence: 0.9