[RFC] PHP Attributes View as Markdown

On Thu, Apr 21, 2016 at 11:52 PM, Larry Garfield larry@garfieldtech.com
wrote:

Hi,

I would like to present an RFC proposing support for native annotation.

The naming, syntax and behavior are mostly influenced by HHVM Hack, but
not exactly the same.

The most interesting difference is an ability to use arbitrary PHP
expressions as attribute values.

These expressions are not evaluated, but stored as Abstract Syntax Trees,
and later may be accessed (node by node) in PHP extensions, preprocessors
and PHP scripts their selves. I think this ability may be useful for
"Design By Contract", other formal verification systems, Aspect Oriented
Programming, etc

https://wiki.php.net/rfc/attributes

Note that this approach is going to be native, in contrast to doc-comment
approach that uses not well defined syntax, and even not parsed by PHP
itself.

Additional ideas, endorsement and criticism are welcome.

Thanks. Dmitry.

Thanks, Dmitry! In concept I am in favor of syntax-native annotations,
although I have some concerns with the specifics of the proposal. Thoughts
in no particular order:

First, for the getAttributes() reflection method, please oh please don't
return array-or-false. That's horrible. Just return an empty array if
there aren't any, as that makes getAttributes() entirely type safe and
saves all callers from a mandatory if-check. (See
http://www.garfieldtech.com/blog/empty-return-values for more
information.)

The reflection section further indicates that the type of the result is
variable, which means I cannot know in advance if I'm going to get back a
scalar or an array. If we go with this free-form approach, I'd honestly
prefer to always get back an array, even for single value, so that I can
always know the type I'm dealing with. (Since I cannot enforce a given
attribute to be single-value.)

For the expression example:

<<test($a + $b > 0)>>
function foo($a, $b) {
}

It is not at all clear to me what scope the annotation's $a and $b exist
in. Are the they same $a and $b as in the function signature? If so, what
happens if I reflect the function before ever calling it? How can I
evaluate test? Or are they inherited from the global scope at the time of
declaration? (That scares me a great deal.) I don't know what to make of
that at all.

They don't exist in any scope. You get an AST of this expression, what you
do with it is entirely your choosing and you can set the scope/context
yourself.

In the "Attribute syntax" section, the text says the tokens are the left
and right double-angle character, as used for quotations in some European
languages. The rest of the text says it's two left/right carrot
characters, as seen above the comma and period on US keyboards. I'm
assuming the former is just a typo/auto-correct bug.

If I read correctly, the following two would be semantically identical:

<<One, Two>>
function foo() {}

<<One>>
<<Two>>
function foo() {}

Is there a reason you chose the name "attribute" rather than
"annotations", which seems at least in PHP to be the more common term for
this type of declaration?

It appears that the annotations themselves are entirely free-form. At the
risk of expanding the typing debate, this concerns me as then all we're
adding is a new way to parse undocumented, undefined anonymous structs.
How can I say what annotations mean what for my ORM, or routing system, or
whatever? We're back to, essentially, out-of-band documentation of big
anonymous structs (aka associative arrays).

A more robust alternative would be something along the same lines that
Doctrine uses: Make annotations actual classes. To wit:

<<AThing>>
<<AnotherThing('stuff')>>
<<MoreThing(1, 2, 3)>>
function foo($a, $b) { }

Where AThing, AnotherThing, and MoreThing are defined classes, and subject
to namespaces and use statements. Then what gets returned from
getAttributes() is an array consisting of an instance of AThing, an
instance of AnotherThing, and an instance of MoreThing. In this example
we'd just call their constructors with the listed values and let them do as
they will. Doctrine uses named properties in the annotation that maps to
properties on the object, which is even more flexible and self-documenting
although I don't know how feasible that is without opening up the named
properties can of worms globally.

I like that its just arrays, PHP is not exclusively OOP, so making this an
OOP feature doesn't make sense to me.

A library like Doctrine can always add the meaning on top, for example
checking:

<<ORM\Entity>>
class User
{
}

Again resolving this against namespaces for example inside Doctrine
Annotations itself, like its done right now.

Either way, the advantage then is that I know what annotations are
available, and the class itself serves as documentation for what it is,
what it does, and what its options are. It also helps address collisions
if two different libraries both want to use the same keyword; we already
have a class name resolution mechanism that works and everyone is familiar
with.

One concern is that not all classes necessarily make sense as an
annotation; perhaps only classes with a certain interface can be used.
Actually (thinking aloud here), that would be a possible solution to the
named property issue. To wit:

