Re: [PHP-DEV] Native Annotation Syntax

[Rowan Collins]

guilhermebla...@gmail.com wrote on 26/11/2015 01:13:

Ok, so I'll explain why it's not "the same way" as you imagine.

I've heard this many times already so I'll save you keystrokes.
- "Sure, we can do that on docblocks"
- "Based on that, it doesn't need to be part of core and can safely be 
implemented as a PECL extension"




OK, as far as everything I was talking about, this is all rather a straw 
man, but perhaps that's just a miscommunication on my part, so let me 
clear that up:


I have never suggested, and would not support a suggestion, that this be 
implemented as an extension. I can absolutely see the advantage to 
having a first-class syntax, baked into the main parser.


With that out of the way, we are back to the main point I was trying to 
make which is that that syntax could, if we wanted, live inside the 
context of /** */ blocks, which are already treated differently from 
comments. The parsing problems within that context are very similar to 
the parsing problems in any other context (again, assuming that this is 
being implemented directly in the core parser, not in any kind of 
extension).


So, the pros and cons of that are not to do with the parsing but to do with:
- potential compatibility with existing code, which may be tricky as 
there is no standard to base the feature on
- the ability to polyfill code in older PHP versions, which is useful 
but not something we have aimed for with previous features
- on the other side, the perception that docblocks are "just comments", 
which would be hard to dispel even if we renamed them "metadata blocks"


Anyway, I apologise for drawing out this part of the discussion for so 
long. I actually think it's just one of many decisions that needs making 
before this feature can be attempted, probably starting with just what 
an annotation consists of - is it a label with some text attached? a 
resolved class name with parsed PHP code passed to its constructor (some 
people have mentioned arrays and heredocs as parameters to annotations)? 
somewhere between the two?


Regards,
--
Rowan Collins
[IMSoP]

--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php

Re: [PHP-DEV] Native Annotation Syntax

[Pedro Cordeiro]

Hi, Rowan. I'll respond to some points that have become recurrent.

1) It's might not be objectively bad to add this feature in docblocks, but
it will be objectively wrong to keep calling them "DocBlocks" if they are
no longer documentation-only blocks.

2) Even though PHP already treats docblocks differently from comments,
that's not the common view on userland, nor is explained on the manuals.
There are no separate entries to explain docblocks, and no mention to them
on the "Comments" page. The Reflection method to retrieve DocBlocks is
"getDocCOMMENT", which suggests they are comment that do not affect runtime
behaviour.

We'd have to update the comments page to say "'/*' starts a comment, unless
if they're immediately followed by another asterisk ('/**'), in which case
it may or may not be a comment, depends on the following token". It's very
confusing.

3) To make this work within docblocks, we'd have to get rid of at least one
configuration setting (opcode.save_comments).

4) You've suggested disregarding docblock stripping from transpilers and
obfuscators, because they are not first-class citizens, even though those
are part of the PHP ecosystem and affect users.

5) We'd have a harder time making decisions on syntax for docblocks,
because there are already multiple different implementations, and because
people will have a hard time agreeing on some points, like the one
guilherme made about the asterisks (*) or spaces being part of multiline
annotation or not.

Whereas none of these points are issues for a native syntax outside
docblocks, because it'd be a completely different feature that would reside
in new syntax, not in modification of current syntax.

2015-11-26 8:06 GMT-02:00 Rowan Collins :

> guilhermebla...@gmail.com wrote on 26/11/2015 01:13:
>
>> Ok, so I'll explain why it's not "the same way" as you imagine.
>>
>> I've heard this many times already so I'll save you keystrokes.
>> - "Sure, we can do that on docblocks"
>> - "Based on that, it doesn't need to be part of core and can safely be
>> implemented as a PECL extension"
>>
>>
> OK, as far as everything I was talking about, this is all rather a straw
> man, but perhaps that's just a miscommunication on my part, so let me clear
> that up:
>
> I have never suggested, and would not support a suggestion, that this be
> implemented as an extension. I can absolutely see the advantage to having a
> first-class syntax, baked into the main parser.
>
> With that out of the way, we are back to the main point I was trying to
> make which is that that syntax could, if we wanted, live inside the context
> of /** */ blocks, which are already treated differently from comments. The
> parsing problems within that context are very similar to the parsing
> problems in any other context (again, assuming that this is being
> implemented directly in the core parser, not in any kind of extension).
>
> So, the pros and cons of that are not to do with the parsing but to do
> with:
> - potential compatibility with existing code, which may be tricky as there
> is no standard to base the feature on
> - the ability to polyfill code in older PHP versions, which is useful but
> not something we have aimed for with previous features
> - on the other side, the perception that docblocks are "just comments",
> which would be hard to dispel even if we renamed them "metadata blocks"
>
> Anyway, I apologise for drawing out this part of the discussion for so
> long. I actually think it's just one of many decisions that needs making
> before this feature can be attempted, probably starting with just what an
> annotation consists of - is it a label with some text attached? a resolved
> class name with parsed PHP code passed to its constructor (some people have
> mentioned arrays and heredocs as parameters to annotations)? somewhere
> between the two?
>
>
> Regards,
> --
> Rowan Collins
> [IMSoP]
>
> --
> PHP Internals - PHP Runtime Development Mailing List
> To unsubscribe, visit: http://www.php.net/unsub.php
>
>

Re: [PHP-DEV] Native Annotation Syntax

[Levi Morrison]

> Ah, and please stop saying "it should be in docblock". This argument is
> just bull... to suppress the actual people interested to see this natively
> available and just exposes your lack of interest into language improvement.

Every feature has a cost and benefit. It is perfectly fine to have the
opinion that a feature is better left out of the language based on
that cost. Being against a feature does not mean that person is
against language improvement or has a lack of interest.

-- 
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php

Re: [PHP-DEV] Native Annotation Syntax

[Rowan Collins]

Hi Pedro,

I agree with most of the points in your last mail. At the end of the 
day, the reasons are fairly subjective, and relate to how the feature 
will be perceived, and the freedom to design it without annoying people, 
but that doesn't stop them being real.


However I would like to come back on this one:

Pedro Cordeiro wrote on 26/11/2015 11:46:
4) You've suggested disregarding docblock stripping from transpilers 
and obfuscators, because they are not first-class citizens, even 
though those are part of the PHP ecosystem and affect users.


You're putting words into my mouth there; I never said to disregard the 
tools themselves, I disputed that they will be disadvantaged by one 
syntax over another.


Transpilers and obfuscators will have to make changes either way, if 
they are to support annotations; the nature of those changes is 
different inside and outside docblocks, but that doesn't seem that big a 
deal to me. Whatever the syntax, they will have to do two things: 1) 
parse the source code for annotations, adding them to whatever AST or 
similar they use; 2) output those annotations (with any relevant 
transforms) in the appropriate syntax. I don't see /** @Foo(42) */ as 
fundamentally harder to do that with than << Foo(42) >>, or whatever 
other syntax anyone comes up with.


