Skip to content
TheChatArchiveThe Chat Archive
Claudeclaude-opus-4-20250514-thinking-16k· AnthropicHugging Face LMArena Human Preference 140K

phpdocbock @return how to signal returned array structure in docbloc. exaple: public…

  1. User

    phpdocbock @return how to signal returned array structure in docbloc.

    exaple:

    public function calculateSimInventoryTotals(): array
    {
    
        return [
            'count' => $simCollection->count(),
            'price' => $simCollection->sum('price'),
        ];
    }
    
  2. Claude 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.

  3. User

    array shape noration

  4. Claude 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

    1. IDE Support: Most modern IDEs (PHPStorm 2020.3+, VS Code with PHP extensions) support array shape notation
    2. Static Analysis: Tools like Psalm and PHPStan fully support this notation
    3. Key Names: Keys must be valid PHP identifiers or integers
    4. Optional Keys: Use ? after the type to indicate optional keys
    5. 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.