This is why it should be just arrays, using classes suddenly tons of
special things can happen and must be thought of.

<<AThing(a => 'a', b => 'b')>>
foo() {}

class AThing implements Attribute {
public static function attributeCreate(array $params) {
return new static($param['a'], $param['b']);
}
}

$r = new ReflectionFunction('foo');
$a = $r->getAttributes();

$a is now an array of one element, an instance of AThing, created with 'a'
and 'b'. The specifics here are probably terrible, but the general idea of
using classes to define annotations is, I think, a big step forward for
documentation and avoiding multi-library collisions.

While I know some of the things Drupal 8 is using annotations for are
arguably excessive (and I would agree with that argument in some cases), as
is I fear the proposed system is too free-form and rudimentary for Drupal
to switch to them.

You can build any kind of structure on top of $refl->getAttributes() inside
your framework (Drupal in this case)

--
--Larry Garfield

Hi,

I would like to present an RFC proposing support for native annotation.

The naming, syntax and behavior are mostly influenced by HHVM Hack,
but not exactly the same.

The most interesting difference is an ability to use arbitrary PHP
expressions as attribute values.

These expressions are not evaluated, but stored as Abstract Syntax
Trees, and later may be accessed (node by node) in PHP extensions,
preprocessors and PHP scripts their selves. I think this ability may
be useful for "Design By Contract", other formal verification
systems, Aspect Oriented Programming, etc

https://wiki.php.net/rfc/attributes

Note that this approach is going to be native, in contrast to
doc-comment approach that uses not well defined syntax, and even not
parsed by PHP itself.

Additional ideas, endorsement and criticism are welcome.

Thanks. Dmitry.

Thanks, Dmitry! In concept I am in favor of syntax-native
annotations, although I have some concerns with the specifics of the
proposal. Thoughts in no particular order:

First, for the getAttributes() reflection method, please oh please
don't return array-or-false. That's horrible. Just return an empty
array if there aren't any, as that makes getAttributes() entirely type
safe and saves all callers from a mandatory if-check. (See
http://www.garfieldtech.com/blog/empty-return-values for more
information.)
Makes sense. I may change this.

The reflection section further indicates that the type of the result
is variable, which means I cannot know in advance if I'm going to get
back a scalar or an array. If we go with this free-form approach, I'd
honestly prefer to always get back an array, even for single value, so
that I can always know the type I'm dealing with. (Since I cannot
enforce a given attribute to be single-value.)

I'm not sure yet. both decisions may make sense. If I expect just a
single value, I'll have to check the number of elements (or just ignore
values above the first).

For the expression example:

<<test($a + $b > 0)>>
function foo($a, $b) {
}

It is not at all clear to me what scope the annotation's $a and $b
exist in. Are the they same $a and $b as in the function signature?
If so, what happens if I reflect the function before ever calling it?
This is just an AST. It may contain any valid PHP expression syntax, but
variable, functions and constants don't have to be valid.

How can I evaluate test?
I hope this functionality will be provided by php-ast extension.
Currently, it is not a problem to reconstruct PHP source from AST and
then use regular eval().
In general, we may find a more efficient way.

Or are they inherited from the global scope at the time of
declaration? (That scares me a great deal.) I don't know what to
make of that at all.
AST is going to be mainly used by extension and pre-processors (like AOT
and DBC), but in general, they also may be used directly in scripts.

<<test($a + $b > 0)>>
function foo($a, $b) {
ast_eval(RefelectionFunction(FUNCTION)->getAttributes()["test"]);
}

DB
In the "Attribute syntax" section, the text says the tokens are the
left and right double-angle character, as used for quotations in some
European languages. The rest of the text says it's two left/right
carrot characters, as seen above the comma and period on US
keyboards. I'm assuming the former is just a typo/auto-correct bug.

yeah, computers think they are too smart :)

If I read correctly, the following two would be semantically identical:

<<One, Two>>
function foo() {}

<<One>>
<<Two>>
function foo() {}

right

Is there a reason you chose the name "attribute" rather than
"annotations", which seems at least in PHP to be the more common term
for this type of declaration?

I took the name from HHVM. Personally, I don't care about naming at all.

It appears that the annotations themselves are entirely free-form.
no. they are parsed according to PHP expression syntax rules. syntax
mistakes in attributes are going to be caught at compile time.

