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() { ... }

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() { ... }

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

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

Answer 1

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[] */