On parsing annotations in docblocks: please don't.
First of all, there are already plenty of established userland
implementations - so there is really no need for this.
Whatever you decide on in terms of syntax, most likely won't satisfy every
the needs of every userland annotation library, so at least some of them
most likely won't use it. You'd be creating more work for the maintainers
of these frameworks, and they don't standard to gain anything from that
work.
In terms of performance, there is nothing significant to gain here - any
good annotation engine/framework already caches parsed annotations.
On the other hand, I would be interested in having support for actual
annotation syntax (not docblocks) added to PHP. Real annotation syntax
could have benefits over parsing docblocks, starting with the fact that
most of what's currently in docblocks is documentation, and thus not very
interesting at run-time for anything other than documentation generators.
(again, documentation generators already have working parsers, and don't
stand to gain anything significant from switching to a native docblock
parser.) - also mind the fact that docblocks are a loose standard with many
more variations since annotation libraries came around.
The only real downside (in terms of run-time) to adding custom syntax, is
that existing useful annotations (such as @var for property-types) would
not be useful - but in another sense, that's a good thing, because (for the
most part) in existing codebases, these were written as documentation, not
intended for run-time consumption. IDEs and documentation tools can add
support for new annotation syntax, and treat these consistently and code,
which itself can be documented using phpdoc blocks.
I would support and encourage a C# style syntax and behavior, e.g.:
use my\lib\DataType;
[DataType('datetime')]
public $published_date;
In other words, DataType is a class, implementing an interface for
initialization - everything between the parentheses is interpreted
basically the same way as in an array() statement, and is passed to the
annotation instance after construction via an initialization method defined
by the interface.
I could elaborate tons more on this subject, as it's something I have spent
a lot of time researching in different languages, prior to writing my own
annotation library.
It may strike you as odd that someone who implemented an annotation library
based on docblocks is actually against annotations in docblocks - I mainly
chose that option because it was the best option at the time. I'm not a C
programmer, and I do believe that docblocks are the best approach for a
native PHP implementation. For a native implementation, I'd prefer to see a
clear separation between non-functional documentation metadata and
functional annotation objects. While there is some overlap between the two,
much of what is currently written as documentation (for example @var
annotations) could be written as functional annotations when these have a
meaningful purpose. After all, existing code with phpdoc-annotations most
likely was not written with the intent of consuming that metadata at
runtime, unless written for use with an annotation library.
I would be happy to involve myself deeper in this, if others agree and
would like to work on a new RFC.
- Rasmus Schultz
Cof... cof...
https://wiki.php.net/rfc/annotations
Good luck convincing php-src folks.
You'd be my hero.
On parsing annotations in docblocks: please don't.
First of all, there are already plenty of established userland
implementations - so there is really no need for this.Whatever you decide on in terms of syntax, most likely won't satisfy every
the needs of every userland annotation library, so at least some of them
most likely won't use it. You'd be creating more work for the maintainers
of these frameworks, and they don't standard to gain anything from that
work.In terms of performance, there is nothing significant to gain here - any
good annotation engine/framework already caches parsed annotations.On the other hand, I would be interested in having support for actual
annotation syntax (not docblocks) added to PHP. Real annotation syntax
could have benefits over parsing docblocks, starting with the fact that
most of what's currently in docblocks is documentation, and thus not very
interesting at run-time for anything other than documentation generators.
(again, documentation generators already have working parsers, and don't
stand to gain anything significant from switching to a native docblock
parser.) - also mind the fact that docblocks are a loose standard with many
more variations since annotation libraries came around.The only real downside (in terms of run-time) to adding custom syntax, is
that existing useful annotations (such as @var for property-types) would
not be useful - but in another sense, that's a good thing, because (for the
most part) in existing codebases, these were written as documentation, not
intended for run-time consumption. IDEs and documentation tools can add
support for new annotation syntax, and treat these consistently and code,
which itself can be documented using phpdoc blocks.I would support and encourage a C# style syntax and behavior, e.g.:
use my\lib\DataType; [DataType('datetime')] public $published_date;In other words, DataType is a class, implementing an interface for
initialization - everything between the parentheses is interpreted
basically the same way as in an array() statement, and is passed to the
annotation instance after construction via an initialization method defined
by the interface.I could elaborate tons more on this subject, as it's something I have spent
a lot of time researching in different languages, prior to writing my own
annotation library.It may strike you as odd that someone who implemented an annotation library
based on docblocks is actually against annotations in docblocks - I mainly
chose that option because it was the best option at the time. I'm not a C
programmer, and I do believe that docblocks are the best approach for a
native PHP implementation. For a native implementation, I'd prefer to see a
clear separation between non-functional documentation metadata and
functional annotation objects. While there is some overlap between the two,
much of what is currently written as documentation (for example @var
annotations) could be written as functional annotations when these have a
meaningful purpose. After all, existing code with phpdoc-annotations most
likely was not written with the intent of consuming that metadata at
runtime, unless written for use with an annotation library.I would be happy to involve myself deeper in this, if others agree and
would like to work on a new RFC.
- Rasmus Schultz
--
Guilherme Blanco
MSN: guilhermeblanco@hotmail.com
GTalk: guilhermeblanco
Toronto - ON/Canada
I agree with Rasmus on this one.
Userland solutions are enough to support a in-docblock solution today, the
performance gains from making it SPL are too little to matter.
However docblocks are a compromise, and not where these should be.
I do suggest we revive Guilherme's RFC and try once more to arrive at a
"acceptable" syntax. A lot has happened since the last discussion, maybe
this time the usefulness of annotations can be further moved along and we
can get this patch into core.
That would be: https://wiki.php.net/rfc/annotations
Maybe moving more towards the implementation described by Rasmus Schultz.
On Tue, Jan 8, 2013 at 4:42 AM, guilhermeblanco@gmail.com <
guilhermeblanco@gmail.com> wrote:
Cof... cof...
https://wiki.php.net/rfc/annotations
Good luck convincing php-src folks.
You'd be my hero.On parsing annotations in docblocks: please don't.
First of all, there are already plenty of established userland
implementations - so there is really no need for this.Whatever you decide on in terms of syntax, most likely won't satisfy
every
the needs of every userland annotation library, so at least some of them
most likely won't use it. You'd be creating more work for the maintainers
of these frameworks, and they don't standard to gain anything from that
work.In terms of performance, there is nothing significant to gain here - any
good annotation engine/framework already caches parsed annotations.On the other hand, I would be interested in having support for actual
annotation syntax (not docblocks) added to PHP. Real annotation syntax
could have benefits over parsing docblocks, starting with the fact that
most of what's currently in docblocks is documentation, and thus not very
interesting at run-time for anything other than documentation generators.
(again, documentation generators already have working parsers, and don't
stand to gain anything significant from switching to a native docblock
parser.) - also mind the fact that docblocks are a loose standard with
many
more variations since annotation libraries came around.The only real downside (in terms of run-time) to adding custom syntax, is
that existing useful annotations (such as @var for property-types) would
not be useful - but in another sense, that's a good thing, because (for
the
most part) in existing codebases, these were written as documentation,
not
intended for run-time consumption. IDEs and documentation tools can add
support for new annotation syntax, and treat these consistently and
code,
which itself can be documented using phpdoc blocks.I would support and encourage a C# style syntax and behavior, e.g.:
use my\lib\DataType; [DataType('datetime')] public $published_date;In other words, DataType is a class, implementing an interface for
initialization - everything between the parentheses is interpreted
basically the same way as in an array() statement, and is passed to the
annotation instance after construction via an initialization method
defined
by the interface.I could elaborate tons more on this subject, as it's something I have
spent
a lot of time researching in different languages, prior to writing my own
annotation library.It may strike you as odd that someone who implemented an annotation
library
based on docblocks is actually against annotations in docblocks - I
mainly
chose that option because it was the best option at the time. I'm not a C
programmer, and I do believe that docblocks are the best approach for a
native PHP implementation. For a native implementation, I'd prefer to
see a
clear separation between non-functional documentation metadata and
functional annotation objects. While there is some overlap between the
two,
much of what is currently written as documentation (for example @var
annotations) could be written as functional annotations when these have a
meaningful purpose. After all, existing code with phpdoc-annotations most
likely was not written with the intent of consuming that metadata at
runtime, unless written for use with an annotation library.I would be happy to involve myself deeper in this, if others agree and
would like to work on a new RFC.
- Rasmus Schultz
--
Guilherme Blanco
MSN: guilhermeblanco@hotmail.com
GTalk: guilhermeblanco
Toronto - ON/Canada
--
Rafael Dohms
PHP Evangelist and Community Leader
http://doh.ms
http://wwwamsterdamphp.nl
Hi!
First of all, there are already plenty of established userland
implementations - so there is really no need for this.
On the contrary, plenty of implementations means there's a need in this
functionality, and it might be a good idea to have one standard
implementation if it can cover like 80% of use cases.
Whatever you decide on in terms of syntax, most likely won't satisfy every
the needs of every userland annotation library, so at least some of them
most likely won't use it. You'd be creating more work for the maintainers
of these frameworks, and they don't standard to gain anything from that
work.
Since when "it does not satisfy all needs of all users, and some of them
may end up not using it" is an argument for not including functionality?
And how it's more work for maintainers if they just won't use it?
On the other hand, I would be interested in having support for actual
annotation syntax (not docblocks) added to PHP. Real annotation syntax
Can we please not hijack the topic? We discussed annotations many times
already, if you have better proposal than current RFCs please create
your own RFC (or ask one of the current RFC authors for collaboration)
and start a new topic
--
Stanislav Malyshev, Software Architect
SugarCRM: http://www.sugarcrm.com/
(408)454-6900 ext. 227
First of all, there are already plenty of established userland
implementations - so there is really no need for this.On the contrary, plenty of implementations means there's a need in
this
functionality, and it might be a good idea to have one standard
implementation if it can cover like 80% of use cases.
I agree with Stas on this one; I have noticed that there is a real need
to
parse the meta-data from a DocBlock (not just tags, descriptions as
well).
phpDocumentor is an example but other projects benefit from this as
well.
On the contrary, plenty of implementations means there's a need in this
functionality, and it might be a good idea to have one standard
implementation if it can cover like 80% of use cases.
I agree, there is a need in this functionality, but all those userland
implementations were at the first place made because this
functionality was not part of the language. I think docblocks is not
the solution, doc blocks are just comments, and I would expect any
code to work the same way if I remove my comments.
Pierrick
Firstly - many apologizes for not follwoing along, couldn't be near my mail
yesterday (university...). Many apologizes for the long response too ;).
> .
> There is already a similar RFC here :) Maybe it could be good to start
> from this one so that we don't have any duplicated RFC ?
>
> https://wiki.php.net/rfc/annotations-in-docblock
Didn't saw this RFC, it's describes better the idea, yeah. I think that we
should collect the argument we've said in this discussion and merge between
these RFC's. I can do that, in case you dont mind :).
At phpDocumentor we have been working on formalizing the PHPDoc Standard for
> quite some time now and I would ask you to take a look at that and use it
> as
> basis for the parsing of DocBlocks.
>
> You can find the document here:
> https://github.com/phpDocumentor/phpDocumentor2/blob/develop/docs/PSR.md
>
Personally, I think that a built-in parser should cover that. (I'll state
my opinion in this mail).
What about repeated keys? i.e:
>
> @param int $a
> @param string $b
>
> Let's make this clear immediately: an associative array as output is not
> useful.
> That would make it impossible to nest annotations. For example, something
> like following wouldn't work if the output is just arrays:
>
You right, so we can use the ReflectionAnnotation class proposed in the
other RFC (that I missed), which contains key and value. Even sounds more
OO for me.
Annotations have nothing to do with user land documentation, please
> don't go down this discussion again as it will be of no help for this
> topic.
>
That's true. But I wish to state my opinion now: the current annotations
that Doctorine etc. use is a hack. They took the original doc-block style
comments and use them for storing metadata. that's the reason I think that
in case we'll implement some sort of a parser - it should support the
documentation.
Yahav and all,
> Why does this need to be part of Reflection? Seems a rather odd place for
> it IMHO, since it basically hard-codes the functionality into part of the
> core that's not trivially extendable (at least $class->getMethods() is hard
> to override)...
>
> Instead, what about adding a SPL class to parse the comment. Something like
>
> class SplAnnotationParser {
> const PARSE_DEFAULT = 1;
> const PARSE_FUNCTION = 2;
> public function __construct($rules = self::PARSE_DEFAULT);
>
> /**
> * @param string $comment The comment to parse
> * @returns array An array of parsed annotations, pursuant to the
> ruleset used
> public function parseAnnotations($comment);
> }
>
> That way, you'd do:
>
> $parser = new SplAnnotationParser(SplAnnotationParser::PARE_FUNCTION);
> foreach ($class->getMethods() as $method) {
> $annotations = $parser->parseAnnotations($method->getDocComment());
> }
>
> It decouples the implementation, and allows for people to polymorphically
> substitute different parsers for different needs.
>
> Thoughts?
I don't think it should be implemented as SPL feature since it uses the
doc-comment of a specific function. Since we got getDocComment() in the
Reflection extension, it just feel obvious for me that I'd have the
annotations accessors in the related classes too. In addition, in order to
parse a doc-block you should have either the doc-block as string or the
class/method/function etc. In case you wish to perform it from the
class/method etc. - the logic is already well-known for users that they can
reflect their classes using Reflection, so I don't see the reason to add
another layer. In case you wish to use the doc-comment - it's possible ,
but the user most likely need to initialize a Reflection object anyway to
get this doc-comment string...
Hey everybody,
>
> I've been following this list for a while (1-2 years) and this is the
> first message I'm sending.
> In my oppinion, annotations in docblocks are a bit(a lot) hacky and
> making it even worse by adding them to core is not the best idea.
>
> This is how I think annotations have to look like if implemented in
> core (I've taken on of the annotation classes in Doctrine and
> transformed it).
>
> Declaration:
>
> namespace Doctrine\ORM\Mapping;
>
> use SplAnnotation, SplAnnotationInterface;
>
> @Target({'PROPERTY', 'ANNOTATION'})
> class JoinColumn implements SplAnnotation
> {
> @SplAnnotation\String
> private $name;
>
> @SplAnnotation\Boolean
> private $unique;
>
> @SplAnnotation\Mixed
> private $onDelete;
>
> @SplAnnotation\String
> private $referencedColumn = 'id';
> }
>
> Usage:
>
> <?php
>
> use Lib\Mapping\ORM as ORM;
>
> @ORM\Table()
> @ORM\Entity()
> class User {
>
> @ORM\Column(name="name", type="string")
> private $name;
>
> @ORM\OneToMany(targetEntity="
> Group", mappedBy="user")
> @ORM\JoinColumn(onDelete="CASCADE")
> private $groups;
> }
>
> Of course the syntax and interfaces are just an example for you to get
> the concept.
>
> I'm not very familiar with the internals of the language, so if this
> is hard(not really possible) to implement, just ignore it.
> However, I think that parsing annotations as a part of the syntax of
> the language would be much faster (and less of a mess) and reliable
> than
> parsing strings in docblocks.
>
> Bottomline, my idea is:
> A native syntax outside docblocks that doesn't suck :)
>
> Cheers,
> Vladislav
>
On parsing annotations in docblocks: please don't.
>
> First of all, there are already plenty of established userland
> implementations - so there is really no need for this.
>
> Whatever you decide on in terms of syntax, most likely won't satisfy every
> the needs of every userland annotation library, so at least some of them
> most likely won't use it. You'd be creating more work for the maintainers
> of these frameworks, and they don't standard to gain anything from that
> work.
>
> In terms of performance, there is nothing significant to gain here - any
> good annotation engine/framework already caches parsed annotations.
>
> On the other hand, I would be interested in having support for actual
> annotation syntax (not docblocks) added to PHP. Real annotation syntax
> could have benefits over parsing docblocks, starting with the fact that
> most of what's currently in docblocks is documentation, and thus not very
> interesting at run-time for anything other than documentation generators.
> (again, documentation generators already have working parsers, and don't
> stand to gain anything significant from switching to a native docblock
> parser.) - also mind the fact that docblocks are a loose standard with many
> more variations since annotation libraries came around.
>
> The only real downside (in terms of run-time) to adding custom syntax, is
> that existing useful annotations (such as @var for property-types) would
> not be useful - but in another sense, that's a good thing, because (for the
> most part) in existing codebases, these were written as documentation, not
> intended for run-time consumption. IDEs and documentation tools can add
> support for new annotation syntax, and treat these consistently and code,
> which itself can be documented using phpdoc blocks.
>
> I would support and encourage a C# style syntax and behavior, e.g.:
>
> use my\lib\DataType;
>
> [DataType('datetime')]
> public $published_date;
>
> In other words, DataType is a class, implementing an interface for
> initialization - everything between the parentheses is interpreted
> basically the same way as in an array() statement, and is passed to the
> annotation instance after construction via an initialization method defined
> by the interface.
>
> I could elaborate tons more on this subject, as it's something I have spent
> a lot of time researching in different languages, prior to writing my own
> annotation library.
>
> It may strike you as odd that someone who implemented an annotation library
> based on docblocks is actually against annotations in docblocks - I mainly
> chose that option because it was the best option at the time. I'm not a C
> programmer, and I do believe that docblocks are the best approach for a
> native PHP implementation. For a native implementation, I'd prefer to see a
> clear separation between non-functional documentation metadata and
> functional annotation objects. While there is some overlap between the two,
> much of what is currently written as documentation (for example @var
> annotations) could be written as functional annotations when these have a
> meaningful purpose. After all, existing code with phpdoc-annotations most
> likely was not written with the intent of consuming that metadata at
> runtime, unless written for use with an annotation library.
>
> I would be happy to involve myself deeper in this, if others agree and
> would like to work on a new RFC.
>
You're proposing annotations as C# Attributes. I do think that they should
be implemented - but their RFC was declined. I, too, don't think that the
documentations should be used for metadata storage - this is not the reason
it as created for. You do see that though that many well-known and
professional FW and software use it - so I do think that it should be
re-considered (I'd vote for that, but I didn't got the opportunity to
contribute to PHP since almost all RFCs come with a path :( ).
Cof... cof...
>
> https://wiki.php.net/rfc/annotations
>
> Good luck convincing php-src folks.
> You'd be my hero.
>
Mine too ;)
> First of all, there are already plenty of established userland
> > implementations - so there is really no need for this.
>
> On the contrary, plenty of implementations means there's a need in this
> functionality, and it might be a good idea to have one standard
> implementation if it can cover like 80% of use cases.
>
I agree - I think that the implementation should be abstract enough to
allow most implementation to just hook in and add their syntax to them.
That's true. But I wish to state my opinion now: the current
annotations
that Doctorine etc. use is a hack. They took the original doc-block
style
comments and use them for storing metadata. that's the reason I think
that
in case we'll implement some sort of a parser - it should support the
documentation.
If I read this thread correctly then almost everyone agrees that
PHPUnit,
Symfony, ZF, Doctrine, etc, all use annotations in the DocBlock because
there
is no available alternative that enables them to use annotations.
As far as I am concerned I'd separate this topic into a DocBlock parser
(that
might take into account the current state of affairs with DocBlock
Annotations)
and actual Annotation support.
Which ever way the annotation discussion goes; fact is that a lot of
libraries
already use a form of annotations and I believe a DocBlock parser
should at
least take this into account to facilitate existing projects.
Yahav and all,
Why does this need to be part of Reflection? Seems a rather odd
place for
it IMHO, since it basically hard-codes the functionality into part
of the
core that's not trivially extendable (at least $class->getMethods()
is hard
to override)...Instead, what about adding a SPL class to parse the comment.
Something likeclass SplAnnotationParser {
const PARSE_DEFAULT = 1;
const PARSE_FUNCTION = 2;
public function __construct($rules = self::PARSE_DEFAULT);/** * @param string $comment The comment to parse * @returns array An array of parsed annotations, pursuant tothe
ruleset used
public function parseAnnotations($comment);
}That way, you'd do:
$parser = new
SplAnnotationParser(SplAnnotationParser::PARE_FUNCTION);
foreach ($class->getMethods() as $method) {
$annotations =
$parser->parseAnnotations($method->getDocComment());
}It decouples the implementation, and allows for people to
polymorphically
substitute different parsers for different needs.Thoughts?
I don't think it should be implemented as SPL feature since it uses
the
doc-comment of a specific function. Since we got getDocComment() in
the
Reflection extension, it just feel obvious for me that I'd have the
annotations accessors in the related classes too. In addition, in
order to
parse a doc-block you should have either the doc-block as string or
the
class/method/function etc. In case you wish to perform it from the
class/method etc. - the logic is already well-known for users that
they can
reflect their classes using Reflection, so I don't see the reason to
add
another layer. In case you wish to use the doc-comment - it's
possible ,
but the user most likely need to initialize a Reflection object
anyway to
get this doc-comment string...
I disagree with the above, documentation generators are unable to use
the
Reflection library of PHP due to issues with Dynamic Reflection and the
processing of a large amount of files (report on request) with it.
To phpDocumentor and related projects it would be imperative that a
DocBlock parser is available without having to use the Reflection
extension.
As far as I am concerned I'd separate this topic into a DocBlock
parser (that might take into account the current state of affairs with
DocBlock Annotations) and actual Annotation support.
Yup - two different things. Something akin an extension that does your
docblock parsing makes sense to me (perhaps tied up into reflection),
but adding all sorts of weird extra syntax for "pure" annotations...
meh.
Which ever way the annotation discussion goes; fact is that a lot of
libraries already use a form of annotations and I believe a DocBlock
parser should at least take this into account to facilitate existing
projects.
There is a tokenizer for this already that Greg wrote ages ago in pecl:
http://pecl.php.net/package/docblock - why can't that be extended to
parse your style of annotations in docblocks?
cheers,
Derick
--
http://derickrethans.nl | http://xdebug.org
Like Xdebug? Consider a donation: http://xdebug.org/donate.php
twitter: @derickr and @xdebug
Posted with an email client that doesn't mangle email: alpine
There is a tokenizer for this already that Greg wrote ages ago in
pecl:
http://pecl.php.net/package/docblock - why can't that be extended to
parse your style of annotations in docblocks?
To be honest; I haven't had the time yet to learn and apply extension
programming and work / expand on that. I would love for an extension to
come to life or even a core module so that we can all standardize on
it.
As far as I am concerned I am not advocating my personal way or that of
phpDocumentor but of the PHPDoc standard which is above that.
And as a last note to this mail I would like to add that annotations
are
not part of PHPDoc. The draft that I have written will allow for the
annotation syntax (current PHPDoc does not) but actual handling of
annotations will always be out of scope as far as I am concerned.
Hi!
I agree, there is a need in this functionality, but all those userland
implementations were at the first place made because this
functionality was not part of the language. I think docblocks is not
the solution, doc blocks are just comments, and I would expect any
code to work the same way if I remove my comments.
So you never used PHPUnit and never will in the future, right? Maybe so,
but thousands of other people do, and have no problem with directives in
the comments. I think it is time to lay this red herring to rest -
nobody who had any encounter with any of the most popular PHP tools
really expects it.
Stanislav Malyshev, Software Architect
SugarCRM: http://www.sugarcrm.com/
(408)454-6900 ext. 227
I do use PHP Unit and also Doctrine which uses annotations. And I know
that today because there is no native annotations, the implementation
use docblocks so I can not remove them :) But still if I did not know
anything about PHP and that someone was talking to me about comments,
I would expect my code to work even without them.
Pierrick
Hi!
I agree, there is a need in this functionality, but all those userland
implementations were at the first place made because this
functionality was not part of the language. I think docblocks is not
the solution, doc blocks are just comments, and I would expect any
code to work the same way if I remove my comments.So you never used PHPUnit and never will in the future, right? Maybe so,
but thousands of other people do, and have no problem with directives in
the comments. I think it is time to lay this red herring to rest -
nobody who had any encounter with any of the most popular PHP tools
really expects it.Stanislav Malyshev, Software Architect
SugarCRM: http://www.sugarcrm.com/
(408)454-6900 ext. 227
hi Stas,
Hi!
I agree, there is a need in this functionality, but all those userland
implementations were at the first place made because this
functionality was not part of the language. I think docblocks is not
the solution, doc blocks are just comments, and I would expect any
code to work the same way if I remove my comments.So you never used PHPUnit and never will in the future, right? Maybe so,
but thousands of other people do, and have no problem with directives in
the comments. I think it is time to lay this red herring to rest -
nobody who had any encounter with any of the most popular PHP tools
really expects it.
Everyone I talked to who implemented annotations in docblocks did it
as hack because there is no native support. This is not something that
belongs to docblocks. It would be nice if you could take a look at the
c# doc, there are really good concepts there.
Cheers,
Pierre
@pierrejoye | http://blog.thepimp.net | http://www.libgd.org
Exactly. Annotations just don't belong there. Short syntax for arrays got
shut a few times but it finally made it to core. I hope native support will
be revisited at some point.
hi Stas,
On Tue, Jan 8, 2013 at 7:28 PM, Stas Malyshev <smalyshev@sugarcrm.comjavascript:;>
wrote:Hi!
I agree, there is a need in this functionality, but all those userland
implementations were at the first place made because this
functionality was not part of the language. I think docblocks is not
the solution, doc blocks are just comments, and I would expect any
code to work the same way if I remove my comments.So you never used PHPUnit and never will in the future, right? Maybe so,
but thousands of other people do, and have no problem with directives in
the comments. I think it is time to lay this red herring to rest -
nobody who had any encounter with any of the most popular PHP tools
really expects it.Everyone I talked to who implemented annotations in docblocks did it
as hack because there is no native support. This is not something that
belongs to docblocks. It would be nice if you could take a look at the
c# doc, there are really good concepts there.Cheers,
Pierre
@pierrejoye | http://blog.thepimp.net | http://www.libgd.org
Hi!
Everyone I talked to who implemented annotations in docblocks did it
as hack because there is no native support. This is not something that
belongs to docblocks. It would be nice if you could take a look at the
c# doc, there are really good concepts there.
I know why they did it, and we already discussed that stuff in the last
annotation discussion. What I mean here is that presenting it as if the
notion of meaningful comments is completely unheard of in PHP and nobody
expects it is just wrong. Maybe it was so years ago, but it is
definitely not true now - de-facto meaningful comments are the
standard now, and have a lot of use, and nobody with any experience is
surprised by them. Regardless of why is it so, it is a fact.
--
Stanislav Malyshev, Software Architect
SugarCRM: http://www.sugarcrm.com/
(408)454-6900 ext. 227
On Tue, Jan 8, 2013 at 10:37 PM, Stas Malyshev smalyshev@sugarcrm.comwrote:
Hi!
Everyone I talked to who implemented annotations in docblocks did it
as hack because there is no native support. This is not something that
belongs to docblocks. It would be nice if you could take a look at the
c# doc, there are really good concepts there.I know why they did it, and we already discussed that stuff in the last
annotation discussion. What I mean here is that presenting it as if the
notion of meaningful comments is completely unheard of in PHP and nobody
expects it is just wrong. Maybe it was so years ago, but it is
definitely not true now - de-facto meaningful comments are the
standard now, and have a lot of use, and nobody with any experience is
surprised by them. Regardless of why is it so, it is a fact.Stas,
That still does not make it the right place. Annotations went into docblocks
because it was the only place reflection could provide the needed
information at
runtime. Just because we now treat docblocks as 1st class citizens does not
mean annotations should be there.
Does that mean that annotations should be in docblocks and not in core
for the reason of "we all know docblocks exist". I would seriously expect
at the very least a stronger reason. These were some of the ones i heard
before:
- The syntax is crap: this is solvable, let's find the right syntax
- PHP does not need it: i think we have proven the use already, every
major FW has a
implementation of this, there is clearly demand.
So if we are going to get anywhere with this discussion I suggest getting
back to
the original RFC and working on solving the issues instead of discussing
developer folklore.
--
Rafael Dohms
PHP Evangelist and Community Leader
http://doh.ms
http://wwwamsterdamphp.nl
If I read this thread correctly then almost everyone agrees that PHPUnit,
Symfony, ZF, Doctrine, etc, all use annotations in the DocBlock because
there
is no available alternative that enables them to use annotations.
Yes, I understood that too.
As far as I am concerned I'd separate this topic into a DocBlock parser
(that
might take into account the current state of affairs with DocBlock
Annotations)
and actual Annotation support.
I agree.
I disagree with the above, documentation generators are unable to use the
Reflection library of PHP due to issues with Dynamic Reflection and the
processing of a large amount of files (report on request) with it.To phpDocumentor and related projects it would be imperative that a
DocBlock parser is available without having to use the Reflection
extension.
Even so, I think that a pointer to that function should be present in the
Reflection, so even if we got SPL parser, one could access it using
Reflection since it's the obvious way he/she would look for that.
On Tue, Jan 8, 2013 at 11:51 PM, Rafael Dohms listas@rafaeldohms.com.brwrote:
On Tue, Jan 8, 2013 at 10:37 PM, Stas Malyshev <smalyshev@sugarcrm.com
wrote:
Hi!
Everyone I talked to who implemented annotations in docblocks did it
as hack because there is no native support. This is not something that
belongs to docblocks. It would be nice if you could take a look at the
c# doc, there are really good concepts there.I know why they did it, and we already discussed that stuff in the last
annotation discussion. What I mean here is that presenting it as if the
notion of meaningful comments is completely unheard of in PHP and nobody
expects it is just wrong. Maybe it was so years ago, but it is
definitely not true now - de-facto meaningful comments are the
standard now, and have a lot of use, and nobody with any experience is
surprised by them. Regardless of why is it so, it is a fact.Stas,
That still does not make it the right place. Annotations went into
docblocks
because it was the only place reflection could provide the needed
information at
runtime. Just because we now treat docblocks as 1st class citizens does not
mean annotations should be there.Does that mean that annotations should be in docblocks and not in core
for the reason of "we all know docblocks exist". I would seriously expect
at the very least a stronger reason. These were some of the ones i heard
before:
- The syntax is crap: this is solvable, let's find the right syntax
- PHP does not need it: i think we have proven the use already, every
major FW has a
implementation of this, there is clearly demand.So if we are going to get anywhere with this discussion I suggest getting
back to
the original RFC and working on solving the issues instead of discussing
developer folklore.--
Rafael Dohms
PHP Evangelist and Community Leader
http://doh.ms
http://wwwamsterdamphp.nl
I, too, think that we should re-consider using Annotation. This feature
proved itself as usable
My opinion is that we should separate this discussion into two fields which
will get their own RFC:
- We should recreate / reconsider the Annotation feature. It proved itself
as something that developers wish to get, and they mix between abilities
(the ability to write documentation in userland) just to achieve that
because we didn't provided that. - A doc-block parser (in SPL, core or whatever) that can analyze the
doc-comment and separate it. I think that we should still implement this
even if we'll have Annotation because this is a usable feature in PHP that
can give information for writing API's and such. However, in case
Annotations will be implemented - I understand that you may say that my
argument is weak.
Hi internals,
Just like before, people are confusing documentation support with
behavioral support.
No matter what people say, documentation is documentation and code still
behaves the same with and without the comment docblock. When talking about
behavioral marks, removing that piece makes your code crash.
While creating Doctrine Common Annotations, I was forced to add them in the
docblock because there was no way in the language to not place it there.
This is not an excuse to tell everyone now that only because different
tools used docblocks (because of the lack of support), this is now the
standard. It is a hack using the documentation support to add behavioral
support, point made.
Of course it does not invalidate the documentation. Docblocks should still
have a way to be parsed, but that information is static.
I really pushed hard annotations in the past, mainly because I was
foreseeing that many tools would start adopting behavioral support.
Behaviors can be declared by other ways, like XML, YAML or even PHP. But
the fact of bringing things together under different perspectives (read as
aspects) turns a certain piece of code more powerful and informative than
ever.
I wanted to use the term aspects on purpose because that is another subject
that people normally bring in about highly coupled classes. This is
conceptually wrong because if I only want to populate class properties, I
don't even touch other aspects like validation and filtering, so there's no
coupling, since code is used/dependent elsewhere.
Another point that got mentioned in the past was the lack of
standardization of annotations, which would lead different projects a good
portion of time to refactor to accommodate possible new support. Currently,
the status is quite different from 2010.
Now, except phpunit, almost all major projects are pointing to Doctrine
Common Annotations. Some examples are Doctrine itself, Symfony, Zend
Framework, Drupal, PPI, Flow3 and many others that I can bring here. It
does seem to me that language requires this functionality like 2 years ago,
and everyone is paying the price by using a hacked solution that now people
claim it's the standard. No, it's not the standard and it will never be.
What happened is that annotations indeed became a standard in PHP using a
hack due to the lack of support in core and it seems more and more we delay
the inclusion it will get worse to remove this hack because of this
"standardization". I wonder if that was the idea back in 2010, or maybe if
it was due to the lack of knowledge, interest or willingness.
For those still wondering how it could be applied, here are some links:
http://drupal.org/node/1882526
http://docs.doctrine-project.org/projects/doctrine-common/en/latest/reference/annotations.html
https://packages.zendframework.com/docs/latest/manual/en/modules/zend.form.quick-start.html#using-annotations
http://symfony.com/doc/master/book/validation.html
I think we should split this discussion to 2 points. One that details
Annotations support for the language and a second one, as a PECL extension
that add Docblock parsong support.
For Annotations, I recommend that you guys that a look at RFC I created
back in 2010: https://wiki.php.net/rfc/annotations
The docblock one (https://wiki.php.net/rfc/annotations-in-docblock) was
abandoned because I faced different problems that couldn't fix without
requiring a more powerful solution.
So, do you guys wanna discuss again this possible inclusion?
If I read this thread correctly then almost everyone agrees that PHPUnit,
Symfony, ZF, Doctrine, etc, all use annotations in the DocBlock because
there
is no available alternative that enables them to use annotations.Yes, I understood that too.
As far as I am concerned I'd separate this topic into a DocBlock parser
(that
might take into account the current state of affairs with DocBlock
Annotations)
and actual Annotation support.I agree.
I disagree with the above, documentation generators are unable to use the
Reflection library of PHP due to issues with Dynamic Reflection and the
processing of a large amount of files (report on request) with it.To phpDocumentor and related projects it would be imperative that a
DocBlock parser is available without having to use the Reflection
extension.Even so, I think that a pointer to that function should be present in the
Reflection, so even if we got SPL parser, one could access it using
Reflection since it's the obvious way he/she would look for that.On Tue, Jan 8, 2013 at 11:51 PM, Rafael Dohms <listas@rafaeldohms.com.br
wrote:
On Tue, Jan 8, 2013 at 10:37 PM, Stas Malyshev <smalyshev@sugarcrm.com
wrote:
Hi!
Everyone I talked to who implemented annotations in docblocks did it
as hack because there is no native support. This is not something
that
belongs to docblocks. It would be nice if you could take a look at
the
c# doc, there are really good concepts there.I know why they did it, and we already discussed that stuff in the last
annotation discussion. What I mean here is that presenting it as if the
notion of meaningful comments is completely unheard of in PHP and
nobody
expects it is just wrong. Maybe it was so years ago, but it is
definitely not true now - de-facto meaningful comments are the
standard now, and have a lot of use, and nobody with any experience is
surprised by them. Regardless of why is it so, it is a fact.Stas,
That still does not make it the right place. Annotations went into
docblocks
because it was the only place reflection could provide the needed
information at
runtime. Just because we now treat docblocks as 1st class citizens does
not
mean annotations should be there.Does that mean that annotations should be in docblocks and not in core
for the reason of "we all know docblocks exist". I would seriously expect
at the very least a stronger reason. These were some of the ones i heard
before:
- The syntax is crap: this is solvable, let's find the right syntax
- PHP does not need it: i think we have proven the use already, every
major FW has a
implementation of this, there is clearly demand.So if we are going to get anywhere with this discussion I suggest getting
back to
the original RFC and working on solving the issues instead of discussing
developer folklore.--
Rafael Dohms
PHP Evangelist and Community Leader
http://doh.ms
http://wwwamsterdamphp.nlI, too, think that we should re-consider using Annotation. This feature
proved itself as usable
My opinion is that we should separate this discussion into two fields which
will get their own RFC:
- We should recreate / reconsider the Annotation feature. It proved itself
as something that developers wish to get, and they mix between abilities
(the ability to write documentation in userland) just to achieve that
because we didn't provided that.- A doc-block parser (in SPL, core or whatever) that can analyze the
doc-comment and separate it. I think that we should still implement this
even if we'll have Annotation because this is a usable feature in PHP that
can give information for writing API's and such. However, in case
Annotations will be implemented - I understand that you may say that my
argument is weak.
--
Guilherme Blanco
MSN: guilhermeblanco@hotmail.com
GTalk: guilhermeblanco
Toronto - ON/Canada
On Tue, Jan 8, 2013 at 10:37 PM, Stas Malyshev smalyshev@sugarcrm.comwrote:
Everyone I talked to who implemented annotations in docblocks did it
as hack because there is no native support. This is not something that
belongs to docblocks. It would be nice if you could take a look at the
c# doc, there are really good concepts there.I know why they did it, and we already discussed that stuff in the last
annotation discussion. What I mean here is that presenting it as if the
notion of meaningful comments is completely unheard of in PHP and nobody
expects it is just wrong. Maybe it was so years ago, but it is
definitely not true now - de-facto meaningful comments are the
standard now, and have a lot of use, and nobody with any experience is
surprised by them. Regardless of why is it so, it is a fact.That still does not make it the right place.
Huh? Why not? If it's something that everybody does
(docblocks documenting methods/parameters), why change it?
Annotations went into docblocks because it was the only place
reflection could provide the needed information at runtime. Just
because we now treat docblocks as 1st class citizens does not mean
annotations should be there.Does that mean that annotations should be in docblocks and not in core
for the reason of "we all know docblocks exist". I would seriously expect
at the very least a stronger reason. These were some of the ones i heard
before:
- The syntax is crap: this is solvable, let's find the right syntax
Any extra syntax makes the PHP parser more complicated (and arguably
slower). I don't want to have it slower/more complex for some arbitrary
extra syntax just for some weird annotations.
cheers,
Derick
--
http://derickrethans.nl | http://xdebug.org
Like Xdebug? Consider a donation: http://xdebug.org/donate.php
twitter: @derickr and @xdebug
Posted with an email client that doesn't mangle email: alpine
- The syntax is crap: this is solvable, let's find the right syntax
Any extra syntax makes the PHP parser more complicated (and arguably
slower). I don't want to have it slower/more complex for some arbitrary
extra syntax just for some weird annotations.
This is my worry as well. Especially when it comes to opcode cache
support. Most of the patches I see these days completely ignore the
opcode cache side of things which needs to change. For any large
language-level change, any implementation that doesn't also include an
APC diff, or at least a very complete explanation of how it will be
generally supported by opcode caches just isn't complete.
In this case, attaching annotations/properties to classes will
definitely affect APC since we cache classes separately and NOP their
creation out of the op_arrays. So any extra opcodes will have to be
optimized out and the resulting class created and cached correctly.
-Rasmus
Hi,
I agree with you on this point, we should not introduce any new
feature if there is no way to deal with largely used extensions like
apc, xdebug or maybe others. The provided implementation is not
supposed to be final (syntax or internal implementation) and I'm sure
there are many improvements that could be made to make it better and
I'm open to any suggestions. If the implementation and the idea is
considered, I'll be please to work on a patch for APC so that
annotations can be cached and that there is as less performance
decrease as possible (it will at the same time give me the occasion to
look at APC internal). I'll probably need some help but I'm sure this
will not be an issue.
Pierrick
In this case, attaching annotations/properties to classes will
definitely affect APC since we cache classes separately and NOP their
creation out of the op_arrays. So any extra opcodes will have to be
optimized out and the resulting class created and cached correctly.
- The syntax is crap: this is solvable, let's find the right syntax
Any extra syntax makes the PHP parser more complicated (and arguably
slower). I don't want to have it slower/more complex for some arbitrary
extra syntax just for some weird annotations.This is my worry as well. Especially when it comes to opcode cache
support. Most of the patches I see these days completely ignore the
opcode cache side of things which needs to change. For any large
language-level change, any implementation that doesn't also include an
APC diff, or at least a very complete explanation of how it will be
generally supported by opcode caches just isn't complete.
I totally agree. So far people are asking me if apc is 5.4 compatible
as they want to move to 5.4. Lacking support for APC is a real problem
for people to adopt recent versions and with even faster release
cycles we should keep think more about APC when we introduce new
features.
Hi!
Everyone I talked to who implemented annotations in docblocks did it
as hack because there is no native support. This is not something that
belongs to docblocks. It would be nice if you could take a look at the
c# doc, there are really good concepts there.I know why they did it, and we already discussed that stuff in the last
annotation discussion. What I mean here is that presenting it as if the
notion of meaningful comments is completely unheard of in PHP and nobody
expects it is just wrong. Maybe it was so years ago, but it is
definitely not true now - de-facto meaningful comments are the
standard now, and have a lot of use, and nobody with any experience is
surprised by them. Regardless of why is it so, it is a fact.
Just like any feature not implemented and created using php scripts.
That does not mean we have to use the same hacks to provide native
annotations support. Really not.
--
Pierre
@pierrejoye | http://blog.thepimp.net | http://www.libgd.org
I agree with this very much.
In Doctrine we used Docblocks only because its the only means of
implementing something that closely resembles native annotation support. I
would be happy if we would have a Docblock parser in SPL, so that all
libraries can agree on using its syntax, however ultimately its just
missing the point that language level annotations would still be very handy.
greetings,
Benjamin
On Tue, Jan 8, 2013 at 2:46 PM, Pierrick Charron pierrick@webstart.frwrote:
On the contrary, plenty of implementations means there's a need in this
functionality, and it might be a good idea to have one standard
implementation if it can cover like 80% of use cases.I agree, there is a need in this functionality, but all those userland
implementations were at the first place made because this
functionality was not part of the language. I think docblocks is not
the solution, doc blocks are just comments, and I would expect any
code to work the same way if I remove my comments.Pierrick
On the contrary, plenty of implementations means there's a need in
this functionality, and it might be a good idea to have one standard
implementation if it can cover like 80% of use cases.
Good luck with that! I've seen so many different syntaxes for docblock
"annotations" out there that I doubt you can do this.
I agree, there is a need in this functionality, but all those userland
implementations were at the first place made because this
functionality was not part of the language. I think docblocks is not
the solution, doc blocks are just comments, and I would expect any
code to work the same way if I remove my comments.
Actually, docblocks are handled by the parser. And whether "annotations"
come in the form of such a docblock with a specific syntax, or without
with a special new syntax outside of docblocks makes no difference at
all.
And really, nobody can convince me that we would need stuff like:
@MyApp\Acl({
"allow"=@MyApp\Acl\Allow({"john"="read", "joe"="write"}),
"deny"=@OtherApp\Acl\Deny(default="*", log=true)
})
cheers,
Derick
Taken from the Doctrine documentation:
<?php
class User
{
//...
/**
* @ManyToMany(targetEntity="Group")
* @JoinTable(name="User_Group",
* joinColumns={@JoinColumn(name="User_id",
referencedColumnName="id")},
* inverseJoinColumns={@JoinColumn(name="Group_id",
referencedColumnName="id")}
* )
*/
private $groups;
//...
}
Not that I'm a fan of it, but it provides a valid usecase. I'm sure
there are more.
Cheers,
Vladislav
On the contrary, plenty of implementations means there's a need in
this functionality, and it might be a good idea to have one standard
implementation if it can cover like 80% of use cases.Good luck with that! I've seen so many different syntaxes for docblock
"annotations" out there that I doubt you can do this.I agree, there is a need in this functionality, but all those userland
implementations were at the first place made because this
functionality was not part of the language. I think docblocks is not
the solution, doc blocks are just comments, and I would expect any
code to work the same way if I remove my comments.Actually, docblocks are handled by the parser. And whether "annotations"
come in the form of such a docblock with a specific syntax, or without
with a special new syntax outside of docblocks makes no difference at
all.And really, nobody can convince me that we would need stuff like:
@MyApp\Acl({
"allow"=@MyApp\Acl\Allow({"john"="read", "joe"="write"}),
"deny"=@OtherApp\Acl\Deny(default="*", log=true)
})cheers,
Derick
Please, no top posting!!!
Taken from the Doctrine documentation:
<?php
class User
{
//...
/**
* @ManyToMany(targetEntity="Group")
* @JoinTable(name="User_Group",
* joinColumns={@JoinColumn(name="User_id", referencedColumnName="id")},
* inverseJoinColumns={@JoinColumn(name="Group_id", referencedColumnName="id")}
* )
*/
private $groups;
//...
}Not that I'm a fan of it, but it provides a valid usecase. I'm sure
there are more.
Maybe valid, but sticking this into core-syntax seems mental.
cheers,
Derick
http://derickrethans.nl | http://xdebug.org
Like Xdebug? Consider a donation: http://xdebug.org/donate.php
twitter: @derickr and @xdebug
Posted with an email client that doesn't mangle email: alpine
Please, no top posting!!!
Taken from the Doctrine documentation:
<?php
class User
{
//...
/**
* @ManyToMany(targetEntity="Group")
* @JoinTable(name="User_Group",
* joinColumns={@JoinColumn(name="User_id",
referencedColumnName="id")},
* inverseJoinColumns={@JoinColumn(name="Group_id",
referencedColumnName="id")}
* )
*/
private $groups;
//...
}Not that I'm a fan of it, but it provides a valid usecase. I'm sure
there are more.Maybe valid, but sticking this into core-syntax seems mental.
The Doctrine Syntax is verbose, because that is necessary to make up for
the missing compile time support in the language.
The core could easily offer a "simpler" language or one that looks more
like PHP code (array syntax).
If you take a look at annotations by starting with PHP code, instead of
docblocks and the syntax optimized for that use-case you can end up with
something much simpler, see:
The most simple type of annotations is attaching metadata to a class,
method, function, property. In Clojure this is actually done like this at
runtime setting a hashmap to any structure.
In PHP that would be something like:
function foo() {}
$refl = new ReflectionFunction('foo');
$refl->setMetadata(array('foo' => 'bar'));
$refl->getMetadata();
Doctrine Annotations do allow "retrieving" metadata for any structure,
sspecified in docblocks. For seperation we need something the Annotations
RFC defined, a new type of docblock that is executable code wrapped in for
example <> brackets, if this were just PHP code, then we'd have:
<return array('foo' => 'bar'))>
function foo() {}
Now the difference between this syntax, and something resembling "Docblock
Annotations" would mean that the last statement between <> is returned from
the block. With short syntax for arrays we get:
<['foo' => 'bar']>
function foo() {}
Now this is nothing new to learn for anybody, except that <> code for any
structure can be "executed" using $reflection->getMetadata();
And the crazy people (like me) could do more structured things:
use Doctrine\ORM\Mapping AS ORM;
<[new ORM\Entity, new ORM\Table(name="user")]>
class User {}
On Wed, Jan 9, 2013 at 3:48 PM, Benjamin Eberlei kontakt@beberlei.dewrote:
Please, no top posting!!!
Taken from the Doctrine documentation:
<?php
class User
{
//...
/**
* @ManyToMany(targetEntity="Group")
* @JoinTable(name="User_Group",
* joinColumns={@JoinColumn(name="User_id",
referencedColumnName="id")},
* inverseJoinColumns={@JoinColumn(name="Group_id",
referencedColumnName="id")}
* )
*/
private $groups;
//...
}Not that I'm a fan of it, but it provides a valid usecase. I'm sure
there are more.Maybe valid, but sticking this into core-syntax seems mental.
The Doctrine Syntax is verbose, because that is necessary to make up for
the missing compile time support in the language.
The core could easily offer a "simpler" language or one that looks more
like PHP code (array syntax).If you take a look at annotations by starting with PHP code, instead of
docblocks and the syntax optimized for that use-case you can end up with
something much simpler, see:The most simple type of annotations is attaching metadata to a class,
method, function, property. In Clojure this is actually done like this at
runtime setting a hashmap to any structure.
In PHP that would be something like:function foo() {}
$refl = new ReflectionFunction('foo');
$refl->setMetadata(array('foo' => 'bar'));
$refl->getMetadata();Doctrine Annotations do allow "retrieving" metadata for any structure,
sspecified in docblocks. For seperation we need something the Annotations
RFC defined, a new type of docblock that is executable code wrapped in for
example <> brackets, if this were just PHP code, then we'd have:<return array('foo' => 'bar'))>
function foo() {}Now the difference between this syntax, and something resembling "Docblock
Annotations" would mean that the last statement between <> is returned from
the block. With short syntax for arrays we get:<['foo' => 'bar']>
function foo() {}Now this is nothing new to learn for anybody, except that <> code for any
structure can be "executed" using $reflection->getMetadata();And the crazy people (like me) could do more structured things:
use Doctrine\ORM\Mapping AS ORM;
<[new ORM\Entity, new ORM\Table(name="user")]>
class User {}
The last two lines are wrong, must obviously be:
<[new ORM\Entity, new ORM\Table(['name'=>"user"])]>
class User {}
Well, Derick,
And really, nobody can convince me that we would need stuff like:
@MyApp\Acl({
"allow"=@MyApp\Acl\Allow({"john"="read", "joe"="write"}),
"deny"=@OtherApp\Acl\Deny(default="*", log=true)
})cheers,
Derick
that actually worked quite well in an old ZF1 MVC app I developed, and was
easier to read than having to map all things somewhere else :)
I had each method annotated with the roles allowed to access and eventually
with custom ACL rules (nested annotations).
And it is also very useful for validations and forms generated from
classes+metadata.
Marco Pivetta
Hi!
@MyApp\Acl({
"allow"=@MyApp\Acl\Allow({"john"="read", "joe"="write"}),
"deny"=@OtherApp\Acl\Deny(default="*", log=true)
})
I seriously hope it never comes to this in PHP. We're supposed to be
simple language for doing cool stuff on the web, not a serialization
format for ORM metadata. If we can not make it simple and
comprehensible, we better not do it at all (at least on the language
level). There are plenty of ways to store metadata, not everything
should be in the language syntax.
--
Stanislav Malyshev, Software Architect
SugarCRM: http://www.sugarcrm.com/
(408)454-6900 ext. 227
@Stas we've already come to that, and this is a way to store metadata: the
discussion here is just if and how it should get to PHP :)
Marco Pivetta
Pierrick, before update v3 of patch, let's first clarify things that need
to be discussed.
Rasmus, you have no idea how happy you made me for a gentle comment
pointing something we should think before propose a patch instead of on
(sorry for the wording) bitching about the idea.
There're tons of elements that need to be addressed before working on a
patch.
The latest annotations RFC is a small subset of what other languages
support. To a more complete feature-wise, it is required to go to a
previous revision: https://wiki.php.net/rfc/annotations?rev=1302087566
Some of the elements that needs to be considered:
-
Should we support nested annotations?
-
How [Foo()] will be different from new Foo()? If they are not different,
is there an alternative to not bloat lexical parsing? -
How parameters would be injected? Is constructor the only way to inject
parameters? -
How would we handle optional parameters, like [Foo("bar", null, null,
"woo")]? -
Suppose you wanna fix the optional arguments by named parameters, like
[Foo("bar", test="woo")]. Doesn't it diverge with PHP interests of not
supporting parametrized arguments? Should we modify the former or the
later? Personally I'm a fan of named parameters. -
How would we deal with inheritance? Should a method, for example, inherit
the same annotations from parent or not? -
Suppose that you define annotations to fix the inheritance problem, how
would it be? -
How would we cast possible usages of an annotation to only class, method
or property? Using annotations too? -
How would it be the syntax to declare a new annotation?
-
Would it be possible to modify an annotation value using Reflection, for
example? -
How could it be handled on APC to minimize the performance impact?
Let's discuss? Thanks.
@Stas we've already come to that, and this is a way to store metadata: the
discussion here is just if and how it should get to PHP :)Marco Pivetta
--
Guilherme Blanco
MSN: guilhermeblanco@hotmail.com
GTalk: guilhermeblanco
Toronto - ON/Canada
This version of annotations (attributes?) is much more interesting than
the most recent version, but I could see this syntax as being a problem
if it were allowed to apply to plain functions because then the parser
would have difficulty distinguishing from an array. I suppose the same
could be said of applying it to a class.
In essence though, this prior revision is exactly the kind of thing that
I would be interested in if we could get past the parsing issues...
Pierrick, before update v3 of patch, let's first clarify things that need
to be discussed.
Rasmus, you have no idea how happy you made me for a gentle comment
pointing something we should think before propose a patch instead of on
(sorry for the wording) bitching about the idea.There're tons of elements that need to be addressed before working on a
patch.
The latest annotations RFC is a small subset of what other languages
support. To a more complete feature-wise, it is required to go to a
previous revision: https://wiki.php.net/rfc/annotations?rev=1302087566Some of the elements that needs to be considered:
Should we support nested annotations?
How [Foo()] will be different from new Foo()? If they are not different,
is there an alternative to not bloat lexical parsing?How parameters would be injected? Is constructor the only way to inject
parameters?How would we handle optional parameters, like [Foo("bar", null, null,
"woo")]?Suppose you wanna fix the optional arguments by named parameters, like
[Foo("bar", test="woo")]. Doesn't it diverge with PHP interests of not
supporting parametrized arguments? Should we modify the former or the
later? Personally I'm a fan of named parameters.How would we deal with inheritance? Should a method, for example, inherit
the same annotations from parent or not?Suppose that you define annotations to fix the inheritance problem, how
would it be?How would we cast possible usages of an annotation to only class, method
or property? Using annotations too?How would it be the syntax to declare a new annotation?
Would it be possible to modify an annotation value using Reflection, for
example?How could it be handled on APC to minimize the performance impact?
Let's discuss? Thanks.
@Stas we've already come to that, and this is a way to store metadata: the
discussion here is just if and how it should get to PHP :)Marco Pivetta
--
-Clint
Clint,
If you switch from [] to <> everything works like a charm. =)
Everything was working smoothly on version 2. Version 3 was an attempt to
simplify the patch, but removing tons of things that would pop in a few
time if patch was accepted.
Cheers,
This version of annotations (attributes?) is much more interesting than
the most recent version, but I could see this syntax as being a problem if
it were allowed to apply to plain functions because then the parser would
have difficulty distinguishing from an array. I suppose the same could be
said of applying it to a class.In essence though, this prior revision is exactly the kind of thing that I
would be interested in if we could get past the parsing issues...Pierrick, before update v3 of patch, let's first clarify things that need
to be discussed.
Rasmus, you have no idea how happy you made me for a gentle comment
pointing something we should think before propose a patch instead of on
(sorry for the wording) bitching about the idea.There're tons of elements that need to be addressed before working on a
patch.
The latest annotations RFC is a small subset of what other languages
support. To a more complete feature-wise, it is required to go to a
previous revision: https://wiki.php.net/rfc/**annotations?rev=1302087566https://wiki.php.net/rfc/annotations?rev=1302087566Some of the elements that needs to be considered:
Should we support nested annotations?
How [Foo()] will be different from new Foo()? If they are not different,
is there an alternative to not bloat lexical parsing?How parameters would be injected? Is constructor the only way to inject
parameters?How would we handle optional parameters, like [Foo("bar", null, null,
"woo")]?Suppose you wanna fix the optional arguments by named parameters, like
[Foo("bar", test="woo")]. Doesn't it diverge with PHP interests of not
supporting parametrized arguments? Should we modify the former or the
later? Personally I'm a fan of named parameters.How would we deal with inheritance? Should a method, for example,
inherit
the same annotations from parent or not?Suppose that you define annotations to fix the inheritance problem, how
would it be?How would we cast possible usages of an annotation to only class, method
or property? Using annotations too?How would it be the syntax to declare a new annotation?
Would it be possible to modify an annotation value using Reflection, for
example?How could it be handled on APC to minimize the performance impact?
Let's discuss? Thanks.
@Stas we've already come to that, and this is a way to store metadata:
the
discussion here is just if and how it should get to PHP :)Marco Pivetta
--
-Clint
--
Guilherme Blanco
MSN: guilhermeblanco@hotmail.com
GTalk: guilhermeblanco
Toronto - ON/Canada
I'm going to address these question in the proposal I'm working on - once
it's all in writing, I will post for debate.
On Wed, Jan 9, 2013 at 2:57 PM, guilhermeblanco@gmail.com <
guilhermeblanco@gmail.com> wrote:
Should we support nested annotations?
How [Foo()] will be different from new Foo()? If they are not different,
is there an alternative to not bloat lexical parsing?How parameters would be injected? Is constructor the only way to inject
parameters?How would we handle optional parameters, like [Foo("bar", null, null,
"woo")]?Suppose you wanna fix the optional arguments by named parameters, like
[Foo("bar", test="woo")]. Doesn't it diverge with PHP interests of not
supporting parametrized arguments? Should we modify the former or the
later? Personally I'm a fan of named parameters.How would we deal with inheritance? Should a method, for example,
inherit the same annotations from parent or not?Suppose that you define annotations to fix the inheritance problem, how
would it be?How would we cast possible usages of an annotation to only class, method
or property? Using annotations too?How would it be the syntax to declare a new annotation?
Would it be possible to modify an annotation value using Reflection, for
example?How could it be handled on APC to minimize the performance impact?
Hi,
My answer below.
Pierrick, before update v3 of patch, let's first clarify things that need
to be discussed.
Rasmus, you have no idea how happy you made me for a gentle comment
pointing something we should think before propose a patch instead of on
(sorry for the wording) bitching about the idea.There're tons of elements that need to be addressed before working on a
patch.
Oh yeah.
The latest annotations RFC is a small subset of what other languages
support.
Oh yeah.
To a more complete feature-wise, it is required to go to a
previous revision: https://wiki.php.net/rfc/annotations?rev=1302087566[snip]
Let's discuss? Thanks.
What do you think about my proposal:
http://news.php.net/php.internals/64727 ?
Best regards.
--
Ivan Enderlin
Developer of Hoa
http://hoa.42/ or http://hoa-project.net/
PhD. student at DISC/Femto-ST (Vesontio) and INRIA (Cassis)
http://disc.univ-fcomte.fr/ and http://www.inria.fr/
Member of HTML and WebApps Working Group of W3C
http://w3.org/
To summarize:
A native implementation of PHP-DOC block parser for run-time purposes
(annotation libraries) is already available in the Reflection API, and
already goes as deep as it needs to - going beyond simply finding and
extracting the docblocks would make little sense, as every annotation
library has it's own individual syntax, behaviors and features. There may
be a some libraries that could use a native implementation if it happens to
fit their needs, but they most likely won't use it, because (A) they won't
win anything by doing so, and (B) these libraries would become incompatible
with anything other than bleeding-edge PHP.
A native implementation of PHP-DOC parser for offline purposes
(documentation generators) is already available in userland, does the job
fine, and does not rely on the Reflection API (as someone mentioned)
because loading every class in a large codebase is not feasible. If you
provide a separate PHP-DOC parser, these projects most likely won't use it,
because (A) see above and (B) see above.
Who else would need to parse PHP-DOC blocks and why?
Bottom line, who is this feature for, what will they do with it, and most
importantly, why would they use it?
On Tue, Jan 8, 2013 at 3:55 AM, Stas Malyshev smalyshev@sugarcrm.comwrote:
Hi!
First of all, there are already plenty of established userland
implementations - so there is really no need for this.On the contrary, plenty of implementations means there's a need in this
functionality, and it might be a good idea to have one standard
implementation if it can cover like 80% of use cases.Whatever you decide on in terms of syntax, most likely won't satisfy
every
the needs of every userland annotation library, so at least some of them
most likely won't use it. You'd be creating more work for the maintainers
of these frameworks, and they don't standard to gain anything from that
work.Since when "it does not satisfy all needs of all users, and some of them
may end up not using it" is an argument for not including functionality?
And how it's more work for maintainers if they just won't use it?On the other hand, I would be interested in having support for actual
annotation syntax (not docblocks) added to PHP. Real annotation syntaxCan we please not hijack the topic? We discussed annotations many times
already, if you have better proposal than current RFCs please create
your own RFC (or ask one of the current RFC authors for collaboration)
and start a new topic--
Stanislav Malyshev, Software Architect
SugarCRM: http://www.sugarcrm.com/
(408)454-6900 ext. 227
If we had true annotations, its certainly something the engine could put to use... See my previous post in this thread.
-Clint
To summarize:
A native implementation of PHP-DOC block parser for run-time purposes
(annotation libraries) is already available in the Reflection API, and
already goes as deep as it needs to - going beyond simply finding and
extracting the docblocks would make little sense, as every annotation
library has it's own individual syntax, behaviors and features. There may
be a some libraries that could use a native implementation if it happens to
fit their needs, but they most likely won't use it, because (A) they won't
win anything by doing so, and (B) these libraries would become incompatible
with anything other than bleeding-edge PHP.A native implementation of PHP-DOC parser for offline purposes
(documentation generators) is already available in userland, does the job
fine, and does not rely on the Reflection API (as someone mentioned)
because loading every class in a large codebase is not feasible. If you
provide a separate PHP-DOC parser, these projects most likely won't use it,
because (A) see above and (B) see above.Who else would need to parse PHP-DOC blocks and why?
Bottom line, who is this feature for, what will they do with it, and most
importantly, why would they use it?On Tue, Jan 8, 2013 at 3:55 AM, Stas Malyshev smalyshev@sugarcrm.comwrote:
Hi!
First of all, there are already plenty of established userland
implementations - so there is really no need for this.On the contrary, plenty of implementations means there's a need in this
functionality, and it might be a good idea to have one standard
implementation if it can cover like 80% of use cases.Whatever you decide on in terms of syntax, most likely won't satisfy
every
the needs of every userland annotation library, so at least some of them
most likely won't use it. You'd be creating more work for the maintainers
of these frameworks, and they don't standard to gain anything from that
work.Since when "it does not satisfy all needs of all users, and some of them
may end up not using it" is an argument for not including functionality?
And how it's more work for maintainers if they just won't use it?On the other hand, I would be interested in having support for actual
annotation syntax (not docblocks) added to PHP. Real annotation syntaxCan we please not hijack the topic? We discussed annotations many times
already, if you have better proposal than current RFCs please create
your own RFC (or ask one of the current RFC authors for collaboration)
and start a new topic--
Stanislav Malyshev, Software Architect
SugarCRM: http://www.sugarcrm.com/
(408)454-6900 ext. 227
A native implementation of PHP-DOC block parser for run-time purposes
(annotation libraries) is already available in the Reflection API,
There is no DocBlock parser in the Reflection API; you can merely
retrieve the T_DOC_COMMENT token.
and
already goes as deep as it needs to - going beyond simply finding and
extracting the docblocks would make little sense, as every annotation
library has it's own individual syntax, behaviors and features.
There are other types of project that benefit from the parsing of the
actual DocBlock without any support for Annotations. Examples follow
below.
There may
be a some libraries that could use a native implementation if it
happens to
fit their needs, but they most likely won't use it, because (A) they
won't
win anything by doing so, and (B) these libraries would become
incompatible
with anything other than bleeding-edge PHP.
I disagree with this,
A) Said applications and libraries win in the terms of performance and
standardization; this will offer a baseline for IDEs to offer proper
support for descriptions and tags and even more advanced features.
B) This issue arises with any new feature that substitutes or
empowers
a userland functionality and I thus consider it a non-argument.
I am Lead Developer of phpDocumentor and I promise you, I'd use
this.
A native implementation of PHP-DOC parser for offline purposes
(documentation generators) is already available in userland, does the
job
fine, and does not rely on the Reflection API (as someone mentioned)
because loading every class in a large codebase is not feasible. If
you
provide a separate PHP-DOC parser, these projects most likely won't
use it,
because (A) see above and (B) see above.
Performance is key with documentation generators. Since DocBlocks are
the
most prevalent thing in a code base they could win with a core
implementation.
Also, as provided earlier, would standardization benefit the whole
community
that consumes DocBlocks and IDE vendors.
Who else would need to parse PHP-DOC blocks and why?
- WSDL Generators to extract descriptions and type information
- REST API documentation generators for the same reason
- HATEOAS libraries could benefit from the reading of the @uses tag
- Command Line Application frameworks could use the Command class'
description
for their help screen.
And more uses that I cannot think of within a few seconds.
But I can add more.
Filtering
Validation
Form declaration
Database mapping
Joinpoint definitions (AOP)
Service Injection (look at FLOW3)
Testing
etc
Basically everything can define constraints or usage of an element,
behavior, process or nature of an element.
Let me give some individual examples:
Constraints: @MinLength, @NotNull
Behavior: @Transactional, @Inject
Process: @Column, @XmlElement, @OneToOne
Nature: @Entity, @Table, @WebService, @TestCase
Makes more sense now?
On Wed, Jan 9, 2013 at 1:01 AM, Mike van Riel mike.vanriel@naenius.comwrote:
A native implementation of PHP-DOC block parser for run-time purposes
(annotation libraries) is already available in the Reflection API,There is no DocBlock parser in the Reflection API; you can merely
retrieve theT_DOC_COMMENTtoken.and
already goes as deep as it needs to - going beyond simply finding and
extracting the docblocks would make little sense, as every annotation
library has it's own individual syntax, behaviors and features.There are other types of project that benefit from the parsing of the
actual DocBlock without any support for Annotations. Examples follow below.There may
be a some libraries that could use a native implementation if it happens
to
fit their needs, but they most likely won't use it, because (A) they won't
win anything by doing so, and (B) these libraries would become
incompatible
with anything other than bleeding-edge PHP.I disagree with this,
A) Said applications and libraries win in the terms of performance and
standardization; this will offer a baseline for IDEs to offer proper
support for descriptions and tags and even more advanced features.
B) This issue arises with any new feature that substitutes or empowers
a userland functionality and I thus consider it a non-argument.
I am Lead Developer of phpDocumentor and I promise you, I'd use this.A native implementation of PHP-DOC parser for offline purposes
(documentation generators) is already available in userland, does the job
fine, and does not rely on the Reflection API (as someone mentioned)
because loading every class in a large codebase is not feasible. If you
provide a separate PHP-DOC parser, these projects most likely won't use
it,
because (A) see above and (B) see above.Performance is key with documentation generators. Since DocBlocks are the
most prevalent thing in a code base they could win with a core
implementation.
Also, as provided earlier, would standardization benefit the whole
community
that consumes DocBlocks and IDE vendors.Who else would need to parse PHP-DOC blocks and why?
- WSDL Generators to extract descriptions and type information
- REST API documentation generators for the same reason
- HATEOAS libraries could benefit from the reading of the @uses tag
- Command Line Application frameworks could use the Command class'
description
for their help screen.And more uses that I cannot think of within a few seconds.
--
--
Guilherme Blanco
MSN: guilhermeblanco@hotmail.com
GTalk: guilhermeblanco
Toronto - ON/Canada