At the risk of expanding the typing debate, this concerns me as then
all we're adding is a new way to parse undocumented, undefined
anonymous structs. How can I say what annotations mean what for my
ORM, or routing system, or whatever? We're back to, essentially,
out-of-band documentation of big anonymous structs (aka associative
arrays).

A more robust alternative would be something along the same lines that
Doctrine uses: Make annotations actual classes. To wit:

<<AThing>>
<<AnotherThing('stuff')>>
<<MoreThing(1, 2, 3)>>
function foo($a, $b) { }

Where AThing, AnotherThing, and MoreThing are defined classes, and
subject to namespaces and use statements. Then what gets returned
from getAttributes() is an array consisting of an instance of AThing,
an instance of AnotherThing, and an instance of MoreThing. In this
example we'd just call their constructors with the listed values and
let them do as they will. Doctrine uses named properties in the
annotation that maps to properties on the object, which is even more
flexible and self-documenting although I don't know how feasible that
is without opening up the named properties can of worms globally.
This is just a next level. Attributes are just a storage of meta-data.
You may use them as you like :)

function getAttributesAsObjects($r) {
$ret = array();
$a = $r->getAttributes();
foreach ($a as $name => $val) {
$ret[] = new $name(...$val);
}
return $ret;
}

Either way, the advantage then is that I know what annotations are
available, and the class itself serves as documentation for what it
is, what it does, and what its options are. It also helps address
collisions if two different libraries both want to use the same
keyword; we already have a class name resolution mechanism that works
and everyone is familiar with.

One concern is that not all classes necessarily make sense as an
annotation; perhaps only classes with a certain interface can be
used. Actually (thinking aloud here), that would be a possible
solution to the named property issue. To wit:

<<AThing(a => 'a', b => 'b')>>
foo() {}

class AThing implements Attribute {
public static function attributeCreate(array $params) {
return new static($param['a'], $param['b']);
}
}

$r = new ReflectionFunction('foo');
$a = $r->getAttributes();

$a is now an array of one element, an instance of AThing, created with
'a' and 'b'. The specifics here are probably terrible, but the
general idea of using classes to define annotations is, I think, a big
step forward for documentation and avoiding multi-library collisions.

While I know some of the things Drupal 8 is using annotations for are
arguably excessive (and I would agree with that argument in some
cases), as is I fear the proposed system is too free-form and
rudimentary for Drupal to switch to them.

We can't use classes and object in storage directly, because they may be
defined in different PHP script, may be changed between requests, etc.
but as I showed, it's very easy to construct corresponding objects on
request.

Thanks for deep review and good suggestions.

Dmitry.

This is amazing. It would actually allow us to implement our
automated assertions ourselves, as opposed to requiring it within the
language.

this was the idea - to give a good tool instead of implementing every
possible use-case in the language.

Could it also support references?

<<sanitize(&$a)>>
function foo($a) {

}

yes. "&$a" is a valid PHP expression.

If you plan to use this, I would appreciate, if you to build the patched
PHP and try it.
The early we find problems the better feature we will get at the end.

Thanks. Dmitry.

On 21 Apr 2016 10:13 p.m., "Dmitry Stogov" <dmitry@zend.com
mailto:dmitry@zend.com> wrote:

Hi,


I would like to present an RFC proposing support for native
annotation.

The naming, syntax and behavior are mostly influenced by HHVM
Hack, but not exactly the same.

The most interesting difference is an ability to use arbitrary PHP
expressions as attribute values.

These expressions are not evaluated, but stored as Abstract Syntax
Trees, and later may be accessed (node by node) in PHP extensions,
preprocessors and PHP scripts their selves. I think this ability
may be useful for "Design By Contract", other formal verification
systems, Aspect Oriented Programming, etc


https://wiki.php.net/rfc/attributes


Note that this approach is going to be native, in contrast to
doc-comment approach that uses not well defined syntax, and even
not parsed by PHP itself.


Additional ideas, endorsement and criticism are welcome.


Thanks. Dmitry.

I would like to present an RFC proposing support for native annotation.

I'm trying to imagine where the benefit of non-constant expressions comes in.

<<foo($a < 1)>>

Assuming we roll in php-ast at the same time (which is a big addition,
IMO, and deserves its own separate RFC), what are users meant to do
with this? Even if there's a use-case here, one could accomplish the
same thing with:

<<foo('$a < 1')>>

And manually running that string into php-ast if that's what the caller wanted.

