# Code Review

> Perform comprehensive code reviews on PHP/Laravel/Filament projects. Analyze code quality, security, performance, and maintainability.

- Skill: `joaopaulolndev/code-review` (Agent Skill)
- Install (CLI): `npx skillmds@latest add joaopaulolndev/code-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/joaopaulolndev/code-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: joaopaulolndev (https://skillmd.com/u/joaopaulolndev)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/joaopaulolndev/code-review

---


# Code Review Assistant

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

## Quick Start

```bash
# 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

```bash
# 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
```php
// 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
```php
// 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
```php
// 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
```php
// BAD: Assumes relationship always exists
$user->profile->avatar_url;

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

#### Leaky Abstraction
```php
// 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

```markdown
## 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`