Hi All,
There seems to be a lot of discussion as to syntax for annotations at
the moment. Firstly I'd like to say that I've never delved into PHP
internals so may not understand some of the reasons why some of my
suggestions may not work, so please don't give me a hard time about it!
I also have no experience with using annotations in any language per
se. This is just the viewpoints of an observer of this discussion.
There seem to be the following concerns:
1. Use of ! or % as a an annotation separator would conflict.
2. Use of [] would prevent the use of them as a shorthand for array()
3. Many other languages use @, but that is the PHP silence operator.
4. Annotations need their own construct and phpdoc won't suit.
I had a few options to try and address all of these:
1. Use a comment-like syntax. phpdoc uses /** */, so perhaps trying
something like /*! */ or /*@ */ could be answer. If this special
comment was parsed and treated differently to a standard comment then
you could also use any syntax you'd like to define for annotations
without worrying about conflicts with PHP. (I realise that PHP does not
know anything about phpdoc tags.) The above are suitable if annotations
will be allowed to span multiple lines. Otherwise some other single
line comment syntax could be suitable: //@ or #...@. One complaint about
this might be the confusion of excess comments.
An advantage is that if annotations are disabled PHP will just skip over
a comment while parsing, or, if an older version of PHP is in use, this
is backward-compatible code. A disadvantage is that people don't think
of comments as being able to affect code.
class DatabaseObject {
/**
* A function that does something to the database object...
*/
/*!
* JoinTable(array(
* 'name' => 'users_phonenumbers',
* 'joinColumns' => array(
* array('name' => 'user_id', 'referencedColumnName' => 'id'),
* ),
* 'inverseJoinColumns' => array(
* array('name' => 'phonenumber_id', 'referencedColumnName' => 'id',
* 'unique' => true),
* ))
*/
public function something() { ... }
}
class Mailer {
/**
* Send e-mail to a single e-mail address.
*
* @param string $email An e-mail address.
*/
#@ EmailValidation(array('options' => array('checkMX' => true))
public function sendEmail($email) { ... }
}
2. If there is a problem with it being a comment, why not just tweak the
delimiters slightly? Surely if /* */ can be used for comments something
like /+ +/ can't be any more awkward? Same advantage in that you could
switch to a different parsing context and perhaps we can leave [] in the
eventuality they get implemented as a shorthand for array().
Alternatively why not try /[ ]/?
class Mailer {
/**
* Send e-mail to a single e-mail address.
*
* @param string $email An e-mail address.
*/
/+
+ EmailValidation(array('options' => array('checkMX' => true))
+/
public function sendEmail($email) { ... }
}
class Mailer {
/**
* Send e-mail to a single e-mail address.
*
* @param string $email An e-mail address.
*/
/[ EmailValidation(array('options' => array('checkMX' => true)) ]/
public function sendEmail($email) { ... }
}
Anyway. Just some thoughts.
Cheers,
Nick
On 12/09/10 09:30, Christian Kaps wrote:
Hi Stas,
this type of annotations cannot be used as PHPDoc annotations due its
different syntax. In other languages like Java, C# or AS3 annotations
are an independent language construct and I think in PHP it should be
the same. I dont know how many non-performant user-land
implementations(hacks), with different syntaxes and concepts, exists in
the meantime. So I think it is time for a consistent syntax in the PHP
core.
I see your concerns about the inconsistency in the syntax, so here are
my thoughts how we can avoid this.
1. In Java annotations are a special type of an interface. But due the
lack of type hinting for scalar values we cannot use this construct,
because we cannot put some validation logic in an interface. My proposal
is to create a new "annotation" type. This type should have the same
rules as a class and should contain all features proposed in the
ReflectionAnnotation class. With this construct it should be possible to
use named or unnamed parameters for an annotation.
annotation URL {
public $url;
public $title;
public $target;
public function __construct($url, $title, $target = 'self') {
}
}
[URL('http://www.php.net',<http://www.php.net%27,> 'PHP', 'blank')] or
[URL('http://www.php.net',<http://www.php.net%27,> 'PHP')] or
[URL('url' = 'http://www.php.net',<http://www.php.net%27,> 'name' = 'PHP',
'target' = 'blank')]
With this new type there exists a new language construct which doesn't
overlap with the class construct. So it is possible to use its own
instantiation syntax.
2. The syntax for arrays should be the same as in PHP. So we can use the
[] as annotation separator. When we allow expressions in the form
Annotation(array('value' => 4 %2)) or Annotation(array('value' =>
!MY_CONSTANT)) which I think is a valid construct, then we cannot use
the ! or % as annotation separator.
3. For the consistency with named parameters there exists 2
possibilities. Either we implement named parameters in the PHP core or
named parameters are an exception for annotations.
I think with this changes we have a separate language construct like
traits, which does allow a new syntax.
Greetings,
Christian
Am 12.09.2010 00:48, schrieb Stas Malyshev:
Hi!
It seems that there is a misunderstanding about the goals of the
annotations. They are not meant to be read by human being
(javadoc/phpdoc/etc. are) but to be parsed automatically to be used
for services.
If it's for services/phpdoc, why can't it be part of phpdoc?
I see here a whole new language syntax being invented, complete with
nested constructs, new instantiation syntax, new argument parsing
rules and what not. All that while tiniest attempts on introducing
syntax sugar were consistently rejected. But here we have sub-section
of language with totally different rules - PHP has no named
parameters, but annotations have them, PHP has no array/instantiation
shortcut syntax, but annotations have it, etc. Please understand, I'm
not objecting to a particular detail of syntax - I'm objecting to the
fact that the design of the language appears to be guided by a random
whim.
--
PHP Internals - PHP Runtime Development Mailing List
To unsubscribe, visit: http://www.php.net/unsub.php