Good point. It's really not a big deal to run
ast\parse_code($r->getAttributes()["foo"])
This would simplify the implementation a bit.

Also, maybe I missed it, but I didn't see an answer to the question of
ambiguity between parsing the above as a straight string, versus
parsing it as a ZEND_AST_ZVAL. I'm sure the answer is "If the AST
tree is just a ZVAL, then it's provided as the compile-time
expression, but what about something else like this:

<<foo(1+1)>>

Logically, this is reducible to a single compile-time value, but it's
a complex expression, so would it be the value int(2)? Or
ZEND_AST_BINARY_OP(int(1), int(1))?
Currently this going to be an AST - ZEND_AST_BINARY_OP(int(1), int(1))

I just think that over-engineers what should be a simple annotation feature.

This makes sense. I think, I'll follow your suggestion.
The only missing ability is syntax check for <expression> attribute values.

All that said, I love the proposal overall, and I can't wait to
propose builtin annotations like <<__Memoize>>, <<__Mock>>, and
similar.
I'm looking forward as well. :)

Thanks. Dmitry.

-Sara

All that said, I love the proposal overall, and I can't wait to
propose builtin annotations like <<__Memoize>>, <<__Mock>>, and
similar.

I'd rather see these two functionalities added as modifiers at the
language level instead since they change the code behavior rather
dramatically. Not sure if knowledge of them is of interest in stages
where annotations might not be readily available; this was a driving
factor in Kotlin's decision what becomes a modifier or annotation.[1]

<?php

final class A {

private memoized function f() {}

}

test class B extends A { // OK, despite final.

public function f() {} // Has access to private methods.

}

test class C extends B {} // OK

class D extends B {} // Fatal Error!

?>

I know that this is true for @invariant, @require, and @ensure as
well, they are fully-fledged assertions after all. Especially the
@invariant could be easily added as a magic method.

[assert]
assert.invariants = 1

<?php

final class Object {

public function __invariant() {}

}

?>

Both @require and @ensure are a bit harder to implement at language
level. The following is the best I can come up with and is inspired by
the Eiffel syntax.[2]

[assert]
assert.preconditions = 1
assert.postconditions = 1

<?php

class PreconditionError extends AssertionError {}
class PostconditionError extends AssertionError {}

final class Account {

public function withdraw(int $sum): void {
$this->balance -= $this->balance - $sum;
}
require {
$sum >= 0;
$sum <= ($this->balance - self::MIN_BALANCE);
}
ensure {
$this->balance === (old::$balance - $sum);
}

}

$account = new Account;

$account->withdraw(-10);
/*
Uncaught PreconditionError: $sum >= 0
*/

$account->withdraw(10);
/*
Uncaught PreconditionError: $sum <= ($this->balance - self::MIN_BALANCE)
*/

$account->deposit(10);
$account->withdraw(5);
/*
Uncaught PostconditionError: $this->balance === (old::$balance - $sum)
*/

?>

I actually think now that it would be better to go for this than for
annotations.

[1] http://blog.jetbrains.com/kotlin/2015/08/modifiers-vs-annotations/
[2]
https://archive.eiffel.com/doc/online/eiffel50/intro/language/invitation-07.html

--
Richard "Fleshgrinder" Fussenegger

Hi Dmitry!

Hi,

I would like to present an RFC proposing support for native annotation.

The naming, syntax and behavior are mostly influenced by HHVM Hack, but not exactly the same.

The most interesting difference is an ability to use arbitrary PHP expressions as attribute values.

These expressions are not evaluated, but stored as Abstract Syntax Trees, and later may be accessed (node by node) in PHP extensions, preprocessors and PHP scripts their selves. I think this ability may be useful for "Design By Contract", other formal verification systems, Aspect Oriented Programming, etc

https://wiki.php.net/rfc/attributes

Note that this approach is going to be native, in contrast to doc-comment approach that uses not well defined syntax, and even not parsed by PHP itself.

Additional ideas, endorsement and criticism are welcome.
Just a couple of comments on this:

1. I'd definitely reuse the php-ast extension for parsing the code into an
   AST. It performs a number of transformations on PHP's underlying AST
   that make it much nicer to use (namely better consistency). It is also
   less fragile by having the abstraction between PHP's internal AST and
   the AST that is exposed to userland (enabling for internal AST changes
   without impacting the AST exposed to userland).
   I'm not sure. Both approaches make sense.

