Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:92934
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: pass (pb1.pair.com: domain gmail.com designates 74.125.82.50 as permitted sender)
To: internals@lists.php.net
References: <BY2PR0201MB178479B3AF8BD49583233034BF6E0@BY2PR0201MB1784.namprd02.prod.outlook.com>
 <571E35D8.8080504@zend.com> <571E4A83.3080304@garfieldtech.com>
 <571E64A2.2040505@gmail.com>
 <CADqTB_hH4=Rx2ZV_WSJuCPzbnA-ERyFUE8ZsCew2Z6p0+FHWsg@mail.gmail.com>
 <5720A6B4.4000307@lsces.co.uk>
 <CADyq6sKBV0n+xnVhRxsP5RDf0oRLMnNO-BM1VEudRgcK1s199A@mail.gmail.com>
 <CADyq6s+P5p-xdJ8CQaFo3Nrwe7ooyCLg1p=98E0kcSscBbSe8A@mail.gmail.com>
 <CADyq6sJp-krEpGgat7hWm2YpvtfwAfK1ya0as4Tv2qtCSeNgAw@mail.gmail.com>
 <5721B9DD.3050300@lsces.co.uk>
 <CADyq6s+nJoHkMmA+iupA0+7jwJskkdLTe=os=gZDt3dqaJxT7A@mail.gmail.com>
 <57231ADD.9040006@lsces.co.uk>
 <CADyq6s+uELdzWoMd0GBvby205Po_xEpxKoEBkSc_qbxsS3YeXQ@mail.gmail.com>
 <572326A3.7000809@lsces.co.uk>
 <cb7724e7-7436-3013-5a3a-f7df6c35ed86@gmail.com>
 <57234D3D.1070602@lsces.co.uk>
 <79c9df57-ee45-f415-3172-95f8229bbece@gmail.com>
 <CAEPJdunLsPfnE5ebZkcARRO_RR9ni1jWQJg_FW_9XZm9XhpPsQ@mail.gmail.com>
 <57235F20.5080707@lsces.co.uk>
Message-ID: <43b9c67f-3ec7-bacc-2608-552abbd1a3fa@gmail.com>
Date: Fri, 29 Apr 2016 14:51:40 +0100
User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:45.0) Gecko/20100101
 Thunderbird/45.0
MIME-Version: 1.0
In-Reply-To: <57235F20.5080707@lsces.co.uk>
Content-Type: text/plain; charset=utf-8; format=flowed
Content-Transfer-Encoding: 7bit
Subject: Re: [PHP-DEV] PHP Attributes -> docBloc alternatives ...
From: rowan.collins@gmail.com (Rowan Collins)

Lester Caine wrote on 29/04/2016 14:18:
> But where will annotations like @range(0,110) fit in the new model?
> Along with the likes of '@notnull' and similar annotations that are also
> currently being planned to be spread around the rest of the code? If a
> variable is defined via the metadata as 'not null', then assigning null
> to it is an error

Hi Lester,

Do you mean you are currently using these attributes / annotations with 
a reflection library to generate assertions in the code and throw errors 
at runtime? If so, yes, the native syntax will be used for that going 
forward, once the tools catch up (though they're likely to provide 
backwards compatibility modes for a fairly long time).

However, there's no support built into the core for doing the actual 
checks now, and there's no plan (that I know of) to build one in in 
future. All that's proposed is to add more support in the language for a 
general syntax which can be used by such tools, to avoid them doing so 
much string parsing.

If you're just using these annotations for documentation (as your 
references to phpDocumentor imply), then nothing will change: you'll 
still be able to use them for that, and they still won't be enforced. 
This is exactly the same as has been true since PHP 5.0 for argument 
types; the engine never validates anything in the docblock, and it might 
be completely wrong, and we have separate syntax for actually enforcing 
checks:

/**
  * @param Foo $foo
  */
  function test(Bar $bar) {}

Even if there were no other downsides to the syntax, it would probably 
be a bad idea for the core to start enforcing things based on docblocks, 
because it would potentially break a lot of code that had them written 
wrong. Indeed, it is for precisely this reason that a new syntax is 
being proposed for general machine-readable attributes (rather than just 
functions for parsing the docblock), so that we can return to seeing 
docblocks as just comments, with no meaning for the code.

In short:
- if you're generating documentation from docblocks, it's up to the 
program doing the generating what to interpret, and nothing is going to 
change that
- if you're generating behaviour from docblocks, it's up to the library 
doing the generating what to interpret, and what will change is them 
recommending the new dedicated syntax if it's implemented, because it 
will be more efficient to process

Regards,
-- 
Rowan Collins
[IMSoP]