codebar-ag/phpstan

PHPStan

When to Apply

• After implementing or refactoring PHP code in app/** or tests/**.
• Before merging pull requests to ensure static analysis passes.
• When raising PHP or PHPStan levels or tightening type strictness.

When NOT to Apply

• Do not run as a blocker for non-PHP changes (pure docs, static assets only).
• Do not require full-project runs while debugging unrelated frontend-only issues.
• Do not update baseline as part of formatting-only or dependency-only changes unless analysis output changed.

Preconditions

• PHP, Composer dependencies, and PHPStan are installed.
• phpstan.neon exists at repo root and is used as the default project config.
• If phpstan.neon is missing, initialize config first; do not guess flags ad hoc:
  • vendor/bin/phpstan init
  • Commit generated config before enforcing this skill.
• If phpstan-baseline.neon exists, it is included intentionally and reviewed before merge.
• If baseline is expected but missing, generate once from current known debt, then review before commit:
  • vendor/bin/phpstan analyse --generate-baseline
• The working tree contains the relevant changes you want to analyze.

Process

1. Run PHPStan and Review Findings

• Run the default project scope from repo root:
  • vendor/bin/phpstan analyse
• Narrow scope only while iterating on a focused change:
  • vendor/bin/phpstan analyse app/ tests/
  • vendor/bin/phpstan analyse app/Services/Billing
• Capture and review all reported errors:
  • Identify missing or weak type hints.
  • Look for untyped signatures and mixed usage.
  • Note any @phpstan-ignore usage and whether it is justified.

2. Strengthen Types and Annotations

• Ensure all parameters, return types, and properties are typed wherever possible.
• Replace broad mixed types with more specific union types.
• Use array<string, mixed> or more precise shapes instead of bare array in PHPDoc.
• Add @throws annotations to methods that can throw exceptions.
• Use phpstan-assert, phpstan-param, and phpstan-return tags when generics or advanced shapes are needed.

3. Prefer Narrowing to Suppression

• Use runtime type narrowing (for example, assert(), instanceof) instead of suppressing errors.
• When suppression is unavoidable:
  • Limit it to the narrowest possible scope.
  • Add a clear justification comment.

4. Re-run and Baseline Check

• Re-run full vendor/bin/phpstan analyse after fixes.
• If baseline is used, ensure no new ignored errors were added accidentally.
• Keep baseline updates explicit and documented in the PR description.
• Review baseline diffs line-by-line:
  • New entries for edited files are not allowed unless a reviewer accepts a temporary exception.
  • Removed entries are preferred and should be called out.
  • Broad regex ignores must be replaced by narrower paths/messages.

5. Common Level 9 Errors and Direct Fixes

• Missing generic value types:
  • Error pattern: array has no value type specified.
  • Fix: add array<string, mixed> or specific shapes (array<int, InvoiceDto>).
• Unknown mixed member/method access:
  • Error pattern: Cannot call method ... on mixed.
  • Fix: narrow first with instanceof, assert(), or typed wrappers.
• Invalid nullable access:
  • Error pattern: Cannot call method ... on Type|null.
  • Fix: add null guard clause before access.
• Template/generic mismatch:
  • Error pattern: invalid @template, Collection generic count/type mismatch.
  • Fix: align declared template params with actual return/param usage.
• Unreachable branch or always-true/false checks:
  • Error pattern: strict comparison impossible/already guaranteed.
  • Fix: remove dead condition and simplify control flow.

Examples

// ✓ Specific types instead of mixed
public function process(Order $order): Invoice { ... }

// ✓ PHPDoc with typed arrays
/**
 * @return array<string, array<int, string|object>>
 */
public function rules(): array { ... }

// ✓ Union types instead of mixed
public function format(string|int|null $value): string { ... }

// ✓ Generics for collections
/**
 * @return Collection<int, Invoice>
 */
public function getInvoices(): Collection { ... }

// ✓ @throws annotation
/**
 * @throws InvoiceAlreadyPaidException
 */
public function markAsPaid(Invoice $invoice): void
{
    if ($invoice->isPaid()) {
        throw InvoiceAlreadyPaidException::for($invoice);
    }
    // ...
}

// ✓ Type narrowing with assert() instead of suppression
public function handle(mixed $model): void
{
    assert($model instanceof Invoice);
    $model->markAsPaid(); // PHPStan now knows it's an Invoice
}

// ✓ Justified suppression with comment
/** @phpstan-ignore-next-line Property accessed via magic method — documented in IDE helper */
$user->custom_attribute;

Checklists

Execution Checklist

• [ ] Ran vendor/bin/phpstan analyse from repo root.
• [ ] Used narrowed scope only for local iteration.
• [ ] Confirmed phpstan.neon exists (or initialized it before applying this skill).
• [ ] Confirmed baseline file existence is intentional (created once if required).
• [ ] Ensured all parameters, properties, and return types are typed where possible.
• [ ] Replaced bare mixed and array usages with more specific types or PHPDoc generics.
• [ ] Added @throws annotations to methods that can throw.
• [ ] Used type narrowing and assertions instead of broad suppressions.
• [ ] Any remaining @phpstan-ignore usages are justified with clear comments.
• [ ] Baseline diff was reviewed line-by-line; no silent new ignores for edited files.

Safety / Things to Avoid

• Using bare mixed when a more specific type is possible.
• Using bare array without a PHPDoc generic shape such as array<string, mixed>.
• Using @phpstan-ignore without an explanation of why it is necessary.
• Omitting @throws annotations on methods that throw.
• Leaving parameters, properties, or return types untyped.
• Relying on (int) or (string) casts as substitutes for proper type narrowing.
• Ignoring common Level 9 issues such as union narrowing gaps or invalid generic/template annotations.

References

• PHPStan Documentation
• PHPStan Rule Levels
• PHPStan Baseline
• resources/boost/skills/php/SKILL.md (type-first PHP conventions)