[PSR-5] Generics and Internals

[Phil Sturgeon]

The vote failed for arrayof as it is, which was essentially somewhat like generics when used in the context of type hinting. 

Basically: Foo[] is not going to happen.

This is rather frustrating, as to me there is a bit of a difference between generics and simply asking for an array of things, as most generics require a little setup. We can make a special case for array<foo> and have array automatically handle that template, but it seems weird to force generics to handle this and essentially munge typed arrays and generics in together. Whatever, internals has spoken.

This RFC will likely come back with the Hack-style generics support for PHP 5.7 or PHP 6, so we should probably go with that style.

array<int>

array<FooInterface>

Foo<Bar>

The 3rd there is simply an example of the same syntax working with "weak-generics" and "strong generics later" which is how internals will go - if we add generics at all. If we dont add generics then we still have the syntax for docblocks so yaaaaay for that.

[Peter Cowburn]

On 17 March 2014 16:13, Phil Sturgeon <em...@philsturgeon.co.uk> wrote:

The vote failed for arrayof as it is, which was essentially somewhat like generics when used in the context of type hinting. 

Basically: Foo[] is not going to happen.

*sad face*

 

This is rather frustrating, as to me there is a bit of a difference between generics and simply asking for an array of things, as most generics require a little setup. We can make a special case for array<foo> and have array automatically handle that template, but it seems weird to force generics to handle this and essentially munge typed arrays and generics in together. Whatever, internals has spoken.

Unfortunate, but true. Personally I'd have loved to have seen Blah[] made available; it's an entirely different beast from generics and one I'd likely make *much* more use of. Alas, it will not be (at least for now).

 

This RFC will likely come back with the Hack-style generics support for PHP 5.7 or PHP 6, so we should probably go with that style.

array<int>

array<FooInterface>

Foo<Bar>

The 3rd there is simply an example of the same syntax working with "weak-generics" and "strong generics later" which is how internals will go - if we add generics at all. If we dont add generics then we still have the syntax for docblocks so yaaaaay for that.

Are you suggesting we start using the generics-like syntax in docblocks today? For array-of-Foo?

[Jeroen De Dauw]

> Basically: Foo[] is not going to happen.

:( I'm assuming there is a discussion somewhere about that RFC. Can someone please link it?

> This RFC will likely come back with the Hack-style generics support for PHP 5.7 or PHP 6, so we should probably go with that style.

[citation needed]. How do you figure this is the case? If I understand you correctly, switching would mean having things such as "@return array<SomeInterface>" in docblocks. I'd not recommend making such a change unless I'm pretty sure this will end up making more sense, and do so in a reasonable time frame. My IDE does not understand the <> notation, while it has no problem with the good old SomeInterface[].

[Phil Sturgeon]

You can go and prowl around internals if you like.

1. Nope to SomeInterface[]

2. Maybe to array<SomeInterface>

You can either choose to build a docblock standard around:

a) something that definitely will not happen

b) something that might happen.

Go for broke. :)

[Matthieu Napoli]

The fact that that arrayof RFC was refused doesn't mean Foo[] should be made forbidden in PSR-5.

1. That RFC was refused partly because some didn't a use case in it, but also some didn't like the implementation regarding performances. Some that feature might still happen someday (we can hope).

2. There are other phpdoc "features" that don't match a PHP feature, like scalar type-hinting, return type-hinting, etc.

3. Foo[] means an array that at the moment contains only Foo. array<Foo> would mean (if generics are indeed added to PHP) an array that was initialized as a an array that can contain only Foo. There's a difference, which is the same difference between array-of and generics. So Foo[] is still useful in phpdoc. And it's different from the generics notation. Which btw shows that there would be a difference between PHP generics and phpdoc generics.

[Jennifer Hodgdon]

On 03/17/2014 11:20 PM, Phil Sturgeon wrote:
> 1. Nope to SomeInterface[]
>
> 2. Maybe to array<SomeInterface>
>
> You can either choose to build a docblock standard around:
>
> a) something that definitely will not happen
>
> b) something that might happen.

Hi Phil,

The wording of your response here, "Nope to SomeInterface[] ...
something that definitely will not happen" made me feel like
discussion is not welcome for PSR-5, at least in this particular area.

So, rather than presenting my thoughts on this particular part of the
PSR-5 spec (and I do have some), I feel like I need to understand a
bit more about PSR-5's purpose and decision-making process.

