Skip to content

PHPStan and Rector Analysis Overview

Date: 2025-11-08 Analysis Type: Type Safety (PHPStan) and Code Modernization (Rector) Status: Planning Phase - No Code Changes Yet

Executive Summary

PHPStan analysis found 635 errors across the codebase, with Rector suggesting 53 files for modernization. Most critically, there are undefined method calls that will cause runtime errors in production.

Critical Finding ⚠️

RUNTIME BUG DETECTED: Multiple calls to RoasterCrawlConfig::getDefaultInstruction() which doesn't exist.

  • Severity: CRITICAL - Will cause fatal errors
  • Location: Strategy factory classes
  • Action Required: Immediate fix (see fix-missing-default-instruction-method.md)

PHPStan Error Statistics

Total Errors: 635

Error Breakdown by Category

Category Count % Priority
Missing iterable value types 294 46% P2 (Medium)
Function not found (deploy.php) 115 18% P3 (Ignore)
Missing generics 69 11% P1 (High)
Argument type mismatches 37 6% P2 (Medium)
Method not found 24 4% P0 (Critical)
Uninitialized properties 18 3% P1 (High)
Missing parameter types 17 3% P2 (Medium)
Return type issues 10 2% P2 (Medium)
Other issues 51 8% P2-P3

Priority Classification

🔴 P0: Critical (Must Fix Immediately)

Undefined Methods - 24 errors

  • Runtime fatal errors waiting to happen
  • RoasterCrawlConfig::getDefaultInstruction() - called but doesn't exist
  • Other method calls that may fail at runtime
  • Plan: fix-missing-default-instruction-method.md, fix-undefined-methods.md

🟠 P1: High Priority (Fix This Week)

Missing Generic Types - 69 errors

  • Doctrine Collections without generic types
  • Example: Collection → Collection<int, Market>
  • Affects all entity relationships
  • Quick Win: Rector can auto-fix most
  • Plan: add-doctrine-collection-generics.md

Uninitialized Properties - 18 errors

  • Properties declared but not initialized
  • Can cause null reference errors
  • Requires business logic understanding
  • Plan: fix-uninitialized-properties.md

🟡 P2: Medium Priority (Fix This Month)

Missing Array Value Types - 294 errors

  • Arrays without value type hints
  • Example: array → array<string, CoffeeBean>
  • Doesn't cause bugs but hurts maintainability
  • Plan: add-array-type-hints-*.md (3 separate plans)

Argument Type Mismatches - 37 errors

  • Type mismatches in function calls
  • Requires investigation
  • Plan: Include in type safety cleanup

Missing Parameter/Return Types - 27 errors

  • Functions missing type declarations
  • Plan: Rector can help automate

🟢 P3: Low Priority (Can Defer/Ignore)

deploy.php errors - 115 errors

  • Deployment script using Deployer library
  • Not part of application runtime
  • Action: Exclude from PHPStan
  • Plan: exclude-deploy-from-phpstan.md

Rector Analysis

Total Files Suggested: 53 files with modernization opportunities

Safe to Apply Automatically ✅

  1. AddArrowFunctionReturnTypeRector

    • Add return types to arrow functions
    • Safe, improves type safety

  2. ClosureReturnTypeRector

    • Add return types to closures
    • Safe, widely beneficial

  3. CompleteReturnDocblockFromToManyRector

    • Add @return Collection<int, Entity> to entity getters
    • Safe, fixes PHPStan errors

  4. AddAnnotationToRepositoryRector

    • Add repository type annotations
    • Safe, improves IDE support

  5. Namespace Import Optimizations

    • Convert \DateTimeImmutable → DateTimeImmutable
    • Safe, code style improvement

Requires Manual Review ⚠️

  1. RemoveUnusedPublicMethodParameterRector

    • DANGEROUS: Could break public APIs
    • Could break interface implementations
    • Action: Review each case manually

  2. TypedPropertyFromCreateMockAssignRector

    • Safe but verify tests still pass
    • Test-only changes

