phpdocbock @return how to signal returned array structure in docbloc. exaple: public…
- User
phpdocbock @return how to signal returned array structure in docbloc.
exaple:
public function calculateSimInventoryTotals(): array { return [ 'count' => $simCollection->count(), 'price' => $simCollection->sum('price'), ]; } Assistant
In PHPDoc, you can document the structure of a returned array in several ways. Here are the most common approaches:
1. Array Shape Notation (Modern PHPDoc)
/** * Calculate SIM inventory totals * * @return array{count: int, price: float} */ public function calculateSimInventoryTotals(): array { return [ 'count' => $simCollection->count(), 'price' => $simCollection->sum('price'), ]; }2. Descriptive Text
/** * Calculate SIM inventory totals * * @return array Array with 'count' (int) and 'price' (float) keys */ public function calculateSimInventoryTotals(): array { return [ 'count' => $simCollection->count(), 'price' => $simCollection->sum('price'), ]; }3. Multi-line Format with Details
/** * Calculate SIM inventory totals * * @return array{ * count: int, * price: float * } */ public function calculateSimInventoryTotals(): array { return [ 'count' => $simCollection->count(), 'price' => $simCollection->sum('price'), ]; }4. Psalm/PHPStan Specific (for static analysis tools)
/** * Calculate SIM inventory totals * * @return array<string, int|float> * @psalm-return array{count: int, price: float} * @phpstan-return array{count: int, price: float} */ public function calculateSimInventoryTotals(): array { return [ 'count' => $simCollection->count(), 'price' => $simCollection->sum('price'), ]; }5. Detailed Documentation
/** * Calculate SIM inventory totals * * @return array<string, mixed> An associative array containing: * - count (int): The total number of SIM cards * - price (float): The sum of all SIM card prices */ public function calculateSimInventoryTotals(): array { return [ 'count' => $simCollection->count(), 'price' => $simCollection->sum('price'), ]; }The array shape notation (
array{count: int, price: float}) is the most modern and recommended approach as it's:- Supported by most modern IDEs (PHPStorm, VS Code with extensions)
- Understood by static analysis tools (Psalm, PHPStan)
- Provides type information for each array key
- Enables better autocompletion and type checking
Choose the format based on your team's conventions and the tools you're using in your project.
- User
array shape noration
Assistant
Here's a comprehensive guide to array shape notation in PHPDoc:
Basic Syntax
/** * @return array{key1: type1, key2: type2} */Examples
Simple Array Shape
/** * @return array{count: int, price: float} */ public function calculateSimInventoryTotals(): array { return [ 'count' => $simCollection->count(), 'price' => $simCollection->sum('price'), ]; }Optional Keys (with
?)/** * @return array{name: string, email: string, phone?: string} */ public function getUserData(): array { return [ 'name' => 'John Doe', 'email' => 'john@example.com', // 'phone' is optional ]; }Nested Array Shapes
/** * @return array{ * user: array{id: int, name: string}, * stats: array{total: int, active: int} * } */ public function getUserWithStats(): array { return [ 'user' => ['id' => 1, 'name' => 'John'], 'stats' => ['total' => 100, 'active' => 75] ]; }Mixed Types
/** * @return array{ * id: int, * name: string, * active: bool, * metadata: mixed, * tags: string[] * } */ public function getProduct(): array { return [ 'id' => 123, 'name' => 'Product Name', 'active' => true, 'metadata' => ['various' => 'data'], 'tags' => ['tag1', 'tag2'] ]; }With Numeric Keys
/** * @return array{0: string, 1: int, name: string} */ public function getMixedArray(): array { return [ 0 => 'first', 1 => 42, 'name' => 'John' ]; }Complex Nested Structure
/** * @return array{ * success: bool, * data: array{ * items: array<int, array{id: int, name: string, price: float}>, * pagination: array{page: int, total: int, perPage: int} * }, * errors?: string[] * } */ public function getApiResponse(): array { return [ 'success' => true, 'data' => [ 'items' => [ ['id' => 1, 'name' => 'Item 1', 'price' => 10.99], ['id' => 2, 'name' => 'Item 2', 'price' => 20.50] ], 'pagination' => [ 'page' => 1, 'total' => 100, 'perPage' => 10 ] ] ]; }For Parameters
/** * @param array{limit?: int, offset?: int, sort?: string} $options * @return array{count: int, items: array} */ public function getItems(array $options = []): array { // Implementation }Union Types in Array Shape
/** * @return array{ * status: 'active'|'inactive'|'pending', * value: int|float, * data: array|null * } */ public function getStatus(): array { return [ 'status' => 'active', 'value' => 42.5, 'data' => null ]; }Important Notes
- IDE Support: Most modern IDEs (PHPStorm 2020.3+, VS Code with PHP extensions) support array shape notation
- Static Analysis: Tools like Psalm and PHPStan fully support this notation
- Key Names: Keys must be valid PHP identifiers or integers
- Optional Keys: Use
?after the type to indicate optional keys - Backwards Compatibility: Older tools might not understand this notation, so you may need fallback documentation
Multi-line Format (for readability)
/** * @return array{ * count: int, * price: float, * currency: string, * lastUpdated: \DateTime * } */This notation provides precise type information and enables better IDE autocompletion and static analysis.