2. You mentioned about moving some of the php-ast extension into core.
   I wonder if it would be better to just move the whole extension into the
   core first, and then enable this functionality if the php-ast extension is
   enabled.
   Even if we move php-ast into core (I think we will do it), it's going to
   be optional.
   However attributes should always work.

Also, slightly tangential, but the RFC says attributes are supported on
class constants, yet doc comments (IIRC) are not. I wonder if support
for doc comments should be added for class constants?

it is already implemented.

Thanks. Dmitry.

Thanks,
Tom

+1 for the basic idea, however, I have various remarks.

The RFC text is hard to read and contains many grammatical mistakes. How
could one help you here?
I would need a co-author :)

I think that the Hack name attributes is unintelligible and annotations
would be much clearer to any audience. Simply because the name is very
well known.

Different languages names this differently.
I may add an additional voting question - "annotation vs attributes?".

I do not see the need for multi-annotation nor multi-value support. It
just creates multiple ways to achieve the exact same thing for no good
reason.
completely disagree.
Each value in multi-value attribute may have its own meaning. e.g.
<<if(Condition,OnTrue,OnFalse)>>

I do not like the <<>> syntax. It requires many key strokes, is hard to
read, and looks ugly. Why not simply @ and be done with it. I am not so
sure about the bracket requirement, is it somehow required for the
parsing? Otherwise I would leave it off. I guess it might be hard to
find the end of an annotation but have you considered to use the
semicolon for that? Would align nicely with existing PHP syntax. The
following would be the ABNF for my proposal:

ANNOTATION = "@" NAME [ " " VALUE ]
NAME = STRING
VALUE = QUOTED-STRING / PHP-CONSTANT / EXPRESSION
QUOTED-STRING = ( "'" / DQUOTE ) STRING ( "'" / DQUOTE )
EXPRESSION = PHP-CODE ";"

A semicolon would only be required if it is not a single quoted string
(see following example) or constant. A question that I see unanswered is
how embedding of variables in quoted strings should be dealt with. I see
no need for this but people might assume it is supported because PHP
supports it everywhere else.

<?php

$name = "Richard Fussenegger";
$email = "php@fleshgrinder.com";

@author "{$name} <{$email}>"
class A {}

<<author("{$name} <{$email}>")>>
class B {}

?>

Requiring PHP code to be terminated with a semicolon should also ensure
that people do not start to write fully-fledged programs in annotations.
Since that is not what they are intended for. An alternative approach I
see here would be to go for the brackets but then again only for PHP code:

EXPRESSION = "(" PHP-CODE ")"

Then again, it looks similar to a function call and this is imho not
good. Unless of course new annotations can be defined as special
functions directly in userland, e.g. with an annotation function
and/or annotation class. However, this would require more thought.

Another question that is unanswered for me is: how to go about adding
annotations to a complete file as is currently possible with PhpDoc and
its file-level doc block:

<?php
@author 'Richard Fussenegger php@fleshgrinder.com'
@copyright '2016 Richard Fussenegger'
@license 'MIT'

declare(strict_types=1);

namespace Fleshgrinder\PhpInternals;

@description 'True annotation support could be a very good thing.'
@invariant $this->balance >= self::MIN_BALANCE;
class Account {

private const int MIN_BALANCE = 0;

private int $balance;

private Person $owner;

@require $sum >= 0;
@ensure $this->balance === (old::$balance + $sum);
public function deposit(int $sum): void {
$this->balance += $sum;
}

@require $sum >= 0;
@require $sum <= $this->balance - self::MIN_BALANCE;
@ensure $this->balance === (old::$balance - $sum);
public function withdraw(int $sum): void {
$this->balance -= $sum;
}

@deprecated 'for various reasons'
public function setOwner(Person $wner): void {
$this->owner = $owner;
}

}

@inheritDoc
class OverdraftAccount extends Account {

private const int MIN_BALANCE = -1000;

}

?>
You should try to implement this syntax to understand the problem.
It leads to parse conflicts.

We also need to make sure to add something regarding coding standards
for annotation names. I would propose to go for camelCase (same as for
method names) since this is what PhpDoc used to use for many years now.

This RFC is not going to propose coding standards.

We also need to define how people can avoid to collide with internal
annotations. The typical double-underscore prefix approach that we have
for magic methods creates a lot of visual clutter and looks weird if
spread among all kinds of places. A namespace approach as we have it
already for userland code could help here.

<?php

use Doctrine\ORM;

