SitePoint Sponsor

User Tag List

Page 1 of 2 12 LastLast
Results 1 to 25 of 33
  1. #1
    SitePoint Zealot johno's Avatar
    Join Date
    Sep 2003
    Location
    Bratislava, Slovakia
    Posts
    184
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)

    PHP Annotations support through DocComment

    Hi there,

    I've been playing around with annotations support for PHP through DocComments.

    Here are some examples of what my annotations parser can handle.

    Code:
    @SimpleAnnotation
    @SingleValuedAnnotation(1)
    @SingleValuedAnnotation(3.1415)
    @SingleValuedAnnotation("double quoted string")
    @SingleValuedAnnotation('single quoted string')
    @PairsAnnotation(key1="value1", key2=3.14)
    Here some practical examples what I can imagine it would be good for.

    Defining O/R mapping and constraints:
    PHP Code:
    /** @Persistent(table="articles") */
    class Article {
       
    /** @PrimaryKey */
       
    private $id;
       
       
    /** @Column("article_title") @String @UniqueConstraint */
       
    private $title;

       
    /** @HasMany("Comment"); */
       
    private $comments;
       
       ...

    Defining caching strategy:
    PHP Code:
    class SearchingAlgorithm {
       
    /** @Cached(timeout=60, units="sec") */
       
    public function search($keywords) {
          
    // big calculations
       
    }

    Here is how you get annotation values for a class/method/properties:

    PHP Code:
    $reflection = new ReflectionAnnotatedClass('Article');
    $annotation $reflection->getAnnotation('Persistent');
    echo 
    $annotation->table// "articles"

    $annotations $reflection->getProperty('title')->getAnnotations();
    echo 
    $annotations[0]->value// "article_title"
    ... 
    I've created ReflectionAnnotatedClass, ReflectionAnnotatedMethod, ReflectionAnnotatedProperty classes with methods like isAnnotatedWith(), getAnnotation(), getAnnotations();

    Annotations are defined as simple classes like
    PHP Code:
    class Persistent extends Annotation {
       public 
    $table;

    So what do you guys think? Any ideas, bugreports or better usage examples?

    Source files and tests: http://johno.jsmf.net/knowhow/addendum/
    Last edited by johno; Nov 16, 2006 at 02:46.
    Annotations support for PHP5
    TC/OPT™ Group Leader

  2. #2
    PHP Brainiac dg_den_golotyuk's Avatar
    Join Date
    Jul 2006
    Location
    Kiev, Ukraine
    Posts
    335
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    It is cool. I've been searching for smth recently. Would be nice to run it, thx
    DG [Den Golotyuk], Lead Developer
    Chestnut Software
    Avoid web outsourcing scams!
    Click here
    for a free downloadable report

  3. #3
    SitePoint Member
    Join Date
    Oct 2003
    Location
    Argentina
    Posts
    19
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    There's some overhead in doing this? Someone measured it?
    I'm a bit skeptical, after all, are only comments. If PHP stores ahead all the docblocks comments, that involve memory allocated during runtime. If search for this information in runtime there's some parsing time. What's doing php to give this kind of information in runtime?

  4. #4
    SitePoint Zealot johno's Avatar
    Join Date
    Sep 2003
    Location
    Bratislava, Slovakia
    Posts
    184
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Quote Originally Posted by k7k0
    There's some overhead in doing this? Someone measured it?
    I'm a bit skeptical, after all, are only comments. If PHP stores ahead all the docblocks comments, that involve memory allocated during runtime. If search for this information in runtime there's some parsing time. What's doing php to give this kind of information in runtime?
    When its really a bottleneck you can always cache it somehow.
    Annotations support for PHP5
    TC/OPT™ Group Leader

  5. #5
    SitePoint Member
    Join Date
    Oct 2003
    Location
    Argentina
    Posts
    19
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Quote Originally Posted by johno
    When its really a bottleneck you can always cache it somehow.
    Ok, that's true. Maybe I'm a bit off-topic, but I'm trying to figure how the comment parsing works, and an easy way to turn off the phpdoc parsing. I'm developing a pretty big framework with a lot of phpdoc (in my case useless in runtime). If that information is available in runtime is because it's parsed and stored, and I want to measure the overhead of this procedure. Of course I can make a script that remove all the phpdoc blocks before a release, but it's not the easy way!

  6. #6
    SitePoint Zealot johno's Avatar
    Join Date
    Sep 2003
    Location
    Bratislava, Slovakia
    Posts
    184
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Quote Originally Posted by k7k0
    Ok, that's true. Maybe I'm a bit off-topic, but I'm trying to figure how the comment parsing works, and an easy way to turn off the phpdoc parsing. I'm developing a pretty big framework with a lot of phpdoc (in my case useless in runtime). If that information is available in runtime is because it's parsed and stored, and I want to measure the overhead of this procedure. Of course I can make a script that remove all the phpdoc blocks before a release, but it's not the easy way!
    Annotation parser is triggered only if you need it. There is almost no overhead in this way.
    Annotations support for PHP5
    TC/OPT™ Group Leader

  7. #7
    Put your best practices away. The New Guy's Avatar
    Join Date
    Sep 2002
    Location
    Canada
    Posts
    2,087
    Mentioned
    1 Post(s)
    Tagged
    1 Thread(s)
    I think its time to switch languages at this point
    "A nerd who gets contacts
    and a trendy hair cut is still a nerd"

    - Stephen Colbert on Apple Users

  8. #8
    SitePoint Zealot johno's Avatar
    Join Date
    Sep 2003
    Location
    Bratislava, Slovakia
    Posts
    184
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Quote Originally Posted by The New Guy
    I think its time to switch languages at this point
    Ok, which one?
    Annotations support for PHP5
    TC/OPT™ Group Leader

  9. #9
    SitePoint Zealot
    Join Date
    Sep 2005
    Posts
    122
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    EZPDO is already doing this for there ORM package: http://www.ezpdo.net/blog/cats/ezpdo

    I've also toyed around with using "annotations" for a validation framework. Performance isn't even worth considering -- start with the database instead.

  10. #10
    SitePoint Wizard silver trophy kyberfabrikken's Avatar
    Join Date
    Jun 2004
    Location
    Copenhagen, Denmark
    Posts
    6,157
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Quote Originally Posted by johno
    Ok, which one?
    JS ?

    You're basically applying properties to functions. In PHP, as in it's role-models (java, c++), the way is to use object properties for theese things. Functions aren't first-class citizens in PHP.

    It's an interesting idea, although I don't really think it's of any practical use.

  11. #11
    SitePoint Zealot johno's Avatar
    Join Date
    Sep 2003
    Location
    Bratislava, Slovakia
    Posts
    184
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Quote Originally Posted by kyberfabrikken
    JS ?
    Ok, you shocked me, I was expecting something like Java, Ruby or maybe LISP. So why Javascript? Did you mean serverside JS?

    Quote Originally Posted by kyberfabrikken
    It's an interesting idea, although I don't really think it's of any practical use.
    As shea noted, EZPDO uses something similar in concept and works great. So I do thing it can be really useful.

    Also annotations with AOP seem to make really good sense. Actually thats what I'm trying to do in PHP. Just in case you have not read about it.

    http://www-128.ibm.com/developerwork...ry/j-aopwork3/
    http://www-128.ibm.com/developerwork...ry/j-aopwork4/
    Annotations support for PHP5
    TC/OPT™ Group Leader

  12. #12
    SitePoint Wizard silver trophy kyberfabrikken's Avatar
    Join Date
    Jun 2004
    Location
    Copenhagen, Denmark
    Posts
    6,157
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Quote Originally Posted by johno
    Ok, you shocked me, I was expecting something like Java, Ruby or maybe LISP. So why Javascript? Did you mean serverside JS?
    Yep - And I weren't completely serious, because no such thing really exists (At least not complete enough that I would use it). Still - js has functions as firstclass citizens - you can assign properties to a function, which is exactly what you do here.

    Quote Originally Posted by johno
    As Ezku noted, EZPDO uses something similar in concept and works great. So I do thing it can be really useful.
    I think I was mostly focussing on the use of annotations for functions. Unless the caller know how to handle this meta-information, it won't make any difference. For variables, it may make more immediate use.

    AOP for example, will need some kind of language-level extension to work, or you would have to make certain assumptions about how the code is utilized, that would be limiting. People can't call functions directly - they need to call them in some non-standard way, or use a proxy. Or you'll need to recompile code, which would limit PHP's dynamic nature.
    A more realistic solution to AOP is as an extension, which can actually manipulate the runtime code. I think AspectPHP is getting close :
    http://www.sebastian-bergmann.de/AspectPHP/

  13. #13
    SitePoint Zealot DerelictMan's Avatar
    Join Date
    Oct 2005
    Posts
    123
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Quote Originally Posted by johno
    As shea noted, EZPDO uses something similar in concept and works great. So I do thing it can be really useful.
    I agree. (Nice work, BTW).

    Quote Originally Posted by kyberfabrikken
    I think I was mostly focussing on the use of annotations for functions. Unless the caller know how to handle this meta-information, it won't make any difference.
    A proxy class that delegates all method calls to a wrapped object (using __call()) could use this information to determine what decorated behavior it should add, no? Granted, I can't immediately think of an application for this other than ORM and the standard AOP example of logging.

    Another use for annotation-style metadata could be in unit testing. In the Java project I'm currently working on, we are developing a set of entity classes that will be mapped to our database using Hibernate. We are creating each entity so that the relationships it has with other entities are all bidirectional. IOW, Parent has getChildren(), addChild(), removeChild(), and Child has getParent(), attachToParent(), detachFromParent(), and these methods are reciprocal (calling Parent#addChild() is the same as Child#attachToParent()). Getting these bidirectional associations right can be kind of a pain (there are weird cases like Child#attachToParent() has to make sure to remove the child from the old parent first, etc.). It's difficult to generalize and break this kind of behavior out into a different class (using either inheritance or composition), so unfortunately managing these bidirectional relationships has turned into a sort of "pattern" for us. (I've seen it referred to as the mutual registration pattern, but granted not in too many places.) Anyway, I have a base test case which we subclass for each persistent entity. Since I don't trust myself or my developers to remember to create the 6-7 necessary test methods that are recommended for each association, I use reflection and Hibernate's metadata to discover each association and complain if certain test methods haven't been implemented (I can't do this via abstract methods since I don't know this information until runtime).

    The issue is that we use a pattern where one side of the association basically delegates to the other. That being the case, we can really fully test the association all from one side (and it's clearer this way too, since you have tests for both sides of the association in one place). The problem is, my test method that enforces the other test methods have been created isn't smart enough to figure out which side delegates to the other. So, how do I indicate in my entity class that the relationship handling is delegated to the other side? Using an annotation...

    That turned out to be more long-winded that I had intended to make it, but my point is there are some occasions where this sort of metadata could be useful. They are esoteric perhaps, but I believe they exist nonetheless.

  14. #14
    SitePoint Zealot johno's Avatar
    Join Date
    Sep 2003
    Location
    Bratislava, Slovakia
    Posts
    184
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Quote Originally Posted by DerelictMan
    A proxy class that delegates all method calls to a wrapped object (using __call()) could use this information to determine what decorated behavior it should add, no? Granted, I can't immediately think of an application for this other than ORM and the standard AOP example of logging.
    What about transactions, authorization, performance (method result caching) and so on?
    Annotations support for PHP5
    TC/OPT™ Group Leader

  15. #15
    SitePoint Zealot johno's Avatar
    Join Date
    Sep 2003
    Location
    Bratislava, Slovakia
    Posts
    184
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Project home moved to Google Code: http://code.google.com/p/addendum/
    Annotations support for PHP5
    TC/OPT™ Group Leader

  16. #16
    SitePoint Zealot
    Join Date
    Jul 2004
    Location
    The Netherlands
    Posts
    170
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Extensions that might be of interest:
    Extended Reflection API
    phpAspect
    Parse_Tree

  17. #17
    SitePoint Guru BerislavLopac's Avatar
    Join Date
    Sep 2004
    Location
    Zagreb, Croatia
    Posts
    830
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Quote Originally Posted by kyberfabrikken
    Yep - And I weren't completely serious, because no such thing really exists (At least not complete enough that I would use it).
    Ahem.

  18. #18
    SitePoint Zealot johno's Avatar
    Join Date
    Sep 2003
    Location
    Bratislava, Slovakia
    Posts
    184
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Addendum still lives!

    I've just added new features including:

    Nested arrays with mixed key/value pairs
    Code:
    /** @Annotation({1, 2, {3, 4}, pi = 3.141592}) **/
    Class AnnotatedClass {}
    Support for multiple annotation instances of same class on one target.
    Code:
    /**
      @Annotation("fist")
      @Annotation("second")
     */
    Class AnnotatedClass {}
    Parsing speed improvements.

    Updated tutorial/documentation http://code.google.com/p/addendum/wi...orialByExample

    Meta-annotation @Target and customized user constraints checking.
    http://code.google.com/p/addendum/wiki/AdvancedFeatures

    Does anybody knows any projects/frameworks/libraries that would need such annotations? ORMs?
    Annotations support for PHP5
    TC/OPT™ Group Leader

  19. #19
    SitePoint Evangelist ghurtado's Avatar
    Join Date
    Sep 2003
    Location
    Wixom, Michigan
    Posts
    591
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Good work, I wouldn't have seen this were it not for your reviving this old thread. May I suggest that you create a new thread for those that were not around sitepoint at the time of the original thread (almost two years old)? That way you can expand on the features a little more. Personally, I am working on an ORM at the moment and I just started considering using annotations for some of the attribute level configuration, so I am very intersted in having a whole new thread dedicated to the topic.
    Garcia

  20. #20
    SitePoint Zealot johno's Avatar
    Join Date
    Sep 2003
    Location
    Bratislava, Slovakia
    Posts
    184
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Quote Originally Posted by ghurtado View Post
    Good work, I wouldn't have seen this were it not for your reviving this old thread. May I suggest that you create a new thread for those that were not around sitepoint at the time of the original thread (almost two years old)? That way you can expand on the features a little more.
    Hmm, threads are sorted according to timestamps of last posts, yes? No need for new thread i think.

    Personally, I am working on an ORM at the moment and I just started considering using annotations for some of the attribute level configuration, so I am very intersted in having a whole new thread dedicated to the topic.
    Well, the funny thing is that I've started addendum exactly for the same purpose - an ORM mapper. It would be awesome if you used my library, i just can't wait for new real world scenarios.
    Annotations support for PHP5
    TC/OPT™ Group Leader

  21. #21
    Resident Code Monkey Chris Corbyn's Avatar
    Join Date
    Nov 2005
    Location
    Melbourne, Australia
    Posts
    713
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    I could see something like this being useful in testing frameworks too. I think one of the most useful annotations from Java is being able to place "@deprecated" on a method signature so that any calling clients are aware they are using a deprecated method and can either annotate to ignore it, or fix their code. Even with Doc tags and reflection it's not really feasible to get that level of annotation support with PHP though. I guess Java has the advantage that the compiler is the thing which reads the annotations rather than runtime code (for the most part).

    Looking forward to browsing over your code this weekend, after my hangover has subsided perhaps

    EDIT | I agree there's no need to start a new thread since this is at the top and it makes little sense to scatter the information between two threads.

  22. #22
    SitePoint Zealot johno's Avatar
    Join Date
    Sep 2003
    Location
    Bratislava, Slovakia
    Posts
    184
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Quote Originally Posted by Chris Corbyn View Post
    Looking forward to browsing over your code this weekend, after my hangover has subsided perhaps
    Cool, looking forward to your suggestions.
    Annotations support for PHP5
    TC/OPT™ Group Leader

  23. #23
    SitePoint Member
    Join Date
    Apr 2004
    Location
    california, usa
    Posts
    7
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Quote Originally Posted by johno View Post
    Addendum still lives!

    I've just added new features including:

    Nested arrays with mixed key/value pairs
    Code:
    /** @Annotation({1, 2, {3, 4}, pi = 3.141592}) **/
    Class AnnotatedClass {}
    Support for multiple annotation instances of same class on one target.
    Code:
    /**
      @Annotation("fist")
      @Annotation("second")
     */
    Class AnnotatedClass {}
    Parsing speed improvements.

    Updated tutorial/documentation http://code.google.com/p/addendum/wi...orialByExample

    Meta-annotation @Target and customized user constraints checking.
    http://code.google.com/p/addendum/wiki/AdvancedFeatures

    Does anybody knows any projects/frameworks/libraries that would need such annotations? ORMs?
    Well, I have been doing a lot of research on frameworks in PHP. I haven't found one yet that is "perfect".. Everything is of course using MVC concepts. I came across a project called Naked Objects and I like some of the ideas there. Basically, you write one object (instead of three like MVC) and the framework generates the rest (the View and Model objects). Its only for Java and it uses annotations to add extra information to object methods (like validations to add to a web form, etc).

    While I probably would not do a wholesale port of Naked Objects to PHP, I would like to see the basic concepts done. And thats where I did a search and stumbled onto this thread about your php version of annotations.

    So I may very well start using your Addendum to create a PHP-Naked Objects framework..

  24. #24
    SitePoint Zealot johno's Avatar
    Join Date
    Sep 2003
    Location
    Bratislava, Slovakia
    Posts
    184
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)
    Cool. If there is anything you will lack in Addendum, just open a new feature request in issue tracker at google code.
    Annotations support for PHP5
    TC/OPT™ Group Leader

  25. #25
    SitePoint Member
    Join Date
    Apr 2004
    Location
    california, usa
    Posts
    7
    Mentioned
    0 Post(s)
    Tagged
    0 Thread(s)

    annotating parameters

    It does not seem possible to do annotations on the parameters of a method
    or function (I don't see a getDocComment on the php parameter reflection
    class so I assume this is not possible). Is that true?
    --
    Trixbox CE Developer
    Fonality, inc.


Bookmarks

Posting Permissions

  • You may not post new threads
  • You may not post replies
  • You may not post attachments
  • You may not edit your posts
  •