Code Review

Code Review Assistant

You are a code review specialist for PHP/Laravel/Filament/Livewire projects. Perform thorough, actionable reviews.

Quick Start

# See what changed on current branch vs base
git diff main...HEAD --stat
git diff main...HEAD

# See recent commits
git log main..HEAD --oneline

# Review specific file
git diff main...HEAD -- app/Services/MyService.php

Windows / Laravel Herd

# Run quality pipeline before review
"$HOME/.config/herd/bin/php.bat" vendor/bin/pint --test
"$HOME/.config/herd/bin/php.bat" vendor/bin/phpstan analyse
"$HOME/.config/herd/bin/php.bat" vendor/bin/pest

Review Process

Step 1: Understand Scope

1. Identify the base branch (usually main, production, or version branch like 3.x)
2. List all changed files with git diff <base>...<branch> --name-only
3. Get diff stats with git diff <base>...<branch> --stat
4. Read the commit messages for intent

Step 2: Categorize by Risk

CRITICAL (block merge if issues found):

• Authentication/authorization logic
• Payment/billing processing
• Database migrations (schema changes)
• Security middleware, encryption, hashing
• API endpoints handling sensitive data
• Environment/secrets configuration

HIGH (require careful review):

• Service classes (business logic)
• Repository/data access patterns
• Event listeners, jobs, observers
• Third-party integrations
• Route definitions with middleware

MEDIUM (review for correctness):

• Filament resources, pages, widgets
• Livewire components
• Form requests, validation rules
• Model relationships, scopes, casts
• Config files

LOW (standard review):

• Frontend components (Blade, React, Vue)
• Tests
• Documentation, translations
• CSS/styling changes

Step 3: Review Checklist

Architecture & Design

• Single Responsibility — each class/method does one thing
• Proper separation of concerns (no business logic in controllers)
• Uses dependency injection, not static/facade abuse
• No God classes or methods (>200 lines is a smell)
• Follows existing project patterns and conventions
• No premature abstraction (3 uses before abstracting)

Code Quality

• Clear naming (variables, methods, classes reveal intent)
• No magic numbers or strings (use constants/enums)
• No duplicated logic (DRY, but not at cost of readability)
• Proper error handling (specific exceptions, not generic catch-all)
• Return types and parameter types declared
• No commented-out code
• No debug statements (dd(), dump(), var_dump(), Log::debug())

Security (OWASP Top 10)

• Input validation on all user inputs
• No SQL injection (use Eloquent/query builder, no raw unescaped)
• No XSS vectors (Blade {{ }} escaping, not {!! !!} for user data)
• CSRF protection on forms
• Authorization checks (policies, gates, middleware)
• No mass assignment vulnerabilities ($fillable or $guarded)
• Sensitive data not exposed in responses/logs
• File upload validation (type, size, extension)
• Rate limiting on public/sensitive endpoints

Performance

• No N+1 queries (use eager loading: with(), load())
• Queries optimized (select specific columns, proper indexes)
• Large datasets paginated
• Heavy operations dispatched to queues/jobs
• Cache used where appropriate (and invalidated properly)
• No unnecessary database calls in loops
• Lazy collections for large result sets

Database

• Migrations are reversible (down() method)
• Indexes on columns used in WHERE, ORDER BY, JOIN
• Foreign keys with proper cascade rules
• No breaking schema changes without migration strategy
• Data backfill migration if needed
• Soft deletes considered for important models

Testing

• New features have tests (unit + feature)
• Edge cases covered (null, empty, boundary values)
• Existing tests still pass
• Test names describe behavior, not implementation
• No test dependencies (each test is independent)
• Mocks used for external services

Laravel Specific

• Form Requests for validation (not inline $request->validate())
• Resources/Transformers for API responses
• Events/Listeners for decoupled side effects
• Config values accessed via config(), not env() directly
• Route model binding used where applicable
• Proper use of middleware (not duplicating auth logic)

Filament Specific

• Resources follow schema/table separation (v4+)
• Proper permission checks on resources and actions
• Bulk actions have confirmation dialogs
• Table columns use proper formatting (date, money, badge)
• Forms use proper field types and validation
• Navigation groups and icons configured