Known Issues ❌

  • config/services.php - Rector internal error
    • Cannot process this file
    • Need to investigate or exclude

Action Plan

Phase 1: Critical Bugs (Week 1)

  1. fix-missing-default-instruction-method.md - P0

    • Fix undefined getDefaultInstruction() method
    • Affects 2-3 strategy factory files
    • Estimated effort: 0.5 day

  2. fix-undefined-methods.md - P0

    • Fix remaining 24 undefined method errors
    • Each may be a real bug
    • Estimated effort: 2-3 days

  3. fix-uninitialized-properties.md - P1

    • Fix 18 uninitialized property errors
    • Prevents null reference errors
    • Estimated effort: 1-2 days

Phase 2: Type Safety Foundation (Week 2)

  1. add-doctrine-collection-generics.md - P1

    • Add generic types to all Doctrine Collections
    • Quick Win: Rector automates most
    • Estimated effort: 1 day

  2. apply-rector-safe-rules.md - P1

    • Apply safe Rector modernizations
    • Return types, closures, annotations
    • Estimated effort: 0.5 day + testing

Phase 3: Array Type Hints (Weeks 3-4)

  1. add-array-type-hints-entities.md - P2

    • Entity classes (highest impact)
    • Estimated effort: 2 days

  2. add-array-type-hints-services.md - P2

    • Service layer
    • Estimated effort: 3 days

  3. add-array-type-hints-repositories.md - P2

    • Repository classes
    • Estimated effort: 1 day

Phase 4: Cleanup (Week 5)

  1. fix-return-type-mismatches.md - P2

    • Investigate 10 return type issues
    • May uncover logic bugs
    • Estimated effort: 1 day

  2. exclude-deploy-from-phpstan.md - P3

    • Clean up PHPStan configuration
    • Estimated effort: 0.5 hour

Metrics & Goals

Current State

  • PHPStan Level: 7
  • Total Errors: 635
  • Critical Errors: ~26 (methods + properties)
  • Type Coverage: ~40%

1-Month Target

  • PHPStan Level: 7 (maintain)
  • Total Errors: <200 (68% reduction)
  • Critical Errors: 0
  • Type Coverage: ~70%
  • All Doctrine Collections: Generic types ✓
  • All Entities: Fully typed ✓

3-Month Target

  • PHPStan Level: 8
  • Total Errors: <50 (92% reduction)
  • Type Coverage: ~90%
  • Full array type coverage

Automation Strategy

High Automation Potential

  • Collection generics: ~80% (Rector)
  • Return types: ~90% (Rector)
  • Closure types: ~95% (Rector)
  • Namespace imports: 100% (Rector)

Manual Required

  • Undefined methods: 100% manual
  • Uninitialized properties: 100% manual
  • Return type mismatches: 100% manual

Semi-Automated

  • Array type hints: Rector + manual review

Risk Assessment

High Risk Items

  1. Undefined method calls - production runtime errors
  2. Uninitialized properties - null reference bugs
  3. Removing unused parameters - could break APIs

Low Risk Items

  1. Adding type hints - backward compatible
  2. Adding docblocks - documentation only
  3. Namespace imports - cosmetic

Dependencies

Blocks Other Work

  • fix-missing-default-instruction-method.md - blocks strategy refactoring
  • fix-undefined-methods.md - blocks any affected features

Complements Other Plans

  • Works well with domain entity refactoring (simplify-domain-entities.md)
  • Supports DTO refactoring (refactor-dto-parameter-lists.md)

From QA Analysis:

Type Safety Plans (This Analysis):

Notes

  • Type safety work is separate from complexity refactoring - can be done in parallel
  • Start with P0 items immediately - these are production bugs
  • Use Rector for quick wins - significant improvements with minimal effort
  • Coordinate with entity refactoring - type safety improvements will help that work
  • Consider CI/CD integration - Run PHPStan in pipeline to prevent regression