@ORM::entity
@ORM::table [
'name' => 'user',
'unique_constraints' => [
'name' => 'user_unique',
'columns' => [ 'username' ],
],
'indexes' => [
'name' => 'user_idx',
'clumns' => [ 'email' ],
],
'schema' => 'schema_name',
];
class User {}

?>

Agree. Namespaces looks better than "__" prefixes.

Thanks. Dmitry.

Hi Dimitry,

I would like to present an RFC proposing support for native annotation.

The naming, syntax and behavior are mostly influenced by HHVM Hack, but not exactly the same.

The most interesting difference is an ability to use arbitrary PHP expressions as attribute values.

These expressions are not evaluated, but stored as Abstract Syntax Trees, and later may be accessed (node by node) in PHP extensions, preprocessors and PHP scripts their selves. I think this ability may be useful for "Design By Contract", other formal verification systems, Aspect Oriented Programming, etc

https://wiki.php.net/rfc/attributes

Note that this approach is going to be native, in contrast to doc-comment approach that uses not well defined syntax, and even not parsed by PHP itself.

Additional ideas, endorsement and criticism are welcome.
Nice RFC!
Attributes are always evaluated, right? i.e. No INI switch nor declare
to control behavior.
Just making sure.
Attributes are always parsed together with PHP script and stored internally.
Then you may access them through Reflection*::getAttributes() or in C
extensions through native API.

AST in attribute values is not evaluated.

Thanks. Dmitry.

Regards,

--
Yasuo Ohgaki
yohgaki@ohgaki.net

-----Original Message-----
From: Sebastian Bergmann [mailto:sebastian@php.net]
Sent: Sunday, April 24, 2016 12:14 PM
To: internals@lists.php.net
Subject: Re: [PHP-DEV] [RFC] PHP Attributes

I would like to present an RFC proposing support for native annotation.

Dmitry,

please use "annotation" as the name for this feature and not "attribute".

We already have attributes: it's what we use to store data in objects. And
while some people call them "member variables" or "properties" the correct
term for them (AFAIK) is "attribute".

I don't think I've ever heard properties referred to as attributes in the context of PHP. The PHP manual defines them and refers to them throughout as 'properties'.

(I'm not voicing an opinion on attributes vs. annotations; Just pointing out that data storage inside objects isn't named attributes).

Zeev

Hi,

I would like to present an RFC proposing support for native annotation.

Hi Dmitry,

Although everyone will have an opinion about the syntax, I think there
is one criticism that should be thought about; the chosen syntax isn't
future expandable to other concerns.

People have talked about "design by contract" RFCs where annotation
like data is readable by the engine. The current proposed syntax
could be used to store DBC data, but it would not be clear what
would be annotation data to read by the application, and what was DBC
data to be read by the engine.

Changing the proposed syntax to be something like @attr(...) would
allow it to be expanded in the future by adding a @contract(...)
construct:

@attr(test($a + $b > 0)) // This is attribute data read by userland code
@contract(require($a + $b > 0, 'InvalidFooArgsException')) // This is
DBC data read by the engine.
function foo($a, $b) {
...
}

Making features be compatible with future features would avoid a lot
of potential pain down the road.

Genuine question[1]: how is @attr() different than <<attr()>>? Also,
isn't @attr() 100% valid user-land code today that can precede
function or constant declarations?

[1] I don't like that I have to make that explicit but it is what it is.

Hi,

I would like to present an RFC proposing support for native annotation.

Hi Dmitry,

Although everyone will have an opinion about the syntax, I think there
is one criticism that should be thought about; the chosen syntax isn't
future expandable to other concerns.

People have talked about "design by contract" RFCs where annotation
like data is readable by the engine. The current proposed syntax
could be used to store DBC data, but it would not be clear what
would be annotation data to read by the application, and what was DBC
data to be read by the engine.

Changing the proposed syntax to be something like @attr(...) would
allow it to be expanded in the future by adding a @contract(...)
construct:

@attr(test($a + $b > 0)) // This is attribute data read by userland code
@contract(require($a + $b > 0, 'InvalidFooArgsException')) // This is
DBC data read by the engine.
function foo($a, $b) {
...
}

Making features be compatible with future features would avoid a lot
of potential pain down the road.

cheers
Dan
"@..." syntax can't work. @ - is a silence operator.

<<Contract\require($a + $b > 0, 'InvalidFooArgsException')>> - this is
not really worse than your example.

