Links to know about
Music
The Chiara String Quartet
Chiara Quartet (MySpace)
Greenwood Music Camp
UNL School of Music
PHP
PEAR Installer Manifesto
phpDocumentor
PEAR
phar
docblock
PHP_Parser
PHP_Parser_DocblockParser
PHP_ParserGenerator
PHP_LexerGenerator
PEAR_PackageFileManager
PHP_Archive
Games_Chess
Blogs
Joshua Eichorn
Paul M. Jones
Davey Shafik
Popular Entries
Setting up your own PEAR channel with Chiara_PEAR_Server - the official way
(26)
Do you develop a website? It is infinitely better to synchronize live and development sites using the PEAR Installer(25)
doing the PEAR thing(19)
Using PEAR 1.4.0 to install PEAR packages on a remote host(19)
phpDocumentor and __get/__set/__call - give us your ideas (RFC)(17)
Categories
Syndicate This Blog
Powered by
Thursday, July 13. 2006
phpDocumentor and __get/__set/__call - give us your ideas (RFC)
One of the trickier feature requests for phpDocumentor has been documenting "magic" object properties and methods. By "magic" I am referring to properties and methods that are created dynamically by PHP 5.0+ userspace class methods __get, __set, __isset, __unset and __call. For instance, this code creates a read-only property named $foo and a write-only property named $bar and a regular property named $regular as well as a magic function borp() that accepts two parameters.
<?php
class blah
{
private $_thingy;
private $_bar;
function __get($var)
{
switch ($var) {
case 'foo' :
return 45;
case 'regular' :
return $this->_thingy;
}
}
function __set($var, $val)
{
switch ($var) {
case 'bar' :
$this->_bar = $val;
break;
case 'regular' :
if (is_string($val)) {
$this->_thingy = $val;
}
}
}
function __call($method, $params)
{
if ($method == 'borp') {
if (count($params) == 2) {
return $params[0] * $params[1];
}
}
}
}
?>
class blah
{
private $_thingy;
private $_bar;
function __get($var)
{
switch ($var) {
case 'foo' :
return 45;
case 'regular' :
return $this->_thingy;
}
}
function __set($var, $val)
{
switch ($var) {
case 'bar' :
$this->_bar = $val;
break;
case 'regular' :
if (is_string($val)) {
$this->_thingy = $val;
}
}
}
function __call($method, $params)
{
if ($method == 'borp') {
if (count($params) == 2) {
return $params[0] * $params[1];
}
}
}
}
?>
In order to document this stuff, we want to add 4 new tags that would only be recognized in a class docblock. They are:
- @property - magic class variables that can be both read and written to
- @property-read - magic class variables that can only be read
- @property-write - magic class variable that can only be written to
- @method - magic class methods
@property and company would have this basic format:
@property type $varname [description]
@method would have this basic format:
@method returntype function_name(type $param1[ =][, type $param2[ = ]...]) [description]
So, in order to document the previous example code, we would use:
<?php
/**
* show off @property, @property-read, @property-write, @method
*
* @property mixed $regular regular read/write property
* @property-read int $foo
* @property-write string $bar
* @method int borp(int $int1, int $int2) multiply two integers
*/
class blah
{
private $_thingy;
private $_bar;
function __get($var)
{
switch ($var) {
case 'foo' :
return 45;
case 'regular' :
return $this->_thingy;
}
}
function __set($var, $val)
{
switch ($var) {
case 'bar' :
$this->_bar = $val;
break;
case 'regular' :
if (is_string($val)) {
$this->_thingy = $val;
}
}
}
function __call($method, $params)
{
if ($method == 'borp') {
if (count($params) == 2) {
return $params[0] * $params[1];
}
}
}
}
?>
/**
* show off @property, @property-read, @property-write, @method
*
* @property mixed $regular regular read/write property
* @property-read int $foo
* @property-write string $bar
* @method int borp(int $int1, int $int2) multiply two integers
*/
class blah
{
private $_thingy;
private $_bar;
function __get($var)
{
switch ($var) {
case 'foo' :
return 45;
case 'regular' :
return $this->_thingy;
}
}
function __set($var, $val)
{
switch ($var) {
case 'bar' :
$this->_bar = $val;
break;
case 'regular' :
if (is_string($val)) {
$this->_thingy = $val;
}
}
}
function __call($method, $params)
{
if ($method == 'borp') {
if (count($params) == 2) {
return $params[0] * $params[1];
}
}
}
}
?>
This example is rather poor usage of __get/__set/__call, but our point is the documentation, so ignore that for now 
. We will be accepting feedback for about two weeks, and at that point will announce the decision of how these things will be documented at http://www.phpdoc.org. If you are a developer of an IDE and would like to standardize this decision, or are a user with a real need for this feature, please let us know if there is a better way of doing that that we have not thought of. Comment on this entry or send an email to cellog at the-language-we're-talking-about.net
Trackbacks
Trackback specific URI for this entry
No Trackbacks
Comments
Display comments as
(Linear | Threaded)
Hi Greg,
Users will need the flexibility to document their magic methods and properties from anywhere within the class, as something added to an array inside __construct() might be defining something which is accessed through __get(). I.e.:
class foo {
private $readOnly = array();
function __construct() {
/** @newMagic__get 'bar'
* bar contains a common number
*/
$this->readOnly['bar'] = 42;
}
function __get($var) {
return $ths->readOnly[$var];
}
}
They might also need the ability to add a more generalized docBlock before '__get()' and friends to describe a more variable range of properties and methods. E.g., if __get($var) is called and $var begins with 'ENV_' it returns that key from $ENV_. Users will need to be able to document such non-specific behaviour as well.
regards,
Peter
Users will need the flexibility to document their magic methods and properties from anywhere within the class, as something added to an array inside __construct() might be defining something which is accessed through __get(). I.e.:
class foo {
private $readOnly = array();
function __construct() {
/** @newMagic__get 'bar'
* bar contains a common number
*/
$this->readOnly['bar'] = 42;
}
function __get($var) {
return $ths->readOnly[$var];
}
}
They might also need the ability to add a more generalized docBlock before '__get()' and friends to describe a more variable range of properties and methods. E.g., if __get($var) is called and $var begins with 'ENV_' it returns that key from $ENV_. Users will need to be able to document such non-specific behaviour as well.
regards,
Peter
A very interesting problem.
Would it be feasible to keep the docblocks with the magic methods, instead of at the class level, and then collect them to determine what is readonly/writeonly/readwrite?
Would it be feasible to keep the docblocks with the magic methods, instead of at the class level, and then collect them to determine what is readonly/writeonly/readwrite?
I second this idea -- I was just going to add the same comment myself.
Keeping them with the magic methods makes more sense to me -- effectively, you're documenting what properties/behaviours the magic method implements.
Additionally, you could then omit the property-read/property-write tags. A 'property' tag for a __set() method is an implicit property-read; similarly, a __get() property tag implies property-write.
Keeping them with the magic methods makes more sense to me -- effectively, you're documenting what properties/behaviours the magic method implements.
Additionally, you could then omit the property-read/property-write tags. A 'property' tag for a __set() method is an implicit property-read; similarly, a __get() property tag implies property-write.
Originally, this was my idea as well, but questions of maintenance arise. In other words, it is far more complicated to implement in this way, both in terms of making sure things like @property only occurs for __get/__set and @method for __call. Also, in order to determine whether a property is read/write, read-only, or write-only, you have to manually grok the docblocks for both __get and __set.
With the proposed solution, everything is in 1 place, which is both simpler to implement internally, and also easier to read and to detect errors. Plus, although the implementation is in __get/__set/__call, the magic properties/methods belong to the class.
In other words, I no longer see the benefits of what you're proposing even though that was originally my idea (Derick convinced me otherwise in an IRC chat.
With the proposed solution, everything is in 1 place, which is both simpler to implement internally, and also easier to read and to detect errors. Plus, although the implementation is in __get/__set/__call, the magic properties/methods belong to the class.
In other words, I no longer see the benefits of what you're proposing even though that was originally my idea (Derick convinced me otherwise in an IRC chat
.
The problem with these magic methods is their magicness. Say I have a magic method __get that handles a getter for $a and $b, and I document these as:
@property $a
@property $b
Then I'm basically, in my documentation, limiting my magic to these 2 variables, and if I'm doing that, why wouldn't I have made ordinarty getters for those in the first place?
I see two practical uses for __get and __set.
1. Controlling access to member variables. These member variables are usually defined in the class, so they are already documented.
2. Forwarding of stuff to other objects. In thase case, anything is forwarded, so I can't really document which properties it supports, as this depends on the object for which it is being forwarded. (see examples of this forwarding in my blog
So in my opinion, a way of documenting the magic *behaviour*, instead of the properties it accepts, is better. So I'd rather have something like:
/**
* @getters This class has a magic getter
* for forwarding properties to the object
* passed in the constructor.
*/
And you can always decide to add a list of accepted properties to that block.
@property $a
@property $b
Then I'm basically, in my documentation, limiting my magic to these 2 variables, and if I'm doing that, why wouldn't I have made ordinarty getters for those in the first place?
I see two practical uses for __get and __set.
1. Controlling access to member variables. These member variables are usually defined in the class, so they are already documented.
2. Forwarding of stuff to other objects. In thase case, anything is forwarded, so I can't really document which properties it supports, as this depends on the object for which it is being forwarded. (see examples of this forwarding in my blog
So in my opinion, a way of documenting the magic *behaviour*, instead of the properties it accepts, is better. So I'd rather have something like:
/**
* @getters This class has a magic getter
* for forwarding properties to the object
* passed in the constructor.
*/
And you can always decide to add a list of accepted properties to that block.
Hei Greg,
You know what I think about this and just to be clear I like the idea that you proposed above. The reasons that we want to want to have it in the class because they are properties *of* the class so that is the most logical place to put them. Maintainability is also better in that case. It is also more obvious whether things are read or write or both for example without having to look in two places in your documentation.
Derick
You know what I think about this and just to be clear I like the idea that you proposed above. The reasons that we want to want to have it in the class because they are properties *of* the class so that is the most logical place to put them. Maintainability is also better in that case. It is also more obvious whether things are read or write or both for example without having to look in two places in your documentation.
Derick
Hi Derick,
These arguments are precisely the reason our conversation on IRC successfully won me over to the "do-it-in-the-class-docblock" approach
These arguments are precisely the reason our conversation on IRC successfully won me over to the "do-it-in-the-class-docblock" approach
Hei,
just to let you know... a co-worker created a patch for this now, which we're going to send you soonish. Just to make sure we're not duplicating work yet
regards,
Derick
just to let you know... a co-worker created a patch for this now, which we're going to send you soonish. Just to make sure we're not duplicating work yet
regards,
Derick
Is there any update to the status of this patch? This would be very helpful for a few projects I'm working on.
We made a patch for this, and we're already using it for the eZ components documentation. See http://ez.no/doc/components/view/latest/(file)/Mail/ezcMail.html#sec-prop-summary for how it looks like, and the patch is at: http://sourceforge.net/tracker/index.php?func=detail&aid=1540666&group_id=11194&atid=311194
I've tested and slightly reworked Derick's patch, and added method handling to it. It is available at Sourceforge (same patch #1540666).
We'll should be releasing v1.4.0 soon, which will highlight this new feature.
We'll should be releasing v1.4.0 soon, which will highlight this new feature.
Yes, still use it the same way and results look the same... also, method tag looks/acts just like the property tag...
This feature is on the v1.4.0a1 roadmap (http://pear.php.net/bugs/roadmap.php?package=PhpDocumentor#a1.4.0a1)
Hei ,Left version 2.0.0a1. Who tested it? If there is bugs report here, but that one headache with her.
Links in this article
- is_string[331]
- count[264]
- http://www.phpdoc.org[739]
PEAR Installer Manifesto
Calendar
|
July '08 | |||||
| Mon | Tue | Wed | Thu | Fri | Sat | Sun |
| 1 | 2 | 3 | 4 | 5 | 6 | |
| 7 | 8 | 9 | 10 | 11 | 12 | 13 |
| 14 | 15 | 16 | 17 | 18 | 19 | 20 |
| 21 | 22 | 23 | 24 | 25 | 26 | 27 |
| 28 | 29 | 30 | 31 | |||
Quicksearch
My Latest Releases
Top Exits
pear.php.net (321)
www.php.net (101)
pecl.php.net (78)
pear.chiaraquartet.net (73)
news.php.net (65)
www.php.net (101)
pecl.php.net (78)
pear.chiaraquartet.net (73)
news.php.net (65)