Sunday, February 25. 2007
Porting JavaDoc comments to PHP was one of the best things, that ever happened to to PHP4. But like in Java 4, the DocBlocks in PHP evolved from plain documentation to a feature that adds meta information to classes, methods, properties and variables. IDEs, like Zend Studio, use the @var tag to enable type hinting for method return values, which would not possible without the DocBlock, as PHP is a dynamic languages. Furthermore, there are projects like /a href="http://www.stubbles.org/exit.php?url_id=92&entry_id=8" onmouseover="window.status='http://pear.php.net/package/Services_Webservice';return true;" onmouseout="window.status='';return true;" title="Services_Webservice homepage">Services_Webservice or /a href="http://www.stubbles.org/exit.php?url_id=93&entry_id=8" onmouseover="window.status='http://pecl.php.net/package/SCA_SDO';return true;" onmouseout="window.status='';return true;" title="SCA homepage">SCA, which add custom tags to the docblock to mark a method or class as a service and allow you to generate WSDL and a full-blown webservice server without the need to write additional code.
In /a href="http://www.stubbles.org/exit.php?url_id=94&entry_id=8" onmouseover="window.status='http://www.stubbles.net';return true;" onmouseout="window.status='';return true;" title="Stubbles homepage">Stubbles, we are taking the same approach to add meta-information to our classes but on a more generic level. Through our /a href="http://www.stubbles.org/exit.php?url_id=95&entry_id=8" onmouseover="window.status='http://www.stubbles.net/wiki/Docs/Reflection';return true;" onmouseout="window.status='';return true;" title="Stubbles' extented reflection API">extended reflection API, we offer the ability to add annotations to classes, properties, methods or functions.
These annotations must have the following format:
This annotation is used in the /a href="http://www.stubbles.org/exit.php?url_id=96&entry_id=8" onmouseover="window.status='http://www.stubbles.net/wiki/Docs/XMLSerializer';return true;" onmouseout="window.status='';return true;" title="XMLSerializer documentation">XMLSerializer, to define how an object, property or method return value should be marshalled into XML. So it can be used like this:
To be able to extract this information, you need to define a class named /a href="http://www.stubbles.org/exit.php?url_id=97&entry_id=8" onmouseover="window.status='http://www.stubbles.net/browser/trunk/src/main/php/net/stubbles/xml/serializer/annotations/stubXMLTagAnnotation.php';return true;" onmouseout="window.status='';return true;" title="The real stubXMLTagAnnotation">stubXMLTagAnnotation, that provides a setTagName() method:
Now you are all set, to fetch the information stored in the @XMLTag annotation of the class Foo by using the stubReflection API:
Using this API, it is very easy to access the meta information, without having to worry about parsing the DocBlocks yourself.
Still, I would be very happy to see built-in annotation support in PHP6, that does not use comments, but allows us to write code like this:
To define the annotation, we would use code like this:
The keyword annotation is used to mark this class as an annotation class so the parser knows, that it can be used as an annotation. The same should be available for interfaces, so we could use an interface name as the annotatation name and provide different implementations for the same annotation:
To specify the concrete implementation of the annotation, I'd recommend the following syntax:
As Stubbles already provides all of the above features, you might wonder, why I want this in PHP 6. Here are some of the reasons:
So it would definitely be worth to include this feature into PHP, even it is already available in Java . Splitting annotations in an interface and an implementation, PHP annotations would even be a lot more powerful, then they are in other langauges. This way they could be used to inject arbitrary code in your method calls, so they'd even allow you to take a small step in the direction of AOP.
/a href="http://www.google.com/url?sa=D&q=http://www.stubbles.org/archives/9-Wishlist-pt-3-opposed-specifications-instead-annotations.html" >Wishlist pt 3 opposed: specifications instead annotations
In part three of his wishlist for PHP 6 Stephan wrote that he would like to see annotations built into PHP 6 directly. I disagree with him about that. Annotations can be done in userland, without any problems. He already gave some examples of projects tha
Tracked: Feb 25, 15:42
Display comments as (Linear | Threaded)
Still on the Java Lite path? There are other (and more powerfull) ways of doing meta programming besides annotations (just look at Ruby).
Since the core PHP team already has stated there will be no major engine additions other than those already presented a more realistic solution would be adding a docblock/annotation parser to the Reflection API.
#1 Mark Twain on 2007-02-25 14:06
I'm also pretty sure, that this will not be added in PHP 6, that's why I call it my "wish-list"
I'll promise to take a closer look at meta programming in Ruby. Whenever I saw some Ruby code, I just thought, it looks ugly...
Been living under the curse of C-style syntax for too long? You might have a look at RSpec (http://rspec.rubyforge.org/) and Rake (http://rake.rubyforge.org/) for examples of meta programming in Ruby.
#1.1.1 Mark Twain on 2007-02-25 15:15
Because some people want to add good things that have already been introduced in other languages, doesn't mean it's bad. I love annotations as a way to metadata code. I know it can be done in userspace, but havining it native is much faster and defines a standard way. xml parsers can also be written in userspace.......
#1.2 David on 2007-02-25 20:02
Of course adding features from other languages isn't bad per definition. However, adding a feature introduced to work around problems related to static typing to a dynamic language like PHP might not be so good. Java annotations is such a feature.
I'd like to see addition of more general meta programming features rather than an annotations exclusively construct.
To define a standard way an annotations implementation utilizing these new meta programming features could be added to the PHP core library.
Oh, and if performance is your primary concern.... why don't you stick to assembly?
#1.2.1 Mark Twain on 2007-02-26 20:17
I love annotations! This post was one of the many I referenced early on, when I started designing my own library.
In my opinion, the mistake made by you and countless others, is to invent new syntax. Although your syntax is closer to standard PHP-DOC syntax than some libraries, you've added custom syntax for properties and values.
PHP has (familiar and readily available) syntax for that already. Okay, so you saved a few keystrokes - but you lost all of your standard PHP language features. The only new syntax you should need, is @name... everything you're trying to do between the parentheses, PHP already has syntax for - and the rest is PHP-DOC, an already well-defined, widely accepted and broadly supported standard, plus a pair of parentheses.
Have a look at my project's Wiki for more information:
/a href="http://www.stubbles.org/">Frontpage - /a href="#topofpage">Top level
Powered by /a href="http://www.s9y.org">s9y - Design by /a href="http://www.mistralys.com/">Mistralys