I know, any syntax is going to be loved by ones and hated by others...
It's not possible to satisfy everyone.

Thanks. Dmitry.

Hi!

https://wiki.php.net/rfc/attributes
I've read the proposal and I like the idea of reviving the attributes
idea and the simplicity of the approach.

I have the following questions for it:

• Namespacing. Since the attribute names are not processed in any way
  according to spec, it may be rather hard to ensure attribute
  requirements from different domains do not conflict, and we do not get
  into the same problem we've got into with class names before we
  implemented namespaces. How it is planned to address the issue?

I'm going to extend RFC with namespace support.
Attribute name is going to be qualified string.

• The expressions support is nice, however I'm not sure I understand
  what PHP application is supposed to do with syntax trees? I.e. taking
  the example in the RFC, if I got AST\Node representing <<test($a + $b >
  0)>>, how do I use it? Would I implement mini-PHP-engine in PHP to
  evaluate such an expression? Am I supposed to use some other
  functionality to do it? It is unclear.
  I don't think promoting reimplementing PHP expressions in a myriad of
  different ways (which all would be subtly different and distinct from
  how PHP understands such expressions) is not good, and if we expose
  those trees we should also provide means to work with them. Otherwise
  any advanced usage of the feature would mean basically reimplementing
  PHP engine in PHP.
  AST is going to be processed and evaluated using php-ast extension.
  Nikita was going to propose including it into core distribution.
  As a side note, my personal opinion is that for about 90% of use cases
  expressions are not needed. For 90% of those which are needed, string +
  some form of eval would cover it's use case since all the'd be doing is
  evaluating the expression and checking the resulting value.

This is a question. We may use AST expression or just strings.
In second case we miss syntax verification at compile time.
I'm going to describe the problem in RFC and set an additional voting
question.

• As far as I can see, AST extension has no documentation except for
  initial README. If it is going to end up in core, this needs to be
  fixed. Preferably before it is merged into core.

• I would also consider moving AST namespace under \PHP since we have
  this one reserved (unlike \AST which we did not reserve).
  For me AST is the best choice here.

• Are attributes also allowed to apply to anonymous classes/functions?
  Would the syntax still work in that case?

No. At least now.

_ I also think <<...>> syntax is ugly and @attribute syntax would be
much better (and also is used in Java attributes and Python decorators).
That's my personal opinion though.

@ is reserved for silence operator.

Thanks. Dmitry.

Thanks,

On Thu, Apr 21, 2016 at 4:51 PM, Dmitry Stogov <dmitry@zend.com
mailto:dmitry@zend.com> wrote:

    About expressions, isn't there an ambigoutiy? <<test(1)>> is a
    "plain" name, value based attribute. But it could also be an
    ast\node of a function call to "test(1)"

even in AST scalars are scalars.
so <<test(1+2)>> would return: ast\node "+" with two children
int(1) and int(2).

    I am wondering if they shouldn't get their own start/end signs
    to clear that up, <<<test(1)>> vs <<test(1)>>.


no need for extra complication.

Since the encapsulated meta-data is an AST, and as you say any valid
php expression will be valid here, what about bit shifting?

<<Test(FOO >> BAR)>>
This works because attributes are implemented as native part of
context-free PHP grammar.

Are there concerns about finding the T_SR token, which is also the end
annotation symbol? I've not done any work in the parser, so excuse me
if that is an insanely stupid question :)
Not a problem. Better to get false alarm then miss a real one :)

Otherwise, I think this RFC looks great, and appreciate your work on
this :)

Thanks. Dmitry.

Ryan

$r = new ReflectionClass('ORM\Entity');
var_dump($r->getAttributes());

Oops, that should've been:

$r = new ReflectionClass('Foo');
var_dump($r->getAttributes());

Colin

A more robust alternative would be something along the same lines that
Doctrine uses: Make annotations actual classes.

Just spitballing here - what if both approaches were supported, but
class-based annotations were prefixed with a special character
(perhaps "@") to differentiate them? For example:

<<ArbitraryAnnotation("Hello world")>>
<<@ORM\Entity(table => "foo")>>
class Foo {
// ...
}

namespace ORM;
class Entity implements \Attribute {
// ...
}

$r = new ReflectionClass('ORM\Entity');
var_dump($r->getAttributes());

---

array(2) {
["ArbitraryAnnotation"]=>
string(11) "Hello world"
["ORM\Entity"] =>
object(ORM\Entity)#1 (0) { ... }
}

---

