Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:92657
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: error (pb1.pair.com: domain fleshgrinder.com from 77.244.243.86 cause and error)
Reply-To: internals@lists.php.net
References: <BY2PR0201MB178479B3AF8BD49583233034BF6E0@BY2PR0201MB1784.namprd02.prod.outlook.com>
To: Dmitry Stogov <dmitry@zend.com>, internals <internals@lists.php.net>
Message-ID: <571B94C1.1070307@fleshgrinder.com>
Date: Sat, 23 Apr 2016 17:29:05 +0200
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:38.0) Gecko/20100101
 Thunderbird/38.7.2
MIME-Version: 1.0
In-Reply-To: <BY2PR0201MB178479B3AF8BD49583233034BF6E0@BY2PR0201MB1784.namprd02.prod.outlook.com>
Content-Type: multipart/signed; micalg=pgp-sha256;
 protocol="application/pgp-signature";
 boundary="vwVd5G75sVU73JxK090kccrh26vHoxQSC"
Subject: Re: [PHP-DEV] [RFC] PHP Attributes
From: php@fleshgrinder.com (Fleshgrinder)

--vwVd5G75sVU73JxK090kccrh26vHoxQSC
Content-Type: multipart/mixed; boundary="VgWGpxv3RQAcp5MOaBRIwPigR45IFnGa8"
From: Fleshgrinder <php@fleshgrinder.com>
Reply-To: internals@lists.php.net
To: Dmitry Stogov <dmitry@zend.com>, internals <internals@lists.php.net>
Message-ID: <571B94C1.1070307@fleshgrinder.com>
Subject: Re: [PHP-DEV] [RFC] PHP Attributes
References: <BY2PR0201MB178479B3AF8BD49583233034BF6E0@BY2PR0201MB1784.namprd02.prod.outlook.com>
In-Reply-To: <BY2PR0201MB178479B3AF8BD49583233034BF6E0@BY2PR0201MB1784.namprd02.prod.outlook.com>

--VgWGpxv3RQAcp5MOaBRIwPigR45IFnGa8
Content-Type: text/plain; charset=windows-1252
Content-Transfer-Encoding: quoted-printable

+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    =3D "@" NAME [ " " VALUE ]
NAME          =3D STRING
VALUE         =3D QUOTED-STRING / PHP-CONSTANT / EXPRESSION
QUOTED-STRING =3D ( "'" / DQUOTE ) STRING ( "'" / DQUOTE )
EXPRESSION    =3D 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 =3D "Richard Fussenegger";
$email =3D "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 =3D "(" 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=3D1);

namespace Fleshgrinder\PhpInternals;

@description 'True annotation support could be a very good thing.'
@invariant $this->balance >=3D self::MIN_BALANCE;
class Account {

  private const int MIN_BALANCE =3D 0;

  private int $balance;

  private Person $owner;

  @require $sum >=3D 0;
  @ensure $this->balance =3D=3D=3D (old::$balance + $sum);
  public function deposit(int $sum): void {
    $this->balance +=3D $sum;
  }

  @require $sum >=3D 0;
  @require $sum <=3D $this->balance - self::MIN_BALANCE;
  @ensure $this->balance =3D=3D=3D (old::$balance - $sum);
  public function withdraw(int $sum): void {
    $this->balance -=3D $sum;
  }

  @deprecated 'for various reasons'
  public function setOwner(Person $wner): void {
    $this->owner =3D $owner;
  }

}

@inheritDoc
class OverdraftAccount extends Account {

  private const int MIN_BALANCE =3D -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' =3D> 'user',
  'unique_constraints' =3D> [
    'name' =3D> 'user_unique',
    'columns' =3D> [ 'username' ],
  ],
  'indexes' =3D> [
    'name' =3D> 'user_idx',
    'clumns' =3D> [ 'email' ],
  ],
  'schema' =3D> 'schema_name',
];
class User {}

?>

--=20
Richard "Fleshgrinder" Fussenegger


--VgWGpxv3RQAcp5MOaBRIwPigR45IFnGa8--

--vwVd5G75sVU73JxK090kccrh26vHoxQSC
Content-Type: application/pgp-signature; name="signature.asc"
Content-Description: OpenPGP digital signature
Content-Disposition: attachment; filename="signature.asc"

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2

iQIcBAEBCAAGBQJXG5TFAAoJEOKkKcqFPVVrE/gP/0fXS8AHwaCCSgSORAbU11LQ
QuuN34fFlzUQM56H1cqlqqENt0rRm1we7VC5uSMooWV/dYz4klbziWFfZ3gWmICi
9wqH6QBxXhL1w+otBp+OSjZ81San0REqggW7mdVD9VMsakmKWDuWmg2Cqm5MxUoi
9C1eGuqnFKiX/kEBNlsHEgZKG8O6frYp4aq1zlIDhTqoXpRArvftoxKzPk4tDDI9
sRoeqmhGFZhGEoyjsv234eVvGk+dmOOI8Oo5hkQH4Jc0iZAsxOw1ba9ApzoEGJe1
CLvvu1Yw1DlftjIKCT7+xTaDo77dply+Ja4IybZasx3IdHLquvh3i82jCkjT8IpF
O9FnP4spjdd7CqLbd6VWbkbHFVK6xe4fqHQm5QbPVtDWNp9t3PMbpAfbGlMpnJtI
emx+P9wC7orL/eh97U3F+rUedrwD/GlrBHB5wCsE1AFAmsgIncRNiJShDqIx3w9F
jRmGyGqMRP5/kykxFMBDwVYkyfxPeJw/LUcsVJ4yEmUN1PQbOdjtC6zhQw4b5XP5
iIctirJpEqt+yKW2eLTd3IeronUjCjPImZeb9K3BQ4ddTq20MVInvIoR5BkMMN+M
Whj1BDpktGlEap/kyBOQL/zKEw7XCfz2b4+GwaMhag78lDtPNNx3gHjQ1B543Egv
dw9NCC4HmJF2XHAVE6IA
=JcQW
-----END PGP SIGNATURE-----

--vwVd5G75sVU73JxK090kccrh26vHoxQSC--