Annotations [RFC]

[Andres Gutierrez]

This RFC is to discuss the possible implementation of annotations in the framework, these could be used to define meta-data models or define routes in controllers.

Introduction
Currently PHP does not support annotations, other libraries/frameworks have implemented PHP parsers to read annotations in the comments, the annotations are translated into plain PHP  and stored in additional files that are read every time is needed. A RFC is currently declined in the PHP internals (https://wiki.php.net/rfc/annotations) so this feature will not be available in the short time as part of PHP.

Models
In models, annotations can be used to define relationships, behaviors, data types, renaming columns, etc.:

<?php

/**
 * @Source(the_robots)
 * @HasMany(columns=id, refModel=RobotsParts, refColumns=robots_id)
 */
class Robots extends Phalcon\Mvc\Model
{
 
    /**
     * @Column(type="integer", length=11, nullable=false)
     */
    protected $id;

    /**
     * @Column(type="string", length=32, nullable=true)
     */
    protected $name;

}

Controllers
Define routes/http constaints in the controller:

class PostsController extends Phalcon\Mvc\Controller
{

    /**
     * @Get(/api/posts)
     */
    public function showAction()
    {

    }

    /**
     * @Post(/api/posts/new)
     */
    public function create()
    {

    }

}

The annotations parser also can be reused by the developer and adapt it to its own needs.

Advantages

• Simplification of some aspects of the coding
• Removal of database introspection for models

Disadvantages

• It adds additional overhead to parse/read the annotations for the framework to implement the subject of annotations
• All comments in classes/models would be target of parsing looking for annotations 

Implementation

• We need to build a new parser such as Volt/PHQL to read the annotations.
• Add new meta-data/routing strategies to take advantage of the read annotations

Using annotations will be optional, it must be enabled manually by the developer. 

Please vote with +1 or -1 if you want/don't want that this being implemented in a next release. Please add comments on possible drawbacks or disadvantages of adding this.

[Николай Измайлов]

Annotations gives flexibility and it is good. ON the производительсно can all кешировоть and испольноть optimized code and not иходный. In the dev version use every time the parser to prod version, all from the cache and all optimized. +1

2013/1/11 Andres Gutierrez <andres.g...@phalconphp.com>

--
You received this message because you are subscribed to the Google Groups "Phalcon PHP Framework" group.
To post to this group, send email to pha...@googlegroups.com.
To unsubscribe from this group, send email to phalcon+u...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
 
 

[Николай Измайлов]

2013/1/11 Николай Измайлов <nekul...@gmail.com>

производительсно -

performance

[Antonio Lopez]

It's a shame that PHP guys have rejected annotations, btw, excuse my ignorance, but since you work in C, could not you implement the annotations as proposed in RFC link?

<Entity("users")>
class User
{
    <Column("integer")>
    <Id>
    <GeneratedValue("AUTO")>
    protected $id;

    // ...

    <ManyToMany("Phonenumber")>
    protected $Phonenumbers;
}

instead of using the comments that were not designed for it?

[Romanko]

And here we come to Aspect Oriented Programming!

+1 from me, I'd like to see more use of annotations, not only in models but in controllers as well:

• HTTP Caching 
• Edge Side Includes, we work with Akamai and Varnish alot
• ACL & Permissions
• Routes
• May be layouts & templates

There are two questions: how to keep them actual and when to parse them?

Lithium uses AOP a lot, annotations processing can be done similar to their filtering system.

[tmihalik]

+1 

Symfony did it well, annotations works with Route, ACL, Template, Cache: 

http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/index.html#annotations-for-controllers

http://symfony.com/doc/current/cookbook/security/securing_services.html#securing-methods-using-annotations

[Karol]

It is great news, that you plan to add this functionality to phalcon.

I vote +1 for global smart annotations, it should be enable by default, if somebody dont need it then it could be disable in phalcon.ini

[Nikolaos Dimopoulos]

+1

The contents of this message may contain confidential or privileged information and is intended solely for the recipient(s). Use or distribution to and by any other party is not authorized. If you are not the intended recipient, copying, distribution or use of the contents of this information is prohibited.

On Fri, Jan 11, 2013 at 3:09 AM, Karol <ka...@regreen.pl> wrote:

It is great news, that you plan to add this functionality to phalcon.

I vote +1 for global smart annotations, it should be enable by default, if somebody dont need it then it could be disable in phalcon.ini

--
You received this message because you are subscribed to the Google Groups "Phalcon PHP Framework" group.
To post to this group, send email to pha...@googlegroups.com.
To unsubscribe from this group, send email to phalcon+u...@googlegroups.com.

To view this discussion on the web visit https://groups.google.com/d/msg/phalcon/-/eejayZDbG_cJ.

[Andres Gutierrez]

I like that syntax, but there is a problem, extensions can not modify the php parser, even if we discovered how to do it, most IDEs would complain for parsing errors. Despite comments but are not designed to annotations are silently ignored by the IDE which is fine.

2013/1/10 Antonio Lopez <alanto...@gmail.com>

[dschissler]

So I guess that answers my question.  I was hoping that phalcon could have an option to change the '$' token to another one of your choosing by using an enumerated constant.

[Andres Gutierrez]

I've been working on this so it's a fact that it will be part of Phalcon 0.9.

Basically, it is a new component that is responsible for parsing the annotations and store them on different backends to improve performance. It is a general purpose component, any developer can use it to implement annotations in his/her project. 

This component will be used by other components to take advantage of the annotations.

https://gist.github.com/4522325

This component is in the 0.9.0 branch, if anyone wants to try it and give feedback.

2013/1/10 Andres Gutierrez <andres.g...@phalconphp.com>

[Nicolas de Marque]

Annotation as configuration purpose are a good thing. I like this feature.

A second possibility not evocated here are that annotations could be use too for decorate a function, like in python

<?php

/**

 * @Decorator

 */

function Button($color, Closure $closure, $decoratedParams){

  return "<input type='submit' style='color:$color' value='".call_user_func_array($closure, $decoratedParams)."' />";

}

/**

 * @Button("blue")

 */

function MyButton($text){

  return $text;

}

And with a little improvement the call_user_function could be simply replaced by $closure($params);

So i don't know if this RFC was about decorator too but the annotation syntax can easily be used for this purpose, i think this could be thinking in the same time.

Anyway i vote +1 for the annotation mention in the first post.

Best Regards,

Nicolas de Marqué

2013/1/13 Andres Gutierrez <andres.g...@phalconphp.com>

[Andres Gutierrez]

This is how is currently implemented annotations+routing in 0.9:

https://gist.github.com/4543132

• A variant of the routing component must be used
• Resources need to be registered in the router
• A resource is a class that contains routes, those with annotations are registered as routes
• Define a prefix for the controller is highly recommended, in this case the router only parse the annotations if the current handled URI starts with the prefix thus increasing the performance

2013/1/10 Andres Gutierrez <andres.g...@phalconphp.com>

[Andres Gutierrez]

This is another approach for annotations:

Let's pretend we want to implement an annotation "Cache" in the application's actions, the following example shows how to create a plugin that automatically enables the cache for those actions who implements that annotations

https://gist.github.com/4544542 

2013/1/15 Andres Gutierrez <andres.g...@phalconphp.com>