PHP Doc generic type declaration

Question

I'm working on a library which uses the phpDocumentor specification on determining the type system using reflection. However, I couldn't find any information about generic type declarations.

Is there any way a generic type declaration should be specified?

For example: is there any specification (in-progress) which specifies anything like:

/**
 * @template <T extends Base>
 */
class Collection {

    /**
     * @return Iterator<T>
     */
    function get_iterator();

}

Note that the code above is just an example to illustrate what I mean by generic type declarations. I do not want this achieve anything to do with collections and iterators.

Doesn't this look a bit like you want abstract class Collection implements \Iterator {}? — Elias Van Ootegem
– Elias Van Ootegem, Commented Sep 17, 2015 at 10:40
@NDM I understand that it isn't supported in PHP. That doesn't mean it couldn't be supported in phpDocumentor or any derivation. That is what my question is about. — Tim
– Tim, Commented Sep 17, 2015 at 10:51
@NDM Because you don't understand the question, doesn't mean it isn't clear. — Tim
– Tim, Commented Sep 17, 2015 at 10:55
This is likely the next gen php doc, if it gets approved: github.com/phpDocumentor/fig-standards/blob/master/proposed/… — goat
– goat, Commented Jan 5, 2016 at 19:16

Jim Driscoll · Accepted Answer · 2019-12-28 11:37:22Z

6

There apparently was some interest in the related topic of object specialization because that was added to PSR-5:

generic = collection-type "<" [type-expression "," *SP] type-expression ">"

Edit: and then removed as Jack notes below, albeit with a stated expectation that they'll return in one form or another before it's standardised

However, it doesn't provide a means to define a class as generic, and PSR-5 has been abandoned for a long while. The de-facto standard, phpDocumentor, does not in any way define support for such syntax.

If you want to informally mark up generics, you're best off making up your own syntax (inspired by similar syntax that already exists like Closure's documentation or JSDoc) while carefully avoiding anything that could actively confuse phpDocumentor, something like:

/**
 * @template {Base} T
 */
/**
 * @return Iterator {Iterator<T>}
 */

If you want to do it formally, you'll need to switch to another documentation system like doxygen.

edited Dec 28, 2019 at 11:37

answered Apr 26, 2018 at 23:31

Jim Driscoll

90411 silver badges8 bronze badges

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

2 Comments

Jack Wilsdon Over a year ago

It looks like generics have been removed from the PSR for the time being.

Jim Driscoll Over a year ago

@JackWilsdon thanks, I've updated the answer to note this

Dakusan · Accepted Answer · 2019-05-27 23:00:49Z

2

You might want to check out the psalm project.

https://psalm.dev/docs/

https://github.com/vimeo/psalm

It supports generics in the documentation, as well as so much more. It's also used by Symfony's DB ORM, doctrine.

It supports Emacs, Phpstorm/Intellij, vim, and visual studio

answered May 27, 2019 at 23:00

Dakusan

6,7305 gold badges36 silver badges49 bronze badges

Comments

David Mann · Accepted Answer · 2021-08-03 15:31:47Z

0

Psalm supports this via

/**
 * @template T of Foo
 */

Ref: https://medium.com/vimeo-engineering-blog/uncovering-php-bugs-with-template-a4ca46eb9aeb

answered Aug 3, 2021 at 15:31

David Mann

2,0023 gold badges17 silver badges19 bronze badges

Collectives™ on Stack Overflow

PHP Doc generic type declaration

3 Answers 3

2 Comments

Comments

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

3 Answers 3

2 Comments

Comments

Comments

Your Answer

Sign up or log in

Post as a guest

Related