The draft PSR-5 document talks about providing best practices and
design patterns that the industry needs for PHP code documentation.
The FIG landing page on Github talks about finding commonalities
between projects and working together.

So... Let me just ask directly: What is the basis for making decisions
on PSR-5? Are the standards proposed in PSR-5 all open for discussion
on this mailing list, so that we can find a good standard that the
industry can rally around, and that satisfies real needs in the
industry, or are they based solely on the current/planned features of
PHPDocumentor? Are the ideas and comments of everyone on the list
welcome and given consideration, or is discussion closed? Are the
opinions and ideas of one person or one organization within the FIG
given more weight than others' opinions and ideas?

If PSR-5's purpose is actually just to document what PHPDocumenter is
doing or plans to do, then (in my opinion) it shouldn't be a proposed
FIG standard -- it should be published as PHPDocumentor documentation.
Or at a minimum, the introduction of the PSR-5 document should be
edited to say that documenting PHPDocumentor is PHP-5's main purpose
(it does not say that now), and then when the standard comes up for
vote in the FIG, the voting members of the FIG should consider this
when deciding whether to adopt PSR-5 as a FIG standard.

Also, if PSR-5 is actually closed to further revisions, then please do
not ask for any more comments -- it is probably time to bring it up
for an up-or-down adoption vote by the FIG.

And if PSR-5's purpose is not limited to PHPDocumentor, and it is
still open for discussion and revision, then can we continue the
discussion about the best way to document arrays of particular classes
of objects (and other items in the proposed standard), without
unilateral "this cannot happen" comments from anyone?

--Jennifer

--
Jennifer Hodgdon * Poplar ProductivityWare
www.poplarware.com
Drupal web sites and custom Drupal modules

[Mike van Riel]

A longer response later but Jennifer, Phil was talking about the rfc on internals. Not PSR 5

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.
To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+unsubscribe@googlegroups.com.
To post to this group, send email to php...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/5328664A.3090807%40poplarware.com.
For more options, visit https://groups.google.com/d/optout.

[Jennifer Hodgdon]

Ah, well the subject line said [PSR-5] right in it... sorry for the
confusion!
--Jennifer

>> email to php-fig+u...@googlegroups.com.

>> To post to this group, send email to php...@googlegroups.com.
>> To view this discussion on the web visit https://groups.google.com/d/
>> msgid/php-fig/5328664A.3090807%40poplarware.com.
>> For more options, visit https://groups.google.com/d/optout.
>>
>

[Phil Sturgeon]

Thanks Mike. That is what I meant. I didn't use enough words it seems.

So to clear up some confusion: 

"Foo[] is not going to happen."

That means Foo[] is not going to happen in PHP 5.6 for sure. It's definitely not going to happen in PHP 5.7 based off this RFC because me and Joe are running that RFC and we'll be changing the syntax. The performance concerns were not the blocker here, the features proximity to generics was the issue.

So, while PSR-5 can do whatever it likes, one of the items listed in the PSR-5 Update thread was:

1. Generics notation for arrays and collection objects, this discussion 
is delayed due to a proposal on internals which may have consequences 
for this proposal. There is also the matter that the Generics support of 
PHPDoc would not match a complete implementation; there is some 
resistance to that. 

PSR-5 is welcome to pick whatever syntax it likes, but if it is held up waiting for arrayof and wondering what is happening then I am telling you the result. The syntax of Foo[] is not happening. Fact. :)

So, if PSR-5 would still like to use that then okie doke. No drama there. But PHP wont have it. 

PHP might have array<Foo> soon. So maybe PSR-5 would like to use that. 

This was an update from the PHP side of things, as the thread asked for that. 

Everyone on the same page now? :)

[Mike van Riel]

Hello Jennifer,

I have a little more time now and so can give a better and more eloquent answer. If my previous reply
was a bit blunt, please forgive me as I had to type from my phone and that just doesn't work ;)

Please allow me to answer some of your questions inline with your reply,

On 18-03-14 16:29, Jennifer Hodgdon wrote:

The wording of your response here, "Nope to SomeInterface[] ... something that definitely will not happen" made me feel like discussion is not welcome for PSR-5, at least in this particular area.

So, rather than presenting my thoughts on this particular part of the PSR-5 spec (and I do have some), I feel like I need to understand a bit more about PSR-5's purpose and decision-making process.

Please, post your questions! Every question and every comment will improve the PSR and will help.

