[RFC] PHP Attributes

If I was a popular framework creator, this wouldn't stop me. I would
release two packages : one for 7.0, another one for 7.1. And the 7.0 one
would be the 7.1 one that has been processed through a script to remove
any <<>> syntax, or to transform it (if pre/post attributes instructions
were to be implemented in the core).

Regards,
Ben.

Le Sun, 24 Apr 2016 01:09:08 +0200, "Thomas Bley" mails@thomasbley.de a
écrit:

The <<>> syntax comes with the problem that previous versions cannot
ignore it on parsing.
So poeple write new frameworks for 7.0 which cannot be parsed in 5.x,
then they write new frameworks for 7.1 which cannot be parsed with 7.0
and 5.x and so on.
For companies staying on Linux distributions with long term support on
7.0, this is rather a nightmare for both users and framework maintainers.
When choosing <<>> or any other non-backward compatible syntax for 7.1,
there should be a patch for 7.0 to ignore the new syntax without parse
errors.

Regards
Thomas

Fleshgrinder wrote on 23.04.2016 17:29:

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

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.

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;

}

?>

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.

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

?>

--
Richard "Fleshgrinder" Fussenegger

--
Utilisant le logiciel de courrier d'Opera : http://www.opera.com/mail/

The <<>> syntax comes with the problem that previous versions cannot
ignore it on parsing.
So poeple write new frameworks for 7.0 which cannot be parsed in 5.x, then
they write new frameworks for 7.1 which cannot be parsed with 7.0 and 5.x
and so on.
For companies staying on Linux distributions with long term support on
7.0, this is rather a nightmare for both users and framework maintainers.
When choosing <<>> or any other non-backward compatible syntax for 7.1,
there should be a patch for 7.0 to ignore the new syntax without parse
errors.

This does not make sense, when the <<>> attributes have an effect on the
program, then just skipping them on older versions will not make them behave
the same at runtime, because no reflection attributes can be found.

How is introducing this change any different than, say introducing
namespaces? Libraries and frameworks decide to use it or not, and then the
user has to go along.

This just means that you better pick frameworks and libraries with goo long
term support and Backwards compatibility story. Especially when you pick
distributions
with LTS PHP support as well. If you require an LTS php version across your
company, you cannot really expect that bleeding edge PHP libraries work
with that strategy.

Additionally, the way many modern frameworks and libraries work, using
attributes will be an optional way of configuration. I can speak for
Doctrine for example, we will not remove
its the "old" annotation parser, and xml+yml will still be supported. Same
propably goes for Symfony or Zend Framework 2.

Regards
Thomas

Fleshgrinder wrote on 23.04.2016 17:29:

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

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.

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;

}

?>

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.

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

?>

--
Richard "Fleshgrinder" Fussenegger

The <<>> syntax comes with the problem that previous versions cannot ignore it on parsing.
So poeple write new frameworks for 7.0 which cannot be parsed in 5.x, then they write new frameworks for 7.1 which cannot be parsed with 7.0 and 5.x and so on.
For companies staying on Linux distributions with long term support on 7.0, this is rather a nightmare for both users and framework maintainers.
When choosing <<>> or any other non-backward compatible syntax for 7.1, there should be a patch for 7.0 to ignore the new syntax without parse errors.
Good point, but any syntax proposed for native attributes would break
forward-compatibility as well.
The only choice to stay with doc-comments and do all the work at user level.

Thanks. Dmitry.

Regards
Thomas

Fleshgrinder wrote on 23.04.2016 17:29:

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

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.

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;

}

?>

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.

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

?>

--
Richard "Fleshgrinder" Fussenegger