phpstan-fixer

What this skill does

# PHPStan Error Fixer
Fix PHPStan static analysis errors through proper type annotations, PHPDocs, and 
code improvements. This skill teaches agents how to resolve errors without 
suppressing them, respecting the project's configured strictness level.

## Core Principles

1. **Never suppress errors as first resort** — Fix the root cause with proper
   types and annotations
2. **Respect user configuration** — Never modify `phpstan.neon` settings
   (level, paths, parameters)
3. **No silent ignoring** — Never add `ignoreErrors` to config without explicit
   user approval
4. **Context-aware fixes** — Understand the project type (Laravel, Symfony,
   vanilla PHP) before proposing solutions
5. **Ask before ignoring** — If a legitimate ignore is needed, explain why and
   get user approval first
6. **Don't fix third-party code** — Never modify files in `vendor/`. Use stub
   files instead to override wrong types

## Workflow

### Step 1: Understand the Project Context

Before fixing errors, identify the project type:

```bash
# Check for Laravel
grep laravel/framework composer.json

# Check for Symfony
grep symfony/symfony composer.json

# Check for PHPStan extensions
grep phpstan composer.json

# Read PHPStan config
cat phpstan.neon

# Check project guidelines
cat AGENTS.md
```

**Key information to extract:**
- PHPStan level (0-10, or max)
- Installed PHPStan extensions (larastan, phpstan-strict-rules, etc.)
- Framework-specific helpers (Laravel IDE Helper, Symfony plugin)
- Project-specific type conventions

### Step 2: Analyze the Error

PHPStan errors have this structure:

```text
------ ----------------------------------------------
Line   /path/to/File.php
------ ----------------------------------------------
42     Parameter $user of method foo() has invalid
       type App\User.
       💡 Identifier: parameter.type
------ ----------------------------------------------
```

