Add Array Type Hints - Entities¶

Priority: 🟡 P2 - MEDIUM Status: Planning Related Analysis: phpstan-rector-analysis-overview.md

Problem Statement¶

~100 PHPStan errors in entity classes for missing array value types (subset of 294 total).

Current Issue¶

// ❌ Missing value type
public function toArray(): array
{
    return [
        'id' => $this->id,
        'name' => $this->name,
    ];
}

// ✅ With value type
/**
 * @return array<string, mixed>
 */
public function toArray(): array
{
    return [
        'id' => $this->id,
        'name' => $this->name,
    ];
}

Impact¶

Type Safety: PHPStan can't verify array contents
IDE Support: No autocomplete for array keys
Documentation: Unclear what arrays contain
Refactoring: Harder to change array structures safely

Scope¶

Focus on entity layer first (highest impact):

Entity classes in src/Entity/
Array return values
Array parameters
Array properties

Common Patterns in Entities¶

Pattern 1: toArray() Methods¶

/**
 * @return array<string, int|string|bool|null>
 */
public function toArray(): array

Pattern 2: Array Properties¶

/**
 * @var array<string, mixed>
 */
private array $metadata = [];

Pattern 3: Array Parameters¶

/**
 * @param array<string, mixed> $data
 */
public function fromArray(array $data): void

Implementation Plan¶

Step 1: Identify Entity Arrays¶

# Find all array types in entities
make phpstan 2>&1 | grep "missingType.iterableValue" | grep "Entity/" > /tmp/entity-arrays.txt

Step 2: Categorize by Pattern¶

toArray() methods
fromArray() methods
Metadata/options arrays
Configuration arrays
Other

Step 3: Apply Type Hints¶

Work file by file:

Read entity
Identify all array types
Determine appropriate type hint
Add PHPDoc
Run PHPStan to verify
Move to next file

Step 4: Use Rector Where Possible¶

Some can be automated, but many need manual analysis.

Type Hint Patterns¶

Specific Key Types¶

/**
 * @return array{id: int, name: string, active: bool}
 */

Use when array shape is fixed.

String Keys, Mixed Values¶

/**
 * @return array<string, mixed>
 */

Use when keys are strings but values vary.

Numeric Keys¶

/**
 * @return array<int, string>
 */

Use for lists.

Nested Arrays¶

/**
 * @return array<string, array<string, mixed>>
 */

Use for nested structures.

Success Criteria¶

All entity array types have value type hints
PHPStan errors reduced significantly
Better IDE autocomplete
Clear documentation of array structures

Risk Assessment¶

Low Risk:

PHPDoc only, no runtime changes
Easy to fix if wrong
Can be verified with PHPStan

Estimated Effort¶

~30 entity classes
~3-5 arrays per entity average
~5 min per array
Estimate: 8-12 hours

Dependencies¶

Should be done AFTER Doctrine Collection generics
Can be done in parallel with service/repository type hints

Notes¶

This is part of a larger effort to add array type hints across the codebase. Entities are prioritized because they're the foundation.

TODO:

Extract entity-specific array type errors
Create list of entities to update
Identify common patterns
Create type hint templates