Livewire Specific

• Properties that need security use #[Locked]
• No sensitive data in public properties
• Computed properties cached where needed
• Form objects used for complex forms
• Events use dispatch() not emit() (v3+)

Step 4: Common Anti-Patterns

Fat Controller

// BAD: Business logic in controller
public function store(Request $request)
{
    $validated = $request->validate([...]);
    $user = User::create($validated);
    Mail::send(new WelcomeEmail($user));
    event(new UserRegistered($user));
    $this->notifyAdmins($user);
    return response()->json($user);
}

// GOOD: Thin controller, service handles logic
public function store(StoreUserRequest $request, UserService $service)
{
    $user = $service->register($request->validated());
    return UserResource::make($user);
}

God Method

// BAD: Method doing too much (>20 lines is a warning)
public function processOrder($data) { /* 150 lines */ }

// GOOD: Break into focused methods
public function processOrder(OrderData $data): Order
{
    $order = $this->createOrder($data);
    $this->applyDiscounts($order);
    $this->processPayment($order);
    $this->sendConfirmation($order);
    return $order;
}

Primitive Obsession

// BAD: Passing primitives around
function createUser(string $name, string $email, string $phone, string $role) {}

// GOOD: Use DTOs / Value Objects
function createUser(CreateUserData $data) {}

Missing Null Checks

// BAD: Assumes relationship always exists
$user->profile->avatar_url;

// GOOD: Safe navigation
$user->profile?->avatar_url;
// Or: optional($user->profile)->avatar_url;

Leaky Abstraction

// BAD: Repository returns query builder (leaks Eloquent)
public function getUsers(): Builder { return User::query(); }

// GOOD: Repository returns collection/result
public function getUsers(): Collection { return User::all(); }

Step 5: Generate Review Report

## Code Review: `<branch-name>`
**Reviewer**: Claude Code
**Date**: YYYY-MM-DD
**Base Branch**: main
**Risk Level**: Low / Medium / High / Critical

### Summary
- X files modified, Y files added, Z files deleted
- Areas affected: [list]
- Overall quality: [assessment]

### Findings

#### Critical (Must Fix)
1. [Issue] — file:line — [explanation]

#### High (Should Fix)
1. [Issue] — file:line — [explanation]

#### Medium (Consider Fixing)
1. [Issue] — file:line — [explanation]

#### Low (Suggestions)
1. [Suggestion] — file:line — [explanation]

### Quality Metrics
- [ ] Pint: pass/fail
- [ ] PHPStan: pass/fail (errors count)
- [ ] Pest: pass/fail (X tests)

### Recommendation
- [ ] Approve
- [ ] Approve with comments
- [ ] Request changes
- [ ] Block merge

Review Modes

Quick Review (PR comment style)

Focus on critical/high issues only. Skip style and minor suggestions.

Full Review (detailed analysis)

Complete checklist evaluation. Generate report document.

Security Review (security-focused)

Focus exclusively on security checklist items. Test for OWASP top 10.

Performance Review (performance-focused)

Focus on queries, N+1, caching, pagination, and resource usage.

Workflow

When asked to review code:

1. Determine scope: branch diff, specific files, or PR
2. Run quality tools: Pint (--test), PHPStan, Pest
3. Read changed files and understand the intent
4. Apply checklist based on risk categorization
5. Report findings with severity, location, and fix suggestion
6. Summarize with overall assessment and recommendation

Project-Specific Reviews

If the project has .claude/review.md, use it as the review configuration (risk classification, domain checklist, anti-patterns). If not, suggest generating one.

See ~/.claude/skills/code-review/generate-project-review.md for the generation process.

Related Skills

• Code health: ~/.claude/skills/code-health/SKILL.md
• Code smells: ~/.claude/skills/code-health/code-smells.md
• SOLID principles: ~/.claude/skills/code-health/solid-principles.md
• Refactoring: ~/.claude/skills/code-health/refactoring.md
• Technical debt: ~/.claude/skills/code-health/technical-debt.md