Other than this point, this e-mail is a much better summary of why 
docblocks should not be used than any details about which of two 
syntaxes (that we haven't invented yet) parsers might or might not find 
harder.


As I say, apologies for side-tracking the conversation for so long, I 
was intending it to be one decision among many, and wanted to make sure 
we'd captured a good reason for the decision, so that it could be 
justified in future.


Regards,
--
Rowan Collins
[IMSoP]

--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php

Re: [PHP-DEV] Native Annotation Syntax

[guilhermebla...@gmail.com]

Let's be clear. I haven't seen any user asking for traits, which introduced
almost the same amount of performance cost and complexity to ZE. It was
proposed by a "long term contributor" and everybody said yay.

When multiple userland people ask about the same feature, every single
major framework uses a hackish way to suppress a language deficiency, and
internals developers don't move a finger (or even care to reply here) about
the subject, it clearly exposes to me they're not paying attention to
user's needs. This is lack of interest, but you can choose better words.

Regards,

On Thu, Nov 26, 2015 at 9:51 AM, Levi Morrison  wrote:

> > Ah, and please stop saying "it should be in docblock". This argument is
> > just bull... to suppress the actual people interested to see this
> natively
> > available and just exposes your lack of interest into language
> improvement.
>
> Every feature has a cost and benefit. It is perfectly fine to have the
> opinion that a feature is better left out of the language based on
> that cost. Being against a feature does not mean that person is
> against language improvement or has a lack of interest.
>



-- 
Guilherme Blanco
MSN: guilhermebla...@hotmail.com
GTalk: guilhermeblanco
Toronto - ON/Canada

Re: [PHP-DEV] Native Annotation Syntax

[Rowan Collins]

guilhermebla...@gmail.com wrote on 26/11/2015 15:14:

I haven't seen any user asking for traits


Just because you didn't see it, doesn't mean it didn't happen.

I just did a very quick search on Google for php + mixins, limited to 
2007 or earlier (long before the current Trait implementation was born), 
and got plenty of results lamenting the lack of support for horizontal 
reuse in PHP.


See for yourself: 
https://encrypted.google.com/search?q=php+%22horizontal+reuse%22=active=en=lnt=cdr%3A1%2Ccd_min%3A%2Ccd_max%3A12%2F31%2F2007=#safe=active=en=cdr:1%2Ccd_max:12%2F31%2F2007=php+mixins


It's a common accusation of projects like this that time was spent on X 
that should have been spent on Y, but that's nearly always a massive 
over-simplification.


Let's not spend too much time worrying if specific people are interested 
- they may just be on holiday, or busy elsewhere, or just not have much 
to say until someone assembles a few more details about the proposed 
feature. Keep it constructive, lay out how you think the feature should 
look and why, what questions are still open, and see what's needed to 
move it forward.


Regards,
--
Rowan Collins
[IMSoP]

--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php

Re: [PHP-DEV] Native Annotation Syntax

[Pedro Cordeiro]

Hey, Rowan, don't apologize for making the case for what you believed to be
the right way. I'm glad I could summarize my views in a way that you could
agree with me.

I've reread your point about the transpilers and obfuscators, and you're
right, I misunderstood what you said. I'm sorry.

Now, I'd be willing to create a new RFC draft for a native annotation
syntax, targeted at 7.1, this time explaining the reasons NOT to do this in
docblocks nor in a seperate extension, so the discussion won't get
sidetracked again. I'd need some help with the patches, though, since I
don't have any experience with the internals.

There is still the issue of complexity added to the engine, which we could
discuss. I'd like to hear more from a long-term contributor about that, if
it's possible. Were there any performance implications on the previously
submitted patch?

Thank you everyone for the great discussion.

Re: [PHP-DEV] Native Annotation Syntax

[guilhermebla...@gmail.com]

Ok then. I'll pretend that lack of interest didn't happen many other
situations (like http://marc.info/?t=14460876781) and move on.

I don't want to bring the patch up to date/simplify it without a clear
decision of at least be willing to discuss the patch and not reject by all
means.
I'd propose a voting as "Are you ready for Annotations yet?". Every core
developer understands (and can base their decisions) by looking at the
complexity of the old patch.

Once voting completes and IF it gets approved, I'll gladly put it up to
date for consideration and update the RFC.

[]s,

On Thu, Nov 26, 2015 at 10:53 AM, Rowan Collins 
wrote:

> guilhermebla...@gmail.com wrote on 26/11/2015 15:14:
>
>> I haven't seen any user asking for traits
>>
>
> Just because you didn't see it, doesn't mean it didn't happen.
>
> I just did a very quick search on Google for php + mixins, limited to 2007
> or earlier (long before the current Trait implementation was born), and got
> plenty of results lamenting the lack of support for horizontal reuse in PHP.
>
> See for yourself:
> https://encrypted.google.com/search?q=php+%22horizontal+reuse%22=active=en=lnt=cdr%3A1%2Ccd_min%3A%2Ccd_max%3A12%2F31%2F2007=#safe=active=en=cdr:1%2Ccd_max:12%2F31%2F2007=php+mixins
>
> It's a common accusation of projects like this that time was spent on X
> that should have been spent on Y, but that's nearly always a massive
> over-simplification.
>
> Let's not spend too much time worrying if specific people are interested -
> they may just be on holiday, or busy elsewhere, or just not have much to
> say until someone assembles a few more details about the proposed feature.
> Keep it constructive, lay out how you think the feature should look and
> why, what questions are still open, and see what's needed to move it
> forward.
>
>
> Regards,
> --
> Rowan Collins
> [IMSoP]
>
> --
> PHP Internals - PHP Runtime Development Mailing List
> To unsubscribe, visit: http://www.php.net/unsub.php
>
>


-- 
Guilherme Blanco
MSN: guilhermebla...@hotmail.com
GTalk: guilhermeblanco
Toronto - ON/Canada

Re: [PHP-DEV] Native Annotation Syntax

[Chris Riley]

On 26 November 2015 at 16:05, guilhermebla...@gmail.com <
guilhermebla...@gmail.com> wrote:

> Ok then. I'll pretend that lack of interest didn't happen many other
> situations (like http://marc.info/?t=14460876781) and move on.
>
> I don't want to bring the patch up to date/simplify it without a clear
> decision of at least be willing to discuss the patch and not reject by all
> means.
> I'd propose a voting as "Are you ready for Annotations yet?". Every core
> developer understands (and can base their decisions) by looking at the
> complexity of the old patch.
>
> Once voting completes and IF it gets approved, I'll gladly put it up to
> date for consideration and update the RFC.
>
> []s,
>
> On Thu, Nov 26, 2015 at 10:53 AM, Rowan Collins 
> wrote:
>
> > guilhermebla...@gmail.com wrote on 26/11/2015 15:14:
> >
> >> I haven't seen any user asking for traits
> >>
> >
> > Just because you didn't see it, doesn't mean it didn't happen.
> >
> > I just did a very quick search on Google for php + mixins, limited to
> 2007
> > or earlier (long before the current Trait implementation was born), and
> got
> > plenty of results lamenting the lack of support for horizontal reuse in
> PHP.
> >
> > See for yourself:
> >
> https://encrypted.google.com/search?q=php+%22horizontal+reuse%22=active=en=lnt=cdr%3A1%2Ccd_min%3A%2Ccd_max%3A12%2F31%2F2007=#safe=active=en=cdr:1%2Ccd_max:12%2F31%2F2007=php+mixins
> >
> > It's a common accusation of projects like this that time was spent on X
> > that should have been spent on Y, but that's nearly always a massive
> > over-simplification.
> >
> > Let's not spend too much time worrying if specific people are interested
> -
> > they may just be on holiday, or busy elsewhere, or just not have much to
> > say until someone assembles a few more details about the proposed
> feature.
> > Keep it constructive, lay out how you think the feature should look and
> > why, what questions are still open, and see what's needed to move it
> > forward.
> >
> >
> > Regards,
> > --
> > Rowan Collins
> > [IMSoP]
> >
> > --
> > PHP Internals - PHP Runtime Development Mailing List
> > To unsubscribe, visit: http://www.php.net/unsub.php
> >
> >
>
>
> --
> Guilherme Blanco
> MSN: guilhermebla...@hotmail.com
> GTalk: guilhermeblanco
> Toronto - ON/Canada
>

Given that a lot of userland people have voting rights; I would suspect
that an annotations rfc would pass, provided it met the needs of these
users. As far as docblocks vs native goes - you've convinced me that native
would be best, previously I'd have been more in favour of adding a
getAnnotations method to ReflectionClass/Method/Property, to pull in
annotations from docblocks.

I'd like to see this goto a new RFC here are some questions though:

- Can annotations be applied to functions?
- Class constants?
- Should annotations be a special type eg annotation Foo{} or just a class?
- Do we want to add decorator support at the same time? (
http://thecodeship.com/patterns/guide-to-python-function-decorators/)

Re: [PHP-DEV] Native Annotation Syntax

[Rowan Collins]

guilhermebla...@gmail.com wrote on 26/11/2015 16:05:
Ok then. I'll pretend that lack of interest didn't happen many other 
situations (like http://marc.info/?t=14460876781) and move on.


It's possible that a lot of the core devs are still concentrating on 
getting the changes in 7.0 bedded in, and have more time to discuss 
features for 7.1 in a month or two.


--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php

Re: [PHP-DEV] Native Annotation Syntax

[Levi Morrison]

On Thu, Nov 26, 2015 at 9:57 AM, Rowan Collins  wrote:
> guilhermebla...@gmail.com wrote on 26/11/2015 16:05:
>>
>> Ok then. I'll pretend that lack of interest didn't happen many other
>> situations (like http://marc.info/?t=14460876781) and move on.
>
>
> It's possible that a lot of the core devs are still concentrating on getting
> the changes in 7.0 bedded in, and have more time to discuss features for 7.1
> in a month or two.

At least a few are working on features of their own.

I am curious – a quick scan of this thread didn't seem to actually
propose anything new. It's just discussion about same RFC that was
already rejected. Correct?

--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php

Re: [PHP-DEV] Native Annotation Syntax

[Pedro Cordeiro]

Levi, I was asking about the reasons it was rejected. While researching, I
found the original RFC was voted with 123 votes (71% approval), and yet was
marked as 'declined'. I didn't know why, couldn't find why, so I figured
I'd ask (as it strikes me as a major feature that's missing).

2015-11-26 15:11 GMT-02:00 Levi Morrison :

> On Thu, Nov 26, 2015 at 9:57 AM, Rowan Collins 
> wrote:
> > guilhermebla...@gmail.com wrote on 26/11/2015 16:05:
> >>
> >> Ok then. I'll pretend that lack of interest didn't happen many other
> >> situations (like http://marc.info/?t=14460876781) and move on.
> >
> >
> > It's possible that a lot of the core devs are still concentrating on
> getting
> > the changes in 7.0 bedded in, and have more time to discuss features for
> 7.1
> > in a month or two.
>
> At least a few are working on features of their own.
>
> I am curious – a quick scan of this thread didn't seem to actually
> propose anything new. It's just discussion about same RFC that was
> already rejected. Correct?
>
> --
> PHP Internals - PHP Runtime Development Mailing List
> To unsubscribe, visit: http://www.php.net/unsub.php
>
>

Re: [PHP-DEV] Native Annotation Syntax

[guilhermebla...@gmail.com]

Answers inline

On Thu, Nov 26, 2015 at 11:58 AM, Chris Riley  wrote:

>
> On 26 November 2015 at 16:05, guilhermebla...@gmail.com <
> guilhermebla...@gmail.com> wrote:
>
>> Ok then. I'll pretend that lack of interest didn't happen many other
>> situations (like http://marc.info/?t=14460876781) and move on.
>>
>> I don't want to bring the patch up to date/simplify it without a clear
>> decision of at least be willing to discuss the patch and not reject by all
>> means.
>> I'd propose a voting as "Are you ready for Annotations yet?". Every core
>> developer understands (and can base their decisions) by looking at the
>> complexity of the old patch.
>>
>> Once voting completes and IF it gets approved, I'll gladly put it up to
>> date for consideration and update the RFC.
>>
>> []s,
>>
>> On Thu, Nov 26, 2015 at 10:53 AM, Rowan Collins 
>> wrote:
>>
>> > guilhermebla...@gmail.com wrote on 26/11/2015 15:14:
>> >
>> >> I haven't seen any user asking for traits
>> >>
>> >
>> > Just because you didn't see it, doesn't mean it didn't happen.
>> >
>> > I just did a very quick search on Google for php + mixins, limited to
>> 2007
>> > or earlier (long before the current Trait implementation was born), and
>> got
>> > plenty of results lamenting the lack of support for horizontal reuse in
>> PHP.
>> >
>> > See for yourself:
>> >
>> https://encrypted.google.com/search?q=php+%22horizontal+reuse%22=active=en=lnt=cdr%3A1%2Ccd_min%3A%2Ccd_max%3A12%2F31%2F2007=#safe=active=en=cdr:1%2Ccd_max:12%2F31%2F2007=php+mixins
>> >
>> > It's a common accusation of projects like this that time was spent on X
>> > that should have been spent on Y, but that's nearly always a massive
>> > over-simplification.
>> >
>> > Let's not spend too much time worrying if specific people are
>> interested -
>> > they may just be on holiday, or busy elsewhere, or just not have much to
>> > say until someone assembles a few more details about the proposed
>> feature.
>> > Keep it constructive, lay out how you think the feature should look and
>> > why, what questions are still open, and see what's needed to move it
>> > forward.
>> >
>> >
>> > Regards,
>> > --
>> > Rowan Collins
>> > [IMSoP]
>> >
>> > --
>> > PHP Internals - PHP Runtime Development Mailing List
>> > To unsubscribe, visit: http://www.php.net/unsub.php
>> >
>> >
>>
>>
>> --
>> Guilherme Blanco
>> MSN: guilhermebla...@hotmail.com
>> GTalk: guilhermeblanco
>> Toronto - ON/Canada
>>
>
> Given that a lot of userland people have voting rights; I would suspect
> that an annotations rfc would pass, provided it met the needs of these
> users. As far as docblocks vs native goes - you've convinced me that native
> would be best, previously I'd have been more in favour of adding a
> getAnnotations method to ReflectionClass/Method/Property, to pull in
> annotations from docblocks.
>
> I'd like to see this goto a new RFC here are some questions though:
>
> - Can annotations be applied to functions?
>

Yes, classes, interfaces, traits, methods, properties, functions.
Unfortunately we can't apply to namespaces as they don't exist after
compile time.


> - Class constants?
>

No, there's no Reflection data structure around them and imposing one would
be a serious BC break


> - Should annotations be a special type eg annotation Foo{} or just a class?
>

Annotation classes would be annotated with @Annotation and their
corresponding @Target (where they could be applied).


> - Do we want to add decorator support at the same time? (
> http://thecodeship.com/patterns/guide-to-python-function-decorators/)
>

No. Annotations by itself is already a big endeavor and including more
stuff would only make it harder to implement/digest/approve.
What if Annotation gets approved, but people want decorator out? More
work...
Nothing prevent us to make a subsequent RFC to support decorators if the
first one gets accepted.


Regards,

-- 
Guilherme Blanco
MSN: guilhermebla...@hotmail.com
GTalk: guilhermeblanco
Toronto - ON/Canada

Re: [PHP-DEV] Native Annotation Syntax

[Larry Garfield]

On 11/25/15 10:31 AM, Pedro Cordeiro wrote:

2015-11-25 13:47 GMT-02:00 Lester Caine :


Any new system would require
every third party tool to be adapted to use it


That's not true at all. A new syntax would in no way invalidate parsing
annotations from docblocks.

The only legacy code that is supported by IDEs (if they are, PHPStorm will
not hint/autocomplete, nor will eclipse/netbeans) would be
Symfony2/Doctrine2. There are tons of other tools that with custom
annotations (JMSSerializer as an example) that do not have any support at
all.

This argument is so flawed that you didn't consider that there are many
parsers with many different syntaxes (
https://github.com/jan-swiecki/php-simple-annotations,
https://github.com/nette/neon) and that ANY implementation, be it through
docblocks or with a native syntax would require a rewrite anyway for many
projects if those tools want to support the new native feature.

Also, doing it through an extension is a nice way to delay adoption,
because shared hosts rarely give the option to install new extensions.

I don't have a vote here, but if I had, I'd strongly oppose any
docblock-based implementation.


When Drupal adopted annotations, the absolute #1 objection people had 
was "but docblocks aren't code, you moron!"  There's no value in 
language-native annotations being in the docblock, other than BC with 
*some* existing implementations.  However, doing so would make static 
checking more difficult; If annotations become a language-native 
feature, they should be a first-class citizen to make it easier for IDEs 
to handle.


I'm also not super picky on what the tokens are, however I do think 
mapping them to actual classes, like Doctrine does, would be the most 
flexible.  Structured data all the things.  That also means annotations 
can be namespaced, be affected by use statements, and so forth.  In a 
sense, they become isomorphic to:


class Foo {
  public static function getAnnotations() {
return [
  new OneToMany('a', 'b', 'c'),
  new Stuff('d', 4);
];
  }
}

Except they can be applied to anything reflectable rather than just 
classes.  (Functions, methods, classes, object properties.)


Sara's suggestion of making them legal within a // comment line for BC 
reasons is interesting, but we don't do that for any other new syntax 
AFAIK.  Plus, it means it's harder to comment out an annotation 
temporarily for debugging.  There's still /* */, but it's one more quirk 
to have to think about.


--
--Larry Garfield


--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php

Re: [PHP-DEV] Native Annotation Syntax

[Rowan Collins]

Pedro Cordeiro wrote on 25/11/2015 16:53:
Rowan, even if they are not harder, there is no reason to keep this 
feature in docblocks.


Well, I can think of one reason: backwards compatibility. I don't mean 
with current frameworks - as you say, these are not currently 
standardised, so some will need to be adapted whatever is implemented in 
core - but with older versions of PHP.


If we invent new syntax, then any code using that feature must *require* 
the version of PHP that introduces that syntax, because previous 
versions will simply throw a syntax error. There are a few ways around 
this, such as:


- allowing the annotation to be preceded by // as Sara suggested (or 
maybe #, to make it look like a C pre-processor directive)
- using some other syntax that is currently a no-op, like ECMAScript's 
wacky "use strict"


But ultimately, these end up having the same disadvantages you're 
claiming for docblocks - they look like things you can delete, or which 
has some other purpose, but are actually vital to the operation of the 
code.#


I don't feel that strongly in favour of docblocks, but I don't think the 
reasons given against are particularly strong.


Regards,
--
Rowan Collins
[IMSoP]

--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php

Re: [PHP-DEV] Native Annotation Syntax

[Rowan Collins]

Pedro Cordeiro wrote on 25/11/2015 11:04:
I'd really like to see something outside the docblock. Comment 
annotations are a workaround for the lack of native annotations.


This is true, but they are now a very widely used workaround, and any 
native support for them could be polyfilled using the kind of userland 
libraries that already exist.


It makes the environment hard to learn ("What does @param do? And what 
does @ManyToMany do?")


I'm not sure how this is made any easier by moving the annotations out 
of the docblock. I suppose it's a little confusing that, within the 
docblock, code annotations and documentation annotations share the same 
syntax; maybe we could use a different prefix, like "@@" instead of "@"? 
This would also give a chance for projects to transition to the new 
standard syntax, rather than having to break compatibility if their old 
implementation doesn't quite match.


it makes it impossible for IDEs to hint/autocomplete without 
project-specific plugins


That's a good argument for standardisation, but doesn't require moving 
out of the docblock; in fact, it doesn't even require any action from 
this list, as PHP-FIG could simply agree a PSR, and IDEs like PHPStorm 
would use that as an implementation guide.


and adds this odd notion that removing some comment blocks might break 
an app (which is just awful).


If it helps, just think of /** ... */ as not being a comment, but 
already a first-class piece of syntax. Note that the parser already 
thinks so - hence we can have functions like 
ReflectionMethod::getDocComment. IDEs also parse docblocks already, and 
most syntax highlighting editors can probably style them differently 
from comments so that you don't delete them by mistake.


Now, if annotations were being implemented as something brand new to 
PHP, like say Traits were, I'd agree that we should look to languages 
like Java and C# for syntax ideas. But since a lot of people have 
already invented annotations using docblocks, and since docblocks are 
already supported by the reflection classes, I'm not convinced of why we 
shouldn't just carry on down that route.


Regards,
--
Rowan Collins
[IMSoP]

--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php

Re: [PHP-DEV] Native Annotation Syntax

[Lester Caine]

On 25/11/15 16:53, Rowan Collins wrote:
> Now, if annotations were being implemented as something brand new to
> PHP, like say Traits were, I'd agree that we should look to languages
> like Java and C# for syntax ideas. But since a lot of people have
> already invented annotations using docblocks, and since docblocks are
> already supported by the reflection classes, I'm not convinced of why we
> shouldn't just carry on down that route.

Thanks Rowan ... that just about sums it up better than I did ...

-- 
Lester Caine - G8HFL
-
Contact - http://lsces.co.uk/wiki/?page=contact
L.S.Caine Electronic Services - http://lsces.co.uk
EnquirySolve - http://enquirysolve.com/
Model Engineers Digital Workshop - http://medw.co.uk
Rainbow Digital Media - http://rainbowdigitalmedia.co.uk

-- 
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php

Re: [PHP-DEV] Native Annotation Syntax

[Pedro Cordeiro]

2015-11-25 13:47 GMT-02:00 Lester Caine :

> Any new system would require
> every third party tool to be adapted to use it
>

That's not true at all. A new syntax would in no way invalidate parsing
annotations from docblocks.

The only legacy code that is supported by IDEs (if they are, PHPStorm will
not hint/autocomplete, nor will eclipse/netbeans) would be
Symfony2/Doctrine2. There are tons of other tools that with custom
annotations (JMSSerializer as an example) that do not have any support at
all.

This argument is so flawed that you didn't consider that there are many
parsers with many different syntaxes (
https://github.com/jan-swiecki/php-simple-annotations,
https://github.com/nette/neon) and that ANY implementation, be it through
docblocks or with a native syntax would require a rewrite anyway for many
projects if those tools want to support the new native feature.

Also, doing it through an extension is a nice way to delay adoption,
because shared hosts rarely give the option to install new extensions.

I don't have a vote here, but if I had, I'd strongly oppose any
docblock-based implementation.

Re: [PHP-DEV] Native Annotation Syntax

[Rowan Collins]

Larry Garfield wrote on 25/11/2015 17:06:
Too, it means that a given annotation directive may have spurious * 
characters inside its string, if it's multi-line.  Sure, that can be 
filtered out (Doctrine already does), but that's one more complication 
to have to consider. 


I would expect that behaviour would be part of the standard definition, 
and the core implementation, so don't really see it as a big deal. The 
same thing happens with leading whitespace in many syntaxes anyway.


--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php

Re: [PHP-DEV] Native Annotation Syntax

[Lester Caine]

On 25/11/15 11:04, Pedro Cordeiro wrote:
> I feel like this is a major feature that's missing, and people are using it
> in a suboptimal way (docblocks), so I thought I'd reopen the discussion and
> see if someone more familiar with the internals feels like implementing it

In previous discussions it was pointed out that a substantial amount of
legacy code already uses docblock style annotation, and that is well
supported by IDE's and other tools, so there is no reason not it
continue to support that substantial base. Any new system would require
every third party tool to be adapted to use it was there any reason to
load the code base with something which will only have a limited uptake.
Adding an extension to provide an alternative would be the correct way
forward, and then if that gains traction, look to it's status then.

-- 
Lester Caine - G8HFL
-
Contact - http://lsces.co.uk/wiki/?page=contact
L.S.Caine Electronic Services - http://lsces.co.uk
EnquirySolve - http://enquirysolve.com/
Model Engineers Digital Workshop - http://medw.co.uk
Rainbow Digital Media - http://rainbowdigitalmedia.co.uk

-- 
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php

Re: [PHP-DEV] Native Annotation Syntax

[Pedro Cordeiro]

Rowan, even if they are not harder, there is no reason to keep this feature
in docblocks. Even the argument "compatibility with current
implementations" is flawed, because there are many different
implementations (not only doctrine's) with different syntaxes, so any
native option would break SOME implementations.

Docblocks are Documentation Blocks, which is meant for documentation only.

Mixing documentation (@param) with runtime stuff (@manyToMany) is
counter-intuitive and makes the ecosystem harder to learn.

It's also weird that removing comment blocks break an app.

2015-11-25 14:47 GMT-02:00 Rowan Collins :

> Larry Garfield wrote on 25/11/2015 16:42:
>
>> However, doing so would make static checking more difficult; If
>> annotations become a language-native feature, they should be a first-class
>> citizen to make it easier for IDEs to handle.
>>
>
> Could you explain why docblocks are harder to parse than text outside
> docblocks? As far as I know, IDEs *already* parse docblocks, e.g. using
> @param and @return for type analysis, so I don't really see why
> generalising that would be a big problem.
>
>
> --
> PHP Internals - PHP Runtime Development Mailing List
> To unsubscribe, visit: http://www.php.net/unsub.php
>
>

Re: [PHP-DEV] Native Annotation Syntax

[Rowan Collins]

Larry Garfield wrote on 25/11/2015 17:06:
For me, the "sometimes it's code and sometimes it's not, even though 
it looks the same" argument is sufficient to reject docblocks as a 
location for annotations. 


Annotations aren't code, they're metadata, and docblocks already contain 
metadata; it's just that originally, that metadata was targeted at 
generating documentation, rather than generating code, or affecting 
run-time behaviour.


--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php

Re: [PHP-DEV] Native Annotation Syntax

[Larry Garfield]

On 11/25/15 10:47 AM, Rowan Collins wrote:

Larry Garfield wrote on 25/11/2015 16:42:
However, doing so would make static checking more difficult; If 
annotations become a language-native feature, they should be a 
first-class citizen to make it easier for IDEs to handle. 


Could you explain why docblocks are harder to parse than text outside 
docblocks? As far as I know, IDEs *already* parse docblocks, e.g. 
using @param and @return for type analysis, so I don't really see why 
generalising that would be a big problem.


Not being an IDE author I cannot say for certain, so perhaps it's easier 
than I imagine.  However, speaking as a user I would want a robust level 
of static syntax validation of my annotations.  Having robust syntax 
validation show up in *some* parts of my docblock but not others is 
confusing for me as a user; I hypothesize that it would similarly be 
more difficult to selectively treat bits and pieces of the docblock as 
code but not others.  (My current IDE, PHPStorm, parses a docblock to 
validate that it matches the method signature but all it does is tell me 
if the whole thing is valid or not, and if I'm using a "used" class 
name.  It's actually very unhelpful when dealing with complex Doctrine 
annotations like Drupal uses.)


Too, it means that a given annotation directive may have spurious * 
characters inside its string, if it's multi-line.  Sure, that can be 
filtered out (Doctrine already does), but that's one more complication 
to have to consider.


For me, the "sometimes it's code and sometimes it's not, even though it 
looks the same" argument is sufficient to reject docblocks as a location 
for annotations.


--
--Larry Garfield


--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php

Re: [PHP-DEV] Native Annotation Syntax

[Rowan Collins]

Pedro Cordeiro wrote on 25/11/2015 17:04:


2015-11-25 14:53 GMT-02:00 Rowan Collins >:


If it helps, just think of /** ... */ as not being a comment, but
already a first-class piece of syntax.


Except that it won't parse some stuff while parsing some other stuff. 
There was a topic on reddit some time ago with a rant I wrote about 
it, and the community seemed to support the notion that comment 
annotations are bad: 
https://www.reddit.com/r/PHP/comments/1ztstd/rant_it_baffles_me_that_people_think_using/


A very quick response to that rant:

> 1) Some php bytecode compilers (for example, facebook's hiphop) will 
strip your comments. STRIPPING COMMENTS SHOULD NEVER BREAK YOUR APP.


So, let's make sure we treat these as first-class entities not comments, 
and mention it in the language standard (drafted by Facebook, so that 
they can make HHVM maximally conformant) that these MUST NOT be stripped 
by compilers or pre-processors.


> 2) No IDE hints, no IDE syntax checking because, you know, THEY ARE 
COMMENTS. If you think I should download a specific IDE plugin to work 
with Doctrine and another one to work with Symfony and yet another one 
to work in your specific project with your custom annotations, you can 
go F@#$ yourself.


Total strawman: IDEs parse all sorts of information out of docblocks. 
They may not parse annotations *because they're not standardised*, but 
if there were a PSR defining them, I bet the plugin for parsing that 
syntax would soon be bundled with any IDE with decent PHP support.


> 3) Coupling, separation of concerns, encapsulation: having 
@Route("/something") in a controller class is AWFUL.


This appears to be a rant about annotations in general, not the syntax 
used for them.


> 4) Dude, what does "@ManyToMany" do? Oh, ok, and what does "@param" 
do...? HOW THE HELL AM I SUPPOSED TO TELL SOMEONE "oh, this part over 
here is metadata, but this one is just a comment"? How do I distinguish 
between the two of them?


Well, no, they're both metadata, just with different targets - @param is 
targeted at IDEs and documentation generators, @ManyToMany is targeted 
at a run-time hook, or maybe a code-generation one, or, well, anything 
that wants metadata about something.



I'll stop there, because you probably already had this discussion at the 
time, but since you linked...


Regards,
--
Rowan Collins
[IMSoP]

Re: [PHP-DEV] Native Annotation Syntax

[Rowan Collins]

Larry Garfield wrote on 25/11/2015 16:42:
However, doing so would make static checking more difficult; If 
annotations become a language-native feature, they should be a 
first-class citizen to make it easier for IDEs to handle. 


Could you explain why docblocks are harder to parse than text outside 
docblocks? As far as I know, IDEs *already* parse docblocks, e.g. using 
@param and @return for type analysis, so I don't really see why 
generalising that would be a big problem.


--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php

Re: [PHP-DEV] Native Annotation Syntax

[guilhermebla...@gmail.com]

Hi,

I'm the co-author of RFC of Annotations, co-author of Annotations in
docblock which I abandoned for being conceptually wrong and co-author of
Doctrine Annotations.

Comments such as the one from Lester Caine "In previous discussions it was
pointed out that a substantial amount of legacy code already uses docblock
style annotation, and that is well supported by IDE's and other tools, so
there is no reason not it continue to support that substantial base." makes
me very sad, specially because these claimed legacy code using docblocks
were only written that way in first place because Annotations RFC got
"declined".

Yes, I quoted because it actually acquired a lot of positive votes (over
50% of overall voters) even when there was no 2/3, 50% +1, etc criteria,
but that's the feedback I received after bothering a lot of people about
patch's resolution: the majority of long period contributors of PHP voted
against the patch considering it was too complex, with several
modifications to Zend Engine, which lead them to reject as it was. I also
got suggested to implement this support outside of core through a PECL
extension parsing docblock annotations.

If ever any "long term contributor" decided to discuss about potentially
introducing Annotations into PHP core, I'll be the first one to help. Until
them, anything userland guys ask here IMHO is irrelevant.


Regards,


On Wed, Nov 25, 2015 at 12:00 PM, Rowan Collins 
wrote:

> Pedro Cordeiro wrote on 25/11/2015 16:53:
>
>> Rowan, even if they are not harder, there is no reason to keep this
>> feature in docblocks.
>>
>
> Well, I can think of one reason: backwards compatibility. I don't mean
> with current frameworks - as you say, these are not currently standardised,
> so some will need to be adapted whatever is implemented in core - but with
> older versions of PHP.
>
> If we invent new syntax, then any code using that feature must *require*
> the version of PHP that introduces that syntax, because previous versions
> will simply throw a syntax error. There are a few ways around this, such as:
>
> - allowing the annotation to be preceded by // as Sara suggested (or maybe
> #, to make it look like a C pre-processor directive)
> - using some other syntax that is currently a no-op, like ECMAScript's
> wacky "use strict"
>
> But ultimately, these end up having the same disadvantages you're claiming
> for docblocks - they look like things you can delete, or which has some
> other purpose, but are actually vital to the operation of the code.#
>
> I don't feel that strongly in favour of docblocks, but I don't think the
> reasons given against are particularly strong.
>
> Regards,
> --
> Rowan Collins
> [IMSoP]
>
> --
> PHP Internals - PHP Runtime Development Mailing List
> To unsubscribe, visit: http://www.php.net/unsub.php
>
>


-- 
Guilherme Blanco
MSN: guilhermebla...@hotmail.com
GTalk: guilhermeblanco
Toronto - ON/Canada

Re: [PHP-DEV] Native Annotation Syntax

[Rowan Collins]

guilhermebla...@gmail.com wrote on 25/11/2015 17:58:

I can give you a good argument.

opcache.save_comments=0

Make it work.


Simple: remove that configuration variable, and always save doc blocks. 
As mentioned, my view would be that these should no longer be considered 
"comments", but "metadata", and that documentation and core features 
would be altered to reflect this.


Did you think that was a killer argument, or just another thought to 
bring to the discussion? Because I absolutely welcome people adding to 
the list of pros and cons *on either side*, but I object to any attempt 
to shut down the discussion just because people have already made their 
mind up based on some gut feeling.


Regards,
--
Rowan Collins
[IMSoP]

--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php

Re: [PHP-DEV] Native Annotation Syntax

[guilhermebla...@gmail.com]

Hi Rowan,

If you're in a shared hosting, you can't "simply" remove the configuration
variable.
Relying on extensions or configuration flags to support core language
features is very bad. We don't have flags that can turn IF support off for
example, why we would have that for annotations?
I can bring more cons if you want... like how/when to parse "use" calls in
a docblock? I mainly want to address the need of this class:
https://github.com/doctrine/annotations/blob/master/lib/Doctrine/Common/Annotations/TokenParser.php

I've exhausted to death pros and cons of every single part. The biggest
problem of not realizing this is a core feature and pushing so hard to
docblock is that as soon as this is blinded to some people, others will say
"oh, so that doesn't need to be in core and can be a PECL extension". Now
re-read my email from the beginning about shared hosting, you just entered
in an infinite loop.

On Wed, Nov 25, 2015 at 1:50 PM, Pedro Cordeiro 
wrote:

> On top of it, it'd break obfuscators like Zend Guard.
>
> 2015-11-25 15:58 GMT-02:00 guilhermebla...@gmail.com <
> guilhermebla...@gmail.com>:
>
>> I can give you a good argument.
>>
>> opcache.save_comments=0
>>
>> Make it work.
>>
>> On Wed, Nov 25, 2015 at 12:48 PM, Rowan Collins 
>> wrote:
>>
>> > Larry Garfield wrote on 25/11/2015 17:39:
>> >
>> >> On 11/25/15 11:00 AM, Rowan Collins wrote:
>> >>
>> >>> I don't feel that strongly in favour of docblocks, but I don't think
>> the
>> >>> reasons given against are particularly strong.
>> >>>
>> >>> Regards,
>> >>>
>> >>
>> >> If you don't feel strongly in favor of them, why are you trying to
>> make a
>> >> case for them so strongly?  Just for kicks?  We don't need a "devil's
>> >> advocate" at this point in the discussion...
>> >>
>> >>
>> > Hi Larry,
>> >
>> > I don't *feel* strongly in favour or against them, but can see
>> advantages
>> > and disadvantages on both sides. Feeling strongly is not the same as
>> having
>> > a strong argument for your point of view, so just because some people
>> have
>> > expressed strong opinions against, I don't see why I shouldn't challenge
>> > their reasoning, even if that does mean playing devil's advocate.
>> >
>> > Which is better: basing the decision on the gut feeling of a handful of
>> > people who happen to be here now, or basing it on sound reasoning after
>> > thinking through the implications?
>> >
>> > Regards,
>> > --
>> > Rowan Collins
>> > [IMSoP]
>> >
>> > --
>> > PHP Internals - PHP Runtime Development Mailing List
>> > To unsubscribe, visit: http://www.php.net/unsub.php
>> >
>> >
>>
>>
>> --
>> Guilherme Blanco
>> MSN: guilhermebla...@hotmail.com
>> GTalk: guilhermeblanco
>> Toronto - ON/Canada
>>
>
>


-- 
Guilherme Blanco
MSN: guilhermebla...@hotmail.com
GTalk: guilhermeblanco
Toronto - ON/Canada

Re: [PHP-DEV] Native Annotation Syntax

[guilhermebla...@gmail.com]

Ok, so I'll explain why it's not "the same way" as you imagine.

I've heard this many times already so I'll save you keystrokes.
- "Sure, we can do that on docblocks"
- "Based on that, it doesn't need to be part of core and can safely be
implemented as a PECL extension"

IMHO, internals need to stop considering that PECL is a space for beta
testing features, 95% of userland doesn't even know what PECL is.

Now back to business. At parsing level, PHP has its own parser which we
could take advantage of, and though PECL extension would have to create
one. Clearly not the same way.

The closest stage we can start with this at parsed and resolved AST level
(or enter on the dark side of PHP rewriting stuff like xdebug does).
At that stage, we'd already have resolved classnames, but not for those
annotations in docblock, which is a simple block of text so far. We'd also
have to introspect the AST before it pushes to zend_compile, where use
states are vanished and all classes are already string-resolved into their
corresponding FQCN. And we still have to resolve the class names in the
docblocks using USE statements at AST level, we don't even have the
zend_class_entry instances done at that point, because they're only built
later. Not the same way, again.

Considering I've resolved these problems, it starts wit managing these data
structures. At AST level, we don't have the zend_class_entries, but I'd
already be forced to create instances of specific annotation instances. And
also I need to manage keeping my own data structures, cache them through
opcode and also implement/override Reflection data structures to enable
access to specific annotated elements. Still not the same thing.

Now let's enter on logistics of parsing the docblock text. It's multi-lined
and parsing strings like the one I sent you as an example that you ignored
to answer me back replying "it's just the same way" of parsing now need to
be away of line and column location and carefully remove pieces of text
(remember the " * " I commented?), leading to unexpected behavior and
potentially removing user's text, while re2c would already have done for
us. Again, not the same way.

I can't even imagine how can you bindly say the implementation would be the
same or act the same way as a docblock implementation. It's incredibly
complex, error prone and unreliable to be ensured present (well, it'd be an
optional extension, right?) for such an intrinsic to the language data
structure. We didn't make namespaces a PECL extension, we didn't make
traits part of docblocks. I'd argue traits is not widely used too and the
introduced complexity to core was very big. It could easily be solved by
"using traits" through docblocks and general classes too. Why your argument
is applicable to one thing and not the other?


If anyone is really willing to actually discuss true annotations
implementation and behavior in core, I'm here to help. Until then, I'll
keep watching the list.
Ah, and please stop saying "it should be in docblock". This argument is
just bull... to suppress the actual people interested to see this natively
available and just exposes your lack of interest into language improvement.


Regards,

On Wed, Nov 25, 2015 at 5:03 PM, Rowan Collins 
wrote:

> On 25 November 2015 19:02:37 GMT, "guilhermebla...@gmail.com" <
> guilhermebla...@gmail.com> wrote:
> >Hi Rowan,
> >
> >If you're in a shared hosting, you can't "simply" remove the
> >configuration
> >variable.
> >Relying on extensions or configuration flags to support core language
> >features is very bad. We don't have flags that can turn IF support off
> >for
> >example, why we would have that for annotations?
>
> I think you misunderstood: I didn't mean that users would need to turn
> that feature off, I meant that that feature would be removed, and docblocks
> would always be saved.
>
>
> >I can bring more cons if you want... like how/when to parse "use" calls
> >in
> >a docblock
>
> In exactly the same place you'd parse them outside a docblock.
>
> I really don't understand all these arguments about the parsing being
> harder. The only difference is that you're parsing /** @Foo */ instead of
> <> or whatever other syntax anyone comes up with.
>
> Really the only difference is that a docblock means sharing with other
> metadata (directives for generating documentation). Which has the advantage
> of being polyfillable from older versions of PHP, but the disadvantage of
> not being as clearly separated as a new type of syntax. Oh, and the
> perception, right or wrong, that docblocks are "just comments", rather than
> metadata containers, which Drupal's experience may demonstrate is more
> important than a purely rational analysis would suggest.
>
> All the other details about how this or that tool will adapt, how
> whitespace and multiline values should be handled, etc, are going to need
> just as much thought whatever the syntax looks like.
>
> Regards,
>
> --
> Rowan Collins

Re: [PHP-DEV] Native Annotation Syntax

[guilhermebla...@gmail.com]

Hi Rowan,

I'm avoiding drilling down as much as I can to explain every single
decision motivation of the 2010's patch, which hints every time why
docblocks are bad.
Maybe another example may help you to illustrate the problem; all I want is
to add a multi-lined text in an annotation (using your docblock approach):

/**
 * @Documentation\Description("This
 * is
 * multi-lined.")
 */

Or:

/**
 * @Documentation\Description(<<
wrote:

> On 11/25/15 11:48 AM, Rowan Collins wrote:
>
>> Larry Garfield wrote on 25/11/2015 17:39:
>>
>>> On 11/25/15 11:00 AM, Rowan Collins wrote:
>>>
 I don't feel that strongly in favour of docblocks, but I don't think
 the reasons given against are particularly strong.

 Regards,

>>>
>>> If you don't feel strongly in favor of them, why are you trying to make
>>> a case for them so strongly?  Just for kicks?  We don't need a "devil's
>>> advocate" at this point in the discussion...
>>>
>>>
>> Hi Larry,
>>
>> I don't *feel* strongly in favour or against them, but can see advantages
>> and disadvantages on both sides. Feeling strongly is not the same as having
>> a strong argument for your point of view, so just because some people have
>> expressed strong opinions against, I don't see why I shouldn't challenge
>> their reasoning, even if that does mean playing devil's advocate.
>>
>> Which is better: basing the decision on the gut feeling of a handful of
>> people who happen to be here now, or basing it on sound reasoning after
>> thinking through the implications?
>>
>> Regards,
>>
>
> So far, the only argument FOR them is BC with existing practices.
> Everything else I've seen is, I think, ways around the issues that raises.
> However, as has been noted the BC is spurious as it would only be BC with
> one implementation out of several, and we've never polyfiled other
> syntax-level features that I can recall.  (We've polyfilled new functions,
> but that's easy.)
>
> By the same argument, we should have used docblocks for scalar types, too,
> so that they could be polyfilled and be BC with existing practices, and
> those would have even been fairly standardized already.  Someone even made
> that point, IIRC, and it was quickly rejected.
>
> Whereas as a stand-alone syntax, it offers a much better distinction
> between "metadata that affects code execution" and "stuff for humans to
> read" (both for parsers and for humans).  It gives us much more flexibility
> to implement a meaningful API.  It completely avoids the "but comments
> shouldn't be code" question (which is a bigger deal than you'd think; it
> was one of the drivers behind the Backdrop fork of Drupal. I'm not kidding.)
>
> That one of the lead authors of the most widely used comment-based
> annotation system in PHP is arguing what a terrible idea a comment-based
> annotation system is should carry a great deal of weight.
>
> --
> --Larry Garfield
>
>
>
> --
> PHP Internals - PHP Runtime Development Mailing List
> To unsubscribe, visit: http://www.php.net/unsub.php
>
>


-- 
Guilherme Blanco
MSN: guilhermebla...@hotmail.com
GTalk: guilhermeblanco
Toronto - ON/Canada

Re: [PHP-DEV] Native Annotation Syntax

[guilhermebla...@gmail.com]

I can give you a good argument.

opcache.save_comments=0

Make it work.

On Wed, Nov 25, 2015 at 12:48 PM, Rowan Collins 
wrote:

> Larry Garfield wrote on 25/11/2015 17:39:
>
>> On 11/25/15 11:00 AM, Rowan Collins wrote:
>>
>>> I don't feel that strongly in favour of docblocks, but I don't think the
>>> reasons given against are particularly strong.
>>>
>>> Regards,
>>>
>>
>> If you don't feel strongly in favor of them, why are you trying to make a
>> case for them so strongly?  Just for kicks?  We don't need a "devil's
>> advocate" at this point in the discussion...
>>
>>
> Hi Larry,
>
> I don't *feel* strongly in favour or against them, but can see advantages
> and disadvantages on both sides. Feeling strongly is not the same as having
> a strong argument for your point of view, so just because some people have
> expressed strong opinions against, I don't see why I shouldn't challenge
> their reasoning, even if that does mean playing devil's advocate.
>
> Which is better: basing the decision on the gut feeling of a handful of
> people who happen to be here now, or basing it on sound reasoning after
> thinking through the implications?
>
> Regards,
> --
> Rowan Collins
> [IMSoP]
>
> --
> PHP Internals - PHP Runtime Development Mailing List
> To unsubscribe, visit: http://www.php.net/unsub.php
>
>


-- 
Guilherme Blanco
MSN: guilhermebla...@hotmail.com
GTalk: guilhermeblanco
Toronto - ON/Canada

Re: [PHP-DEV] Native Annotation Syntax

[Larry Garfield]

On 11/25/15 11:48 AM, Rowan Collins wrote:

Larry Garfield wrote on 25/11/2015 17:39:

On 11/25/15 11:00 AM, Rowan Collins wrote:
I don't feel that strongly in favour of docblocks, but I don't think 
the reasons given against are particularly strong.


Regards,


If you don't feel strongly in favor of them, why are you trying to 
make a case for them so strongly?  Just for kicks?  We don't need a 
"devil's advocate" at this point in the discussion...




Hi Larry,

I don't *feel* strongly in favour or against them, but can see 
advantages and disadvantages on both sides. Feeling strongly is not 
the same as having a strong argument for your point of view, so just 
because some people have expressed strong opinions against, I don't 
see why I shouldn't challenge their reasoning, even if that does mean 
playing devil's advocate.


Which is better: basing the decision on the gut feeling of a handful 
of people who happen to be here now, or basing it on sound reasoning 
after thinking through the implications?


Regards,


So far, the only argument FOR them is BC with existing practices. 
Everything else I've seen is, I think, ways around the issues that 
raises.  However, as has been noted the BC is spurious as it would only 
be BC with one implementation out of several, and we've never polyfiled 
other syntax-level features that I can recall.  (We've polyfilled new 
functions, but that's easy.)


By the same argument, we should have used docblocks for scalar types, 
too, so that they could be polyfilled and be BC with existing practices, 
and those would have even been fairly standardized already.  Someone 
even made that point, IIRC, and it was quickly rejected.


Whereas as a stand-alone syntax, it offers a much better distinction 
between "metadata that affects code execution" and "stuff for humans to 
read" (both for parsers and for humans).  It gives us much more 
flexibility to implement a meaningful API.  It completely avoids the 
"but comments shouldn't be code" question (which is a bigger deal than 
you'd think; it was one of the drivers behind the Backdrop fork of 
Drupal. I'm not kidding.)


That one of the lead authors of the most widely used comment-based 
annotation system in PHP is arguing what a terrible idea a comment-based 
annotation system is should carry a great deal of weight.


--
--Larry Garfield


--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php

Re: [PHP-DEV] Native Annotation Syntax

[Rowan Collins]

Rowan Collins wrote on 25/11/2015 18:47:

Simple: remove that configuration variable, and always save doc blocks.


Thinking about it, you don't even need to do that, just add a structure 
in the opcache memory layout for the parsed annotations, allowing you to 
accelerate access to those. (Something you'd have to do anyway if the 
syntax was outside the docblock.)


--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php

Re: [PHP-DEV] Native Annotation Syntax

[Larry Garfield]

On 11/25/15 11:00 AM, Rowan Collins wrote:
I don't feel that strongly in favour of docblocks, but I don't think 
the reasons given against are particularly strong.


Regards,


If you don't feel strongly in favor of them, why are you trying to make 
a case for them so strongly?  Just for kicks?  We don't need a "devil's 
advocate" at this point in the discussion...


--
--Larry Garfield


--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php

Re: [PHP-DEV] Native Annotation Syntax

[Pedro Cordeiro]

On top of it, it'd break obfuscators like Zend Guard.

2015-11-25 15:58 GMT-02:00 guilhermebla...@gmail.com <
guilhermebla...@gmail.com>:

> I can give you a good argument.
>
> opcache.save_comments=0
>
> Make it work.
>
> On Wed, Nov 25, 2015 at 12:48 PM, Rowan Collins 
> wrote:
>
> > Larry Garfield wrote on 25/11/2015 17:39:
> >
> >> On 11/25/15 11:00 AM, Rowan Collins wrote:
> >>
> >>> I don't feel that strongly in favour of docblocks, but I don't think
> the
> >>> reasons given against are particularly strong.
> >>>
> >>> Regards,
> >>>
> >>
> >> If you don't feel strongly in favor of them, why are you trying to make
> a
> >> case for them so strongly?  Just for kicks?  We don't need a "devil's
> >> advocate" at this point in the discussion...
> >>
> >>
> > Hi Larry,
> >
> > I don't *feel* strongly in favour or against them, but can see advantages
> > and disadvantages on both sides. Feeling strongly is not the same as
> having
> > a strong argument for your point of view, so just because some people
> have
> > expressed strong opinions against, I don't see why I shouldn't challenge
> > their reasoning, even if that does mean playing devil's advocate.
> >
> > Which is better: basing the decision on the gut feeling of a handful of
> > people who happen to be here now, or basing it on sound reasoning after
> > thinking through the implications?
> >
> > Regards,
> > --
> > Rowan Collins
> > [IMSoP]
> >
> > --
> > PHP Internals - PHP Runtime Development Mailing List
> > To unsubscribe, visit: http://www.php.net/unsub.php
> >
> >
>
>
> --
> Guilherme Blanco
> MSN: guilhermebla...@hotmail.com
> GTalk: guilhermeblanco
> Toronto - ON/Canada
>

Re: [PHP-DEV] Native Annotation Syntax

[Rowan Collins]

Larry Garfield wrote on 25/11/2015 17:39:

On 11/25/15 11:00 AM, Rowan Collins wrote:
I don't feel that strongly in favour of docblocks, but I don't think 
the reasons given against are particularly strong.


Regards,


If you don't feel strongly in favor of them, why are you trying to 
make a case for them so strongly?  Just for kicks?  We don't need a 
"devil's advocate" at this point in the discussion...




Hi Larry,

I don't *feel* strongly in favour or against them, but can see 
advantages and disadvantages on both sides. Feeling strongly is not the 
same as having a strong argument for your point of view, so just because 
some people have expressed strong opinions against, I don't see why I 
shouldn't challenge their reasoning, even if that does mean playing 
devil's advocate.


Which is better: basing the decision on the gut feeling of a handful of 
people who happen to be here now, or basing it on sound reasoning after 
thinking through the implications?


Regards,
--
Rowan Collins
[IMSoP]

--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php

Re: [PHP-DEV] Native Annotation Syntax

[Rowan Collins]

On 25 November 2015 19:02:37 GMT, "guilhermebla...@gmail.com" 
 wrote:
>Hi Rowan,
>
>If you're in a shared hosting, you can't "simply" remove the
>configuration
>variable.
>Relying on extensions or configuration flags to support core language
>features is very bad. We don't have flags that can turn IF support off
>for
>example, why we would have that for annotations?

I think you misunderstood: I didn't mean that users would need to turn that 
feature off, I meant that that feature would be removed, and docblocks would 
always be saved. 


>I can bring more cons if you want... like how/when to parse "use" calls
>in
>a docblock

In exactly the same place you'd parse them outside a docblock.

I really don't understand all these arguments about the parsing being harder. 
The only difference is that you're parsing /** @Foo */ instead of <> or 
whatever other syntax anyone comes up with.

Really the only difference is that a docblock means sharing with other metadata 
(directives for generating documentation). Which has the advantage of being 
polyfillable from older versions of PHP, but the disadvantage of not being as 
clearly separated as a new type of syntax. Oh, and the perception, right or 
wrong, that docblocks are "just comments", rather than metadata containers, 
which Drupal's experience may demonstrate is more important than a purely 
rational analysis would suggest.

All the other details about how this or that tool will adapt, how whitespace 
and multiline values should be handled, etc, are going to need just as much 
thought whatever the syntax looks like.

Regards,

-- 
Rowan Collins
[IMSoP]

-- 
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php

Re: [PHP-DEV] Native Annotation Syntax

[Pedro Cordeiro]

I'd really like to see something outside the docblock. Comment annotations
are a workaround for the lack of native annotations. It makes the
environment hard to learn ("What does @param do? And what does @ManyToMany
do?"), it makes it impossible for IDEs to hint/autocomplete without
project-specific plugins, and adds this odd notion that removing some
comment blocks might break an app (which is just awful).

@beberlei, I had searched through the archives already and couldn't find
the vote. I found the discussion (in which many people advocated for
docblock annotations), but didn't find the vote.

I feel like this is a major feature that's missing, and people are using it
in a suboptimal way (docblocks), so I thought I'd reopen the discussion and
see if someone more familiar with the internals feels like implementing it
(I don't feel confident enough since I've never tried messing with into the
internals).

2015-11-24 22:31 GMT-02:00 Sara Golemon :

> On Tue, Nov 24, 2015 at 11:05 AM, Rowan Collins 
> wrote:
> > At first sight, these seem like details which could be tweaked later, but
> > they make a difference to what syntax to standardise: is the annotation
> name
> > just a string, or a valid class name? is the value of the annotation
> just a
> > string, or a parseable PHP expression? is it more useful to use the de
> facto
> > existing syntax in DocBlocks, or to add a new keyword or operator? etc
> >
> If we're going to use something in the docblock, then I wouldn't want
> it parsed on compilation, but rather have it be an on-demand parse
> while reflecting.  The reason being that there are plenty of
> docblock'd PHP libraries out there using invalid annotations because
> they're not running it through tools to tell them what they got wrong.
> Waiting till they've actually tried to examine it through reflection
> lets us throw an exception on code that cares about it rather than
> preventing code which ignores reflection from running.
>
> I, for one, am a fan of Java style annotations which allow a string
> name plus optional metadata.
>
> @@foo
> class Bar {
>   @@Baz("something", 123, [ 'a', 'b', ''c'])
>   public function qux() { ... }
> }
>
> Though the formality of having to define the annotation as an
> interface is a bit overkill for PHP, the same rules Hack uses would be
> clear and simple enough:
>
> <>
> class Bar {
>   <>
>   public function qux() { ... }
> }
>
> And no, I'm not picky about the parser symbol used...  In fact,
> allowing an optional '//' prefix to annotations might be nice for
> compatibility.
>
> -Sara
>
> --
> PHP Internals - PHP Runtime Development Mailing List
> To unsubscribe, visit: http://www.php.net/unsub.php
>
>

Re: [PHP-DEV] Native Annotation Syntax

[Benjamin Eberlei]

On Tue, Nov 24, 2015 at 5:30 PM, Pedro Cordeiro 
wrote:

> Hello.
>
> I'd been reading some old RFCs recently, and I found two RFCs on the
> subject of annotations, both by Guilherme Blanco. The first one, which
> proposed a native syntax for annotations, is marked as 'declined', and I
> couldn't find a discussion for it anywhere. The second one, which proposes
> retrieving annotation from DocBlocks through reflection is 'inactive', with
> no further explanation.
>
> I'd really like to see native annotation support for PHP that doesn't live
> in comments.
>
> Is there a reason those RFCs were dropped, or was it just lack of interest?
>

There was a vote on the declined one from Guilherme, which was in the old
mailing list style,
you'd have to search the mailing ilst archives to find the thread with the
discussion and voting.

>
> - Pedro.
>

[PHP-DEV] Native Annotation Syntax

[Pedro Cordeiro]

Hello.

I'd been reading some old RFCs recently, and I found two RFCs on the
subject of annotations, both by Guilherme Blanco. The first one, which
proposed a native syntax for annotations, is marked as 'declined', and I
couldn't find a discussion for it anywhere. The second one, which proposes
retrieving annotation from DocBlocks through reflection is 'inactive', with
no further explanation.

I'd really like to see native annotation support for PHP that doesn't live
in comments.

Is there a reason those RFCs were dropped, or was it just lack of interest?

- Pedro.

Re: [PHP-DEV] Native Annotation Syntax

[Rowan Collins]

On 24/11/2015 16:30, Pedro Cordeiro wrote:

I'd been reading some old RFCs recently, and I found two RFCs on the
subject of annotations, both by Guilherme Blanco. The first one, which
proposed a native syntax for annotations, is marked as 'declined', and I
couldn't find a discussion for it anywhere. The second one, which proposes
retrieving annotation from DocBlocks through reflection is 'inactive', with
no further explanation.

I'd really like to see native annotation support for PHP that doesn't live
in comments.

Is there a reason those RFCs were dropped, or was it just lack of interest?


I think one of the stumbling blocks in recent discussions of annotation 
support is just how much support should be provided; off the top of my 
head, this could be:


- a few extra functions in reflection classes to parse the items within 
a docblock (docblocks are already handled in reflection separately from 
normal comments)
- automatic instantiation of a set of standard Annotation objects with 
the text content above

- automatic instantiation of classes based on the annotations provided
- built-in support for applying annotations to the objects they appear 
on, perhaps in the form of full Aspect-Oriented Programming support


At first sight, these seem like details which could be tweaked later, 
but they make a difference to what syntax to standardise: is the 
annotation name just a string, or a valid class name? is the value of 
the annotation just a string, or a parseable PHP expression? is it more 
useful to use the de facto existing syntax in DocBlocks, or to add a new 
keyword or operator? etc


The devil, as ever, is in the detail.

Regards,

--
Rowan Collins
[IMSoP]


--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php

Re: [PHP-DEV] Native Annotation Syntax

[Sara Golemon]

On Tue, Nov 24, 2015 at 11:05 AM, Rowan Collins  wrote:
> At first sight, these seem like details which could be tweaked later, but
> they make a difference to what syntax to standardise: is the annotation name
> just a string, or a valid class name? is the value of the annotation just a
> string, or a parseable PHP expression? is it more useful to use the de facto
> existing syntax in DocBlocks, or to add a new keyword or operator? etc
>
If we're going to use something in the docblock, then I wouldn't want
it parsed on compilation, but rather have it be an on-demand parse
while reflecting.  The reason being that there are plenty of
docblock'd PHP libraries out there using invalid annotations because
they're not running it through tools to tell them what they got wrong.
Waiting till they've actually tried to examine it through reflection
lets us throw an exception on code that cares about it rather than
preventing code which ignores reflection from running.

I, for one, am a fan of Java style annotations which allow a string
name plus optional metadata.

@@foo
class Bar {
  @@Baz("something", 123, [ 'a', 'b', ''c'])
  public function qux() { ... }
}

Though the formality of having to define the annotation as an
interface is a bit overkill for PHP, the same rules Hack uses would be
clear and simple enough:

<>
class Bar {
  <>
  public function qux() { ... }
}

And no, I'm not picky about the parser symbol used...  In fact,
allowing an optional '//' prefix to annotations might be nice for
compatibility.

-Sara

-- 
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php