PHPDoc container objects to act like arrays

Question

Is it possible to indicate that an object behaves like a container, implements \ArrayAccess when writing a doc, specifically, a @return one.

For example if I have a class Collection implements \ArrayAccess, \Countable, \IteratorAggregate object filled with Entity objects from database.

What I'd like to have is PHPStorm (specifically) to have hints available for Collection objects as well as to understand what values they have.

Currently we have this notation for arrays of objects

/**
* @return \Entity[]
*/

This means the method returns an array of Entities. How may I do the same for a different class? I'm thinking about something like this:

/**
* @return \Entity[\Collection]
*/

I have created a pastebin (note that it has links to two more pastebins for Entity and Collection classes).

PASTEBIN example

Could you please clarify what you want to achieve with \Entity[\Collection] (in other words: what it means for you). — LazyOne
– LazyOne, Commented Oct 20, 2015 at 8:04
@LazyOne sorry for not being clear. That means that the return value is a collection consisting of multiple entities. Just like \Entity[] currently means the return value is an array consisting of multiple entities. — Sergey Telshevsky
– Sergey Telshevsky, Commented Oct 20, 2015 at 9:01
So basically ... it's Collection and array of Entities at the same time, right? If so -- have you tried \Collection|\Entity[] syntax? That's the only one I can think of right now. — LazyOne
– LazyOne, Commented Oct 20, 2015 at 9:19
Right. That's basically an OR statement, looks interesting, but PHPStorm autocompletes only for the first mentioned class, in this case, the \Collection :( — Sergey Telshevsky
– Sergey Telshevsky, Commented Oct 20, 2015 at 9:29
Could you please create and share some sample project (or just single file) with basic implementation that would illustrate your situation (basic implementation of your Collection and Entity classes and how you use them )? Projects which I'm involved (usually 3-5+ years old) do not use any collections (or proper ORM at all) so I do not have anything at hand to quickly check other options. — LazyOne
– LazyOne, Commented Oct 20, 2015 at 9:52

LazyOne · Accepted Answer · 2015-10-21 09:59:15Z

2

Based on your pastebin examples single typehint in right place seems to be enough (tested in PhpStorm v9.5 EAP build):

/** @var \Collection|\Entity[] $collection */
$collection = new Collection($entities);

For $collection it offers methods from \Collection class:

For $entity (inside foreach loop) it offers \Entity methods:

If anything you can always type hint $entity variable individually:

edited Oct 21, 2015 at 9:59

answered Oct 21, 2015 at 9:48

LazyOne

167k49 gold badges419 silver badges422 bronze badges

Sign up to request clarification or add additional context in comments.

1 Comment

Sergey Telshevsky Over a year ago

That's what I was looking for, strange, but I tried /** @var \Collection|\Entity[] $collection */ yesterday and it did not work, maybe it was because phpstorm was still parsing the code. However, I've just tried adding /* @method \EntityCollection|\Entity\Client[] findAll($filter) */ and indeed, it does everything perfectly. I still don't understand how it's working though, and how PHPStorm understands that it's an instance of collection that is returned in the first place. Anyway it works as @method return value and I thank you very much for this.

Kris · Accepted Answer · 2015-10-21 09:30:15Z

1

What you seem to want cannot really be done (at the moment) as far as I am aware. I've tried to get the same functionality myself some time ago.

However, you can do something like this:

<?php

/**
 * @return MyCollectionType
 */
function getEntityCollectionFromSomewhere()
{
    return ...
}

$myEntityCollection = getEntityCollectionFromSomewhere();

foreach($myEntityCollection as $entity)
{
    if ($entity instanceof MyEntityType)
    {
        // code completion is active here for MyEntityType...
    }
}

This is the best I've found so far; you get Collection completion where you're working with a collection, and entity functionality where you're working with a single element from that collection.

edited Oct 21, 2015 at 9:30

answered Oct 21, 2015 at 7:25

Kris

42.1k9 gold badges78 silver badges103 bronze badges

6 Comments

Sergey Telshevsky Over a year ago

I'm sorry, but I don't see why autocomplete for collection should fire here, are you sure it's not @return Collection?

Sergey Telshevsky Over a year ago

And does PHPStorm start to typehint MyEntityType because of the if statement?

Kris Over a year ago

@SergeyTelshevsky: you are correct, I'll fix my mistake in the code sample. and yes the if instanceof ... construct lets PHPStorm understand your intention and enables the code completion there.

Alfwed Over a year ago

also /* @var $entity Entity */ and it makes it clear it's just there for the type hinting

Kris Over a year ago

@Alfwed: Indeed, if you like. I just find the instanceof check easier on my eyes. (I don't like comments to have actual program meaning)

|

Collectives™ on Stack Overflow

PHPDoc container objects to act like arrays

2 Answers 2

1 Comment

6 Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

1 Comment

6 Comments

Your Answer

Sign up or log in

Post as a guest

Related