The draft PSR-5 document talks about providing best practices and design patterns that the industry needs for PHP code documentation. The FIG landing page on Github talks about finding commonalities between projects and working together.

So... Let me just ask directly: What is the basis for making decisions on PSR-5? Are the standards proposed in PSR-5 all open for discussion on this mailing list, so that we can find a good standard that the industry can rally around, and that satisfies real needs in the industry, or are they based solely on the current/planned features of PHPDocumentor? Are the ideas and comments of everyone on the list welcome and given consideration, or is discussion closed? Are the opinions and ideas of one person or one organization within the FIG given more weight than others' opinions and ideas?

PSR-5 has the following basis:

1. The existing syntax in the de-factor PHPDoc Standard that is maintained by phpDocumentor.
2. Missing functionality based on what I, and others, have heard and requested at conferences, issue tracker, this mailing list, etc.
3. Removing of redundant concepts in the de-facto PHPDoc Standard.

At this stage of development EVERYTHING is still open for debate. All comments are more than welcome and will contribute to a more well-rounded and proper standard. Please keep in mind that the phpDocumentor project, which I represent, spearheads this project as an independent effort to have all parties who use or consumer the PHPDoc Standard be on the same level. I have regular contact with several parties who are involved with the PHPDoc Standard outside of this mailing list to gather opinions and reflect on what I write.

People who are directly involved with the PHPDoc Standard and Domain Experts such as Chuck and myself have more weight in the decision process as I believe that these parties have more background information and can make decisions based on a bigger picture. Nonetheless I, and others as well, are heavily influenced by the opinions, comments and questions posted here and on the issue tracker for PSR-5.

In the end I have the, sometimes unfortunate, responsibility to cut the knots and make the decisions what goes into PSR-5 and what not. I try to always pick the decision that suits the majority of the members of PHP-FIG as the PSR standards are meant to promote interoperability between members of this group. I do however reserve the right, as editor, to sometimes pick a less-supported option if I am heavily convinced that the alternatives will not benefit PSR-5 in the long run. Though I hate doing so and will try to prevent this wherever possible as I am convinced it means I have failed to bring my point across.

I am going to repeat this to make everything clear: the only connection between PSR-5 and phpDocumentor is that phpDocumentor sponsors the knowledge and time to work on this.

If PSR-5's purpose is actually just to document what PHPDocumenter is doing or plans to do, then (in my opinion) it shouldn't be a proposed FIG standard -- it should be published as PHPDocumentor documentation. Or at a minimum, the introduction of the PSR-5 document should be edited to say that documenting PHPDocumentor is PHP-5's main purpose (it does not say that now), and then when the standard comes up for vote in the FIG, the voting members of the FIG should consider this when deciding whether to adopt PSR-5 as a FIG standard.

PSR-5's goal is to provide IDE's, Annotation Engines, Documentation tools and users with a single central and formal specification to which you can refer.

Also, if PSR-5 is actually closed to further revisions, then please do not ask for any more comments -- it is probably time to bring it up for an up-or-down adoption vote by the FIG.

And if PSR-5's purpose is not limited to PHPDocumentor, and it is still open for discussion and revision, then can we continue the discussion about the best way to document arrays of particular classes of objects (and other items in the proposed standard), without unilateral "this cannot happen" comments from anyone?

I think we are already on the same page based on my previous mail. There was apparently an unfortunate misunderstanding, `this cannot happen` was only in reference to the discussion on internals.

PSR-5 is not complete and not ready to go open for vote.

   --Jennifer

Kind regards,

Mike van Riel

[Jennifer Hodgdon]

Mike: Thanks for taking the time to clarify. Much appreciated, and I'm
glad PSR-5 is still open for discussion and revision (I may open some
discussions :) ).

[Mike van Riel]

I can only encourage you to do so, we can only benefit as community

--
You received this message because you are subscribed to the Google Groups "PHP Framework Interoperability Group" group.

To unsubscribe from this group and stop receiving emails from it, send an email to php-fig+unsubscribe@googlegroups.com.

To post to this group, send email to php...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msgid/php-fig/5328717C.7080100%40poplarware.com.

[Michiel Rook]

On 17/03/2014 17:13, Phil Sturgeon wrote:

The vote failed for arrayof as it is, which was essentially somewhat like generics when used in the context of type hinting. 

Basically: Foo[] is not going to happen.

Ugh. Too bad.