Again, I'm not necessarily advocating this - just throwing the idea
out there for discussion.

Current proposal doen't support this, but this may be a good idea.

1. Attribute names might be not just strings, but also namespace qualified.
2. They may be optionally prefexed by some special character.

To create or not to create attribute objects is the question for next
layer, but the base layer should provide necessary information.

Thanks. Dmitry.

Regards,

Colin

It would, but the short array syntax followed by a function/method decl
would be unambiguous.

On dmitry's note, I'm not sure maintaining similarity with Hack is
justified. While Facebook maintains it as an open source project, they
primarily built it for themselves, so I can only think they will prioritise
their own needs over that of the PHP community.

This make it an unattractive alternative to PHP in my eyes and it may
explain why there are still so few projects on github written in Hack. I
don't see any reason why PHP should follow in their footsteps when it
concerns syntax.

And it will probably be in conflict with the Short Array Syntax ?

Just because HHVM is closer to PHP than C#.

---

From: Dominic Grostate codekestrel@googlemail.com
Sent: Tuesday, April 26, 2016 19:43
To: Dmitry Stogov
Cc: rowan.collins@gmail.com; PHP internals; Stanislav Malyshev
Subject: Re: [PHP-DEV] [RFC] PHP Attributes

Why not like C#?

[Description("My Function")]
function my_function()
{}

Without the semicolon, this wouldn't be valid in any other context.

On 26 Apr 2016 8:41 a.m., "Dmitry Stogov" <dmitry@zend.com<mailto:
dmitry@zend.com>> wrote:

Hi!

No, but this is valid:

@atrr(); function foo() { ... }

That's perhaps a little too close for comfort...?
That's different syntax. If you put ; in the middle of statement, it can
change - "$c = $a + $b;" is not the same as "$c = $a; + $b;" - but
nobody thinks + can not be used because of that. As I said, << and >>
are existing operators too, so if you are creative enough, I'm sure you
can find cases like that too.

Hi Stas,

You may try to replace attribute syntax with @attr(...) (without
semicolon) into our PHP parser.
Note that we have LALR grammar + restrictions caused by semantic actions.
If you are able to do this, I'll add it into the RFC as an option.

Thanks. Dmitry.

Lester Caine wrote on 28/04/2016 08:21:

This is what Mike van Riel was working on with PSR-5. Work has been
suspended atm, but I'd still go look at that first.
Sorry but php-fig is not PHP and sme of the 'standards' created there
are at odds with the preferred practices in the PHP code ... which is
one reason I see that some of the developments have been thankfully
suspended.

As far as I know, the PHP core has never dictated docblock contents, or
any other aspect of coding style. Such decisions are up to "the
community", which is a very broad concept. PHP-FIG is an attempt to get
that community "around a table" to decide on a common style, and common
ways of working.

If you want to follow a different style, you can; if you want to form an
alternative community group to spread that style, you can. None of that
has anything to do with the core language.

Is composer now the only supported installation tool?

Supported by whom? It's certainly not supported by the core language,
it's just a program you can use. However, it seems to meet people's
needs better than previous alternatives, so it is very popular.

Regards,
Rowan Collins
[IMSoP]

This needs to be agreed in the core first

Meh, no. Let someone that actually worked for years and years on the
specific problem to solve that, please: accumulated experience across all
use-cases is the best resource you can get here, and he knows his stuff.

Is composer now the only supported installation tool?

For pretty much most projects, yes. In this case, you can still use PEAR
(not sure for how much more, though) or a PHAR download:
https://www.phpdoc.org/docs/latest/getting-started/installing.html

Marco Pivetta

http://twitter.com/Ocramius

http://ocramius.github.com/

This is what Mike van Riel was working on with PSR-5. Work has been
suspended atm, but I'd still go look at that first.

Sorry but php-fig is not PHP and sme of the 'standards' created there
are at odds with the preferred practices in the PHP code ... which is
one reason I see that some of the developments have been thankfully
suspended. The changes to phpdocumentor are also at odds with core
practices and that is why I am putting my hand up here. This needs to be
agreed in the core first and personally I'd prefer that this annotation
practice was the primary one, and adding hard coded options remained
optional not enabled by default.

Is composer now the only supported installation tool? Even phpdocumentor
installer advises using other methods because of the mess composer
creates if you are installing more than one 'application', but the only
supported method for using php-annotations is via composer ... creating
it's own problems when trying to add back code that existed in the past.

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