FAQ
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.

Search Discussions

  • Benjamin Eberlei at Nov 24, 2015 at 4:40 pm

    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.
  • Rowan Collins at Nov 24, 2015 at 7:06 pm

    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]
  • Sara Golemon at Nov 25, 2015 at 12:31 am

    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:

    <<foo>>
    class Bar {
       <<Baz("something", 123, [ 'a', 'b', 'c'])>>
       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
  • Pedro Cordeiro at Nov 25, 2015 at 11:04 am
    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 <pollita@php.net>:
    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:

    <<foo>>
    class Bar {
    <<Baz("something", 123, [ 'a', 'b', 'c'])>>
    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
  • Lester Caine at Nov 25, 2015 at 3:48 pm

    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
  • Pedro Cordeiro at Nov 25, 2015 at 4:31 pm

    2015-11-25 13:47 GMT-02:00 Lester Caine <lester@lsces.co.uk>:

    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.
  • Larry Garfield at Nov 25, 2015 at 4:42 pm

    On 11/25/15 10:31 AM, Pedro Cordeiro wrote:
    2015-11-25 13:47 GMT-02:00 Lester Caine <lester@lsces.co.uk>:
    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
  • Rowan Collins at Nov 25, 2015 at 4:48 pm

    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.
  • Pedro Cordeiro at Nov 25, 2015 at 4:53 pm
    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 <rowan.collins@gmail.com>:
    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
  • Rowan Collins at Nov 25, 2015 at 5:01 pm

    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]
  • Guilhermeblanco at Nov 25, 2015 at 5:34 pm
    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: guilhermeblanco@hotmail.com
    GTalk: guilhermeblanco
    Toronto - ON/Canada
  • Larry Garfield at Nov 25, 2015 at 5:39 pm

    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
  • Rowan Collins at Nov 25, 2015 at 5:49 pm

    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]
  • Guilhermeblanco at Nov 25, 2015 at 5:59 pm
    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: guilhermeblanco@hotmail.com
    GTalk: guilhermeblanco
    Toronto - ON/Canada
  • Rowan Collins at Nov 25, 2015 at 6:48 pm

    guilhermeblanco@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]
  • Rowan Collins at Nov 25, 2015 at 6:50 pm

    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.)
  • Pedro Cordeiro at Nov 25, 2015 at 6:50 pm
    On top of it, it'd break obfuscators like Zend Guard.

    2015-11-25 15:58 GMT-02:00 guilhermeblanco@gmail.com <
    guilhermeblanco@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: guilhermeblanco@hotmail.com
    GTalk: guilhermeblanco
    Toronto - ON/Canada
  • Guilhermeblanco at Nov 25, 2015 at 7:03 pm
    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 guilhermeblanco@gmail.com <
    guilhermeblanco@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 <rowan.collins@gmail.com>
    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: guilhermeblanco@hotmail.com
    GTalk: guilhermeblanco
    Toronto - ON/Canada

    --
    Guilherme Blanco
    MSN: guilhermeblanco@hotmail.com
    GTalk: guilhermeblanco
    Toronto - ON/Canada
  • Rowan Collins at Nov 25, 2015 at 10:03 pm

    On 25 November 2015 19:02:37 GMT, "guilhermeblanco@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 <<Foo>> 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]
  • Guilhermeblanco at Nov 26, 2015 at 1:14 am
    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, "guilhermeblanco@gmail.com" <
    guilhermeblanco@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
    <<Foo>> 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

    --
    Guilherme Blanco
    MSN: guilhermeblanco@hotmail.com
    GTalk: guilhermeblanco
    Toronto - ON/Canada
  • Rowan Collins at Nov 26, 2015 at 10:07 am

    guilhermeblanco@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]
  • Pedro Cordeiro at Nov 26, 2015 at 11:46 am
    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 <rowan.collins@gmail.com>:
    guilhermeblanco@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
  • Rowan Collins at Nov 26, 2015 at 2:54 pm
    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]
  • Pedro Cordeiro at Nov 26, 2015 at 4:02 pm
    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.
  • Levi Morrison at Nov 26, 2015 at 2:51 pm

    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.
  • Guilhermeblanco at Nov 26, 2015 at 3:15 pm
    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: guilhermeblanco@hotmail.com
    GTalk: guilhermeblanco
    Toronto - ON/Canada
  • Rowan Collins at Nov 26, 2015 at 3:54 pm

    guilhermeblanco@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&safe=active&hl=en&source=lnt&tbs=cdr%3A1%2Ccd_min%3A%2Ccd_max%3A12%2F31%2F2007&tbm=#safe=active&hl=en&tbs=cdr:1%2Ccd_max:12%2F31%2F2007&q=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]
  • Guilhermeblanco at Nov 26, 2015 at 4:05 pm
    Ok then. I'll pretend that lack of interest didn't happen many other
    situations (like http://marc.info/?t=144608767800001) 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:

    guilhermeblanco@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&safe=active&hl=en&source=lnt&tbs=cdr%3A1%2Ccd_min%3A%2Ccd_max%3A12%2F31%2F2007&tbm=#safe=active&hl=en&tbs=cdr:1%2Ccd_max:12%2F31%2F2007&q=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: guilhermeblanco@hotmail.com
    GTalk: guilhermeblanco
    Toronto - ON/Canada
  • Chris Riley at Nov 26, 2015 at 4:58 pm

    On 26 November 2015 at 16:05, guilhermeblanco@gmail.com wrote:

    Ok then. I'll pretend that lack of interest didn't happen many other
    situations (like http://marc.info/?t=144608767800001) 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:

    guilhermeblanco@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&safe=active&hl=en&source=lnt&tbs=cdr%3A1%2Ccd_min%3A%2Ccd_max%3A12%2F31%2F2007&tbm=#safe=active&hl=en&tbs=cdr:1%2Ccd_max:12%2F31%2F2007&q=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: guilhermeblanco@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/)
  • Guilhermeblanco at Nov 26, 2015 at 5:19 pm
    Answers inline
    On Thu, Nov 26, 2015 at 11:58 AM, Chris Riley wrote:


    On 26 November 2015 at 16:05, guilhermeblanco@gmail.com <
    guilhermeblanco@gmail.com> wrote:
    Ok then. I'll pretend that lack of interest didn't happen many other
    situations (like http://marc.info/?t=144608767800001) 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 <rowan.collins@gmail.com>
    wrote:
    guilhermeblanco@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&safe=active&hl=en&source=lnt&tbs=cdr%3A1%2Ccd_min%3A%2Ccd_max%3A12%2F31%2F2007&tbm=#safe=active&hl=en&tbs=cdr:1%2Ccd_max:12%2F31%2F2007&q=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: guilhermeblanco@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: guilhermeblanco@hotmail.com
    GTalk: guilhermeblanco
    Toronto - ON/Canada
  • Rowan Collins at Nov 26, 2015 at 4:58 pm

    guilhermeblanco@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=144608767800001) 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.
  • Levi Morrison at Nov 26, 2015 at 5:11 pm

    On Thu, Nov 26, 2015 at 9:57 AM, Rowan Collins wrote:
    guilhermeblanco@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=144608767800001) 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?
  • Pedro Cordeiro at Nov 26, 2015 at 5:16 pm
    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 <levim@php.net>:
    On Thu, Nov 26, 2015 at 9:57 AM, Rowan Collins wrote:
    guilhermeblanco@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=144608767800001) 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
  • Larry Garfield at Nov 25, 2015 at 7:16 pm

    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
  • Guilhermeblanco at Nov 25, 2015 at 7:30 pm
    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(<<<EOF
      * This
      * is
      * multi-lined
      * EOF;)
      */

    Quickly answer me if every line's * should be part of the string or not. If
    not, what about the space after them? How should heredoc work in this case?
    Feel free to detail your answers and provide examples.
    Things are not as simple as it looks, unfortunately... =(
    On Wed, Nov 25, 2015 at 2:16 PM, Larry Garfield 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: guilhermeblanco@hotmail.com
    GTalk: guilhermeblanco
    Toronto - ON/Canada
  • Larry Garfield at Nov 25, 2015 at 5:07 pm

    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
  • Rowan Collins at Nov 25, 2015 at 5:13 pm

    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.
  • Rowan Collins at Nov 25, 2015 at 5:15 pm

    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.
  • Rowan Collins at Nov 25, 2015 at 4:54 pm

    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]
  • Lester Caine at Nov 25, 2015 at 5:04 pm

    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
  • Rowan Collins at Nov 25, 2015 at 5:11 pm

    Pedro Cordeiro wrote on 25/11/2015 17:04:
    2015-11-25 14:53 GMT-02:00 Rowan Collins <rowan.collins@gmail.com

    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]

Related Discussions

Discussion Navigation
viewthread | post
Discussion Overview
groupphp-internals @
categoriesphp
postedNov 24, '15 at 4:30p
activeNov 26, '15 at 5:19p
posts42
users9
websitephp.net

People

Translate

site design / logo © 2018 Grokbase