[RFC] Simple Annotations

On 14/05/2016 20:49, Rasmus Schultz wrote:

This doesn't really explain how such a feature would fit it into the proposal. For instance, how can we avoid the syntax clashing with existing userland issues? Given that annotations in this proposal don't have names, we can't just reserve all names beginning "__" or "php\". Perhaps they would be pseudo-function calls, like <<__memoize()>>? How would that (or any other undefined function) act if accessed on a version that didn't have the feature? I realise you don't want to define the details, but an idea of what an annotation targeting the engine would look like would make the future-proofing clearer. Regards,

Note that I only make comparisons with doc-blocks to point out the fact that, functionally, they would not be very different from an annotation feature that solely permits you to annotate with values. A doc-block is a string, which is a value - an array/int/float/string/bool is a value. It's only very slightly better than a bare string, in the sense that neither doc-blocks nor simple values permit any kind of definition of which annotations are actually available, hence offer no means of validation of that data (except at run-time by a userland facility), provides no support for static analysis, no IDE support, no clear indication of real dependencies, and so on. Since the discussion isn't completely dead yet (thank you Pedro and Marco), I will just briefly explain what I had in mind for another RFC. This would be largely based on my previous proposal: https://wiki.php.net/rfc/simple-annotations But with the following differences. The syntax would no longer allow arbitrary expressions - instead, it would allow object annotations only, declared in one of three ways: << RequiresLogin >> // equivalent to new RequiresLogin() << Length(20) >> // equivalent to new Length(20) << HttpMethod::post() >> // equivalent to static method-call HttpMethod::post() The latter permits you to declare and call static factory methods, e.g. "named constructors" for some types of annotations. Annotations are now consistently objects, which simplifies filtering annotations, etc. This declaration syntax enables better in-language analysis - because the declarations always include the annotation class-name, this means it can now support deferred as well as conditional creation, by having a slightly different reflection API: $annotations = $class_reflection->getAnnotations(); At this point, we have a list of ReflectionAnnotation objects - the actual annotation objects have *not* been created at this point, which would allow for conditional evaluation, such as: foreach ($annotations as $annotation) { echo $annotation->className; // => "Length" etc. if ($annotation->classExists()) { var_dump($annotation->getInstance()); // => Length object, etc. } else { var_dump($annotation->getInstance()); // => UnknownAnnotation object } } The UnknownAnnotation object has three properties: class-name, method-name ("__construct" if constructor was used) and the list of arguments. In other words, this would provide support for "optional dependencies", in much the same way that unserialize() does it - the getInstance() method will trigger autoloading, and if the class is unavailable, it takes this "typeless" information and puts it in a general object, so that the information itself isn't lost. It may *seem* like this solves the optional dependency problem, but let me be clear, it does *not* fully address that issue, because something like << Method(Http::GET) >> could still fail, if the Method class is defined, but the Http class is not. That's a much more marginal case, but it's not completely unlikely that you would use constants from one dependency and pass them to annotation classes from another dependency, e.g. if the HTTP method constants were part of an HTTP package, and the annotation itself were part of a different package. Arguably it's much less likely to occur though - if you have the annotation package installed, most likely you have the dependent package of that package installed as well. So this is much safer, but just to be clear, the only way you can make it any safer than that, is by completely disallowing anything but values as arguments to annotation constructors - which, in my opinion, simply isn't useful. Alternatively to the above, you could imagine a simpler reflection facility that does eagerly construct annotations, but constructs UnknownAnnotation instances for missing classes - this would perhaps balance more towards immediate usefulness and less towards performance perfectionism, as it increases the chance of loading an unused annotation. This would be my preference though - as previously argued, the odds of having a large number of unrelated annotations on the same member are extremely low in practice; an annotated entity tends to be a persisted property, a form input element, or an action method, etc... rarely do you mix annotations from different domains onto the same member; annotations that are applicable to a given domain are usually relevant to a consumer belonging to the same (or a closely related) domain, so this performance concern is mostly a theoretical micro optimization. For another, eager construction means we can filter annotations with instanceof rather than by class-name, which is much powerful, enabling you to leverage inheritance - for example, you'd be able to ask directly for all instances of ValidationAnnotation and get those with a single call, which is incredibly useful. Anyways, let me know your feelings about that idea? If there's any interest, I'd be happy to write yet another RFC based on that. On Tue, Jun 28, 2016 at 4:30 PM, Pedro Cordeiro <pedronaroga@gmail.com> wrote: