PHPStorm: correct PHPDoc for a Collection of Objects?

Question

I'm using the PHPStorm IDE, and run into trouble when I run the code inspection.

I have a method which returns a collection of objects. The Collection itself is an object, which has its own methods, and implements the Traversable interface:

class Repository
{
    public function findByCustomer(Customer $user)
    {
        // ...
        return new Collection($orders);
    }
}

If I document findByUser() to return a Collection, the code inspection understands the methods on this object, but doesn't understand what objects the collection contains:

/**
 * @return Collection
 */
public function findByCustomer() { ... }

Method getTotal() not found in class Collection

If I document findByUser() to return a collection of Order objects, the code inspection now understands what's inside the collection, but not the methods on the Collection itself:

/**
 * @return Order[]
 */
public function findByCustomer() { ... }

Method slice() not found in class Order[]

Is there a way to specify both at the same time, something like Java's syntax?

/**
 * @return Collection<Order>
 */
public function findByCustomer() { ... }

You can combine them (both types) together. May not be ideal in some situations, but works and you may consider it better than manually specifying type via @var PHPDoc comment. So ... `/** @return Collection|Order[] */` — LazyOne, May 23 '12 at 09:12
@LazyOne: even if not the perfect one, that's a cleaner option to me. Can you add this as an answer? — BenMorel, May 23 '12 at 09:26

score 69 · Answer 1 · answered May 23 '12 at 09:58

69

You can combine them (both types) together. May not be ideal in some situations, but works and you may consider it better than manually specifying type via @var PHPDoc comment.

/** @return Collection|Order[] */

answered May 23 '12 at 09:58

LazyOne

158,824
45
388
391

In that case it can even read : return Collection than can be seen as an array of Order. – programaths Aug 28 '13 at 14:01
@Benjamin Please provide some simple code example to copy-paste (I would like to see it myself deeper) – LazyOne Mar 13 '14 at 10:45
@LazyOne I'm surprised I can't repeat it now, I had all these inspection issues when I first opened PHPStorm 8. It might not be what I thought, and in fact be related to [WI-22469](http://youtrack.jetbrains.com/issue/WI-22469) you just commented on! – BenMorel Mar 13 '14 at 13:02

score 30 · Accepted Answer · edited Dec 19 '22 at 19:46

30

Phpstorm starting from 2021.2 allows the following syntax:

    /**
     * @return Collection<Order>
     */

This works for Doctrine Collections - and all Laravel Collections starting with Laravel 9 (the required annotation is not present in L8).

Screenshot from PhpStorm What's New 2021.2:

edited Dec 19 '22 at 19:46

raveren

17,799
12
70
83

answered Oct 15 '21 at 12:17

MV1908

424
4
4

I was waiting for such a feature like since ever... – Bartłomiej Sobieszek Dec 02 '21 at 18:52
6

This works for Doctrine, but not fo Laravel collections – Adam Apr 27 '22 at 20:57
Actually the correct syntax should be `Collection` for Doctrine. – BenMorel Nov 21 '22 at 08:16
PHPStorm still doesn't have great support for accessing `\ArrayAccess` using regular `$collection[0]` syntax as of 2022.3.2, see related https://youtrack.jetbrains.com/issue/WI-61439/Support-generics-for-array-access-type-inference-via-ArrayAccessoffsetGet – AlbinoDrought Feb 01 '23 at 19:56

score 3 · Answer 3 · answered Apr 27 '22 at 21:12

As MV1908 said, you can use generic collecions in PHPStorm since 2021.2. However, note that this is only possible for a custom collection class (that you created yourself) and Doctrine collection, see https://blog.jetbrains.com/phpstorm/2021/07/phpstorm-2021-2-release/

With the release of PHPStorm 2021.3 its now possible to use generics also for Laravel Collections (however only for Laravel 9). See https://blog.jetbrains.com/phpstorm/2021/12/phpstorm-2021-3-release/#support_for_future_laravel_collections

PHPStorm: correct PHPDoc for a Collection of Objects?

3 Answers3

Linked