**Extract:**
1. **Error identifier** (e.g., `parameter.type`, `missingType.return`)
2. **Error location** (file, line number)
3. **Context** (what's the code trying to do?)

### Step 3: Apply the Right Fix

Use the error identifier to determine the fix strategy:

### Step 4: Verify the Fix

After applying fixes, run PHPStan again to confirm:

```bash
vendor/bin/phpstan analyse
```

**Important:**
- If new errors appear, the fix may have been incorrect. Re-analyze the error and try a different approach.
- If the same error persists, the fix wasn't applied correctly. Double-check the code.
- If errors are resolved, mark the fix as successful and move to the next error.

---

## Common Error Fixes

### Type-Related Errors

#### `missingType.parameter` — Missing parameter type

**Error:**
```text
Parameter $name has no type specified.
```

**Fix — Add native type:**
```php
// Before
function greet($name) {
    return "Hello, $name";
}

// After
function greet(string $name): string {
    return "Hello, $name";
}
```

**Fix — Use PHPDoc for complex types:**
```php
// Before
function processUsers($users) { ... }

// After
/**
 * @param array<int, User> $users
 */
function processUsers(array $users): void { ... }
```

---

#### `missingType.return` — Missing return type

**Error:**
```text
Method foo() has no return type specified.
```

**Fix — Add native return type:**
```php
// Before
public function getUser() {
    return $this->user;
}

// After
public function getUser(): User {
    return $this->user;
}
```

**Fix — Use PHPDoc for union/intersection types:**
```php
// Before
public function findUser($id) { ... }

// After
/**
 * @return User|null
 */
public function findUser(int $id): ?User { ... }
```

---

#### `argument.type` — Wrong argument type

**Error:**
```text
Parameter #1 $id of method find() expects int, string given.
```

**Fix — Cast the argument:**
```php
// Before
$user = $repository->find($request->input('id'));

// After
$user = $repository->find((int) $request->input('id'));
```

**Fix — Narrow the type earlier:**
```php
// Better approach
$id = $request->integer('id'); // Laravel helper
$user = $repository->find($id);
```

---

#### `return.type` — Wrong return type

**Error:**
```text
Method foo() should return User but returns User|null.
```

**Fix — Adjust return type:**
```php
// Before
public function getUser(): User {
    return $this->user ?? null;
}

// After
public function getUser(): ?User {
    return $this->user ?? null;
}
```

**Fix — Ensure non-null with assertion:**
```php
public function getUser(): User {
    assert($this->user !== null);
    return $this->user;
}
```

---

### Property Errors

#### `property.notFound` — Undefined property access

**Error:**
```text
Access to an undefined property User::$name.
```

**Fix — Add property declaration:**
```php
class User {
    private string $name;
    
    public function __construct(string $name) {
        $this->name = $name;
    }
}
```

**Fix — Document magic property:**
```php
/**
 * @property string $name
 */
class User {
    public function __get($key) { ... }
}
```

**Fix (Laravel) — Use IDE Helper:**
```bash
# Generate PHPDocs for Eloquent models
php artisan ide-helper:models
```

---

#### `property.onlyWritten` — Property written but never read

**Error:**
```text
Property User::$name is never read, only written.
```

**Fix — Remove unused property or add getter:**
```php
// If truly unused, remove it
// If needed, add usage:
public function getName(): string {
    return $this->name;
}
```

---

### Method Errors

#### `method.notFound` — Undefined method call

**Error:**
```text
Call to an undefined method App\User::getFullName().
```

**Fix — Add method:**
```php
class User {
    public function getFullName(): string {
        return $this->first_name . ' ' . $this->last_name;
    }
}
```

**Fix — Document magic method:**
```php
/**
 * @method string getFullName()
 */
class User {
    public function __call($method, $args) { ... }
}
```

**Fix (Laravel) — Add to `@mixin` for query builders:**
```php
/**
 * @mixin \Illuminate\Database\Eloquent\Builder
 */
class User extends Model { ... }
```

---

### Array/Offset Errors

#### `offsetAccess.notFound` — Undefined array offset

**Error:**
```text
Offset 'email' does not exist on array.
```

**Fix — Use array shape PHPDoc:**
```php
/**
 * @param array{email: string, name: string} $data
 */
function createUser(array $data): void {
    echo $data['email']; // PHPStan knows this exists
}
```

**Fix — Add existence check:**
```php
if (isset($data['email'])) {
    echo $data['email'];
}
```

**Fix — Use null coalescing:**
```php
$email = $data['email'] ?? '[email protected]';
```

---

### Generics Errors

#### `missingType.generics` — Missing generic type

**Error:**
```text
Class Collection has @template T but does not specify it.
```

**Fix — Specify generic type in PHPDoc:**
```php
// Before
/** @var Collection $users */
$users = User::all();

// After
/** @var Collection<int, User> $users */
$users = User::all();
```

**Fix (Laravel) — Use IDE Helper stubs for collections.**

---

### Dead Code Errors

#### `deadCode.unreachable` — Unreachable code

**Error:**
```text
Unreachable statement - code above always terminates.
```

**Fix — Remove dead code:**
```php
// Before
function foo() {
    return true;
    echo "This never runs"; // Error
}

// After
function foo() {
    return true;
}
```

---

#### `identical.alwaysTrue` / `identical.alwaysFalse` — Condition is always true/false

**Error:**
```text
Strict comparison using === between int and string will always evaluate to false.
```

**Fix — Remove useless condition or fix type:**
```php
// Before
if ($id === '123') { ... } // $id is int

// After
if ($id === 123) { ... }
```

---

## Framework-Specific Fixes

### Laravel

**Install Larastan for Laravel-aware analysis:**
```bash
composer require --dev larastan/larastan
```

**Check `phpstan.neon` includes Larastan** (ask user to add if missing):
```yaml
includes:
    - vendor/larastan/larastan/extension.neon
```

**Common Laravel