There and Back Again

The PhpDocumentor team hopes to release the final 1.4.0 stable feature release on 7/20. If you have test-driven any of the recent pre-releases for 1.4.0 (alpha1, alpha2, RC1, RC2), please let us know any good/bad feedback you have from that experience.

Changelogs:
1.4.0RC2
Includes no PEAR items:

Includes these Sourceforge items:
- [1733938] regression: “-” not allowed anymore in converter (file)name
- [1733936] “phpdoc” does not return with error code “0″ on success
- [1733345] inline @link tag renders wrong way
- [1722096] DocBlock template example does not work

1.4.0RC1
Includes these PEAR items:
Bug #11409: PHP Notices accompany Global Never Found errors

Includes these Sourceforge items:
- [1724990] @static tag example
- [1724884] object return parameter value
- [1720764] documentation update needed
- [1672589] missing elements, bad links with HTML:Smarty:HandS
- [1634153] require/include with concatenated file name
- [1632496] {@internal}} becomes wrong on documentation
- [1124133] <code> and @include….

1.4.0a2
Includes these PEAR items:
Bug #10864: PhpDocumentor dies when parsing illegal page-level docblock
Bug #10870: Dead links generated with HTML:Smarty:PHP Bug 10871: Wrong rendering of inline {@internal}}
Bug #10910: DOM templates create incorrect trees
Doc #10914: Can’t use nested tags inside or
Doc #10972: @method does not work
Doc #11032: param type1|type2 not documented
Doc #11143: Provide a Minimal Tutorial File Setup Example

Includes no Sourceforge items.

1.4.0a1
Includes these PEAR items:
Req #10670: Don’t Die on Empty Tag Descriptions
Doc #10675: Clear some errors.html items
Doc #10730: Replace Sourceforge Trackers with PEAR

Includes these Sourceforge items:
- [1647423] memory_limit: bad if-clause
- [1622538] List undocumented classes/functions
- [1602988] Added –ignore-symlinks option
- [1588942] Allow memory_limit setting in phpdoc.ini
- [1588936] Show INI Path at Startup
- [1585840] Refactored RETURNs #3
- [1574047] Refactored RETURNs #2
- [1574043] Refactored RETURNs #1
- [1543289] Apply ignore patterns to subdir of dir, instead of full path
- [1543287] Use predefined PHP env var in phpdoc script
- [1540666] patch for @property, @property-read and @property-write tags
- [1044752] List undocumented classes/functions

The PEAR group and president now have a blog. We will be using it to make announcements and to ask the community for feedback. I think this is a big step towards making PEAR a more transparent project.

I just quickly hacked up a theme for it so if you don’t how the blog looks you can blame me. Of course a more useful thing to do in that case would be to send me an updated css file.

I’d like to thank everyone who left a comment on my last post about How you would improve PEAR. You’ll be happy to know that were already working on many of your suggestions, Greg’s post on the subject has some more details. I’ll be sharing everyones comments with the rest of the PEAR group at our meeting on the 13th, so if anyone has a suggestion they haven’t submitted yet thats your deadline.

Out of all the suggestions the one I’m most excited about is starting a mentoring program to help developers get involved with PEAR. This is someone we were already planning on doing so now its just a matter of getting the details taken care of. I’m not sure if will end up with an official sign up for a mentor or some other process but until then, if your interested in getting started as a PEAR developer and want a mentor send me an email and i’ll find a mentor for you.

Also if anyone left a comment and it didn’t show up it got caught in my spam filters. I get about 500 blog spams a day so I can’t easily check the filter for false positives. If you think this happened to you shoot me an email and post again and i’ll make sure it goes through.

You might have heard that I’m a member of the PEAR group now. Because of this I’ve been spending a lot of time thinking about what I’d like to see changed in PEAR to make it a better project. I’m slowly building up a list of ideas and at some point I’ll share it, but today I’d like to get some feedback from everyone who reads this blog.

If you were a member of the PEAR group what would you change about PEAR. Please keep in mind were not an all powerful body (Read the constitution for details), but we do have the ability to set policy, and like in any open source project we can make changes through our direct actions.

Thanks in advance for your comments.

The PEAR elections start tomorrow, if your a PEAR developer you’ll want to read people’s position statements so you can make an informed vote.

I hope these elections will be the beginning of the a rebirth of PEAR. It was a wonderful idea when it started but its been coasting for the last couple years we never did enough to embrace PHP5.

If your wondering what the whole election is about its pretty simple. A month or so again PEAR voted to accept a new constitution. This constitution, created a new position of President (Which only Greg Beaver is running for) and made the PEAR group an elected position (candidate list with position statement follows). The PEAR group’s job is to decide how PEAR should be run and too make this happen.

This election is for a term running May 1, 2007 to May 1, 2008

The following are running for the PEAR Group (Position statements are linked for their names)
Updated April 19th 2:45PM MST

• David Coallier PEAR Page
• Bertrand Mansion PEAR Page (nomination post)
• Christian Weiske PEAR Page
• Helgi Þormar PEAR Page
• Arnaud Limbourg PEAR Page (nomination post)
• Martin Jansen PEAR Page
• Paul M. Jones PEAR Page (nomination post)
• Joe Stump PEAR Page
• Joshua Eichorn PEAR Page
• Brett Bieber PEAR Page
• Stefan Neufeind PEAR Page
• Justin Patrin PEAR Page
• Mark Wiesemann PEAR Page

Some people haven’t replied with a position statement yet, so I haven’t linked to it, i’ll update this post as people’s emails make it too the list.

If I didn’t find position statements posts today I added a link to the post the person sent at nomination time.

Thanks to Greg’s efforts I’m now hosting a mirror of the PEAR channel. At the moment were only mirroring installer data not the entire website but its a start.

Things are still in the testing phase, but the mirror is usable, just run: pear config-set preferred_mirror us.pear.php.net

Right now we sync the mirrors every 4 hours, so it could be slightly out of date, but not enough to cause problems.

I hacked akismet a couple days ago to give me hourly spam statistics and then threw together a graph.

Looks like the evil spammers were at it again this morning.

The Code

Create a new table to hold the stats:

CREATE TABLE `spam_count` (
  `day` date NOT NULL default ‘0000-00-00′,
  `hour` tinyint(4) NOT NULL default ‘0′,
  `count` int(11) NOT NULL default ‘0′,
  PRIMARY KEY  (`day`,`hour`)
) ENGINE=MyISAM DEFAULT CHARSET=latin1;

Find your akismet plugin [blog root]/wp-content/plugins/akismet/akistmet.php

Find the line in akismet that updates the global spam count

<?php

update_option( ‘akismet_spam_count’, get_option(‘akismet_spam_count’) + 1 );

?>

On my version of akismet thats line 139, in the ksd_auto_check_comment function

below that line add:

<?php

                /* Hourly Spam Counting Start */
                $today = date(‘Y-m-d’);
                $hour = date(‘H’);
                global $wpdb;
                $wpdb->query(“insert into spam_count (`day`,`hour`,`count`) values(’$today’,$hour,1) on duplicate key update `count`=`count`+1″);
                /* Hourly Spam Counting End */

?>

Then post some comments to test things, make sure your logged out and post something spammy. Then check the spam_count table and make sure its got a new row in it. If so then things are working right.

Now you have the data so the next step is too add some graphs. I use PEAR’s Image_Graph so install it.

Something like the command below might work:

pear install –alldeps Image_Graph-beta


Then make a graph the code for mine is:

<?php

// uses PEAR Image_Graph http://pear.php.net/Image_Graph
require_once ‘Image/Graph.php’;

require_once( dirname(__FILE__) . ‘/wp-config.php’);

$day = date(‘Y-m-d’,strtotime(‘-24 hours’));
$today = date(‘Y-m-d’);
$hour = date(‘H’,strtotime(‘-24 hours’));

$sql = “select `hour`, count from spam_count where day = ‘$today’ or (day = ‘$day’ and hour > $hour)”;
$data = $wpdb->get_results($sql ,ARRAY_A);

$month = date(‘F’);

// create the graph
$Graph =& Image_Graph::factory(‘graph’, array(300, 300));
// add a TrueType font
//$Font =& $Graph->addNew(’font’, ‘Verdana’);
$Font =& $Graph->addNew(‘font’, ‘/usr/share/fonts/dejavu/DejaVuSans.ttf’);
// set the font size to 11 pixels
$Font->setSize(8);

$Graph->setFont($Font);

$Graph->add(
    Image_Graph::vertical(
        Image_Graph::factory(‘title’, array(“Blog Spams in the Last 24 Hours”, 12)),
        $Plotarea = Image_Graph::factory(‘plotarea’),
            //$Plotarea = Image_Graph::factory(’plotarea’,array(’axis’, ‘axis’)),
        7
    )
);

$colors = array(‘red’,‘green’,‘blue’,‘orange’,‘gray’,‘purple’);

// create the dataset
$Dataset_all =& Image_Graph::factory(‘dataset’);
foreach($data as $row) {
        $Dataset_all->addPoint($row['hour'],$row['count']);
}

$Dataset_all =& Image_Graph::factory(‘dataset’);
foreach($data as $row) {
        $Dataset_all->addPoint($row['hour'],$row['count']);
}

// create the 1st plot as smoothed area chart using the 1st dataset
$Plot_all =& $Plotarea->addNew(‘Image_Graph_Plot_Smoothed_Area’, array(&$Dataset_all));

$Plot_all->setLineColor($colors[5]);
$Plot_all->setFillColor(“$colors[2]@0.2″);
$Plot_all->setTitle(‘24 Spam’);

// format the axis

$Processor =& Image_Graph::factory(‘Image_Graph_DataPreprocessor_Function’, ‘formatTime’);
$AxisX =& $Plotarea->getAxis(IMAGE_GRAPH_AXIS_X);
$AxisX->setDataPreprocessor($Processor);
$AxisX->setLabelInterval(3);

// output the Graph
$Graph->done();

function formatTime($hour) {
        $hour = (int)$hour;
        $m = ‘AM’;
        if ($hour > 12) {
                $hour = $hour-12;
                $m = ‘PM’;
        }
        return “$hour$m”;
}

?>

The code for the graph is a little more complicated then needed since its just a hacked up version of the graphs i make for WebThumb. Anyhow then its just a matter of putting your graph script in the src of an image.

<img src="/graph-spam-last24.php"/>

Oh and you might want to add some caching if your showing the graph all the time since generating pngs is a bit more expensive then generating html.

Yesterday we released HTML_AJAX 0.5.0

It contains lots of bug fixes and a couple new features, but the biggest change is this means were commiting to a stable API. Between this release and 1.0 will be in a feature freeze, focusing on improving documentation and fixing any problems.

You can upgrade by running pear upgrade HTML_AJAX-beta

As PHP keeps added language features one of the things we have to do is figure out how to document them.

Lately I’ve been hearing requests for a way to document virtual properties and methods on classes that are implemented using __call etc.

After talking a bit with Greg, I’m leaning towards adding in some new docblock tags to classes to allow these methods/properties to be documented.

It might look something like this:

<?php

/**
 * whatever
 *
 * @property int $blah this is the short desc (no long desc allowed)
 * @property-read int $foo read-only variable
 * @property-write string $oof write-only variable
 * @method int myfunc(int $var, string $param2, Object $param3 = null) description of myfunc
 */
class magicClass {
}

?>

My big concern with this approach is it can lead to a unwieldly class level docblock and it makes it hard to add large descriptions. On the plus side this is easy to implement and normally when you have a virtual method/property it doesn’t need a lot of description.

Finally if anyone has thoughts on managing changes like this in the future let me know. Right now we consider the phpDocumentor manual to be the official guide to how things work, but im not sure if that works that well for other people writing phpdoc parsers (ide’s etc).

Related Bugs:

• PHPDoc for “member overloading”

I found a handy tutorial of building a stock lookup plugin for Wordpress using HTML_AJAX. Shows how easy HTML_AJAX makes AJAX.

The only problem I see is the code won’t work in PHP5 since introspection will return the method name as GetQuote instead of getquote.

You can fix this by adding the following to the HTML_AJAX_Server instance.

// Create the HTML_AJAX Server
$objServer = new HTML_AJAX_Server();

// Set php4 case compatability so this code will work in 4 or 5
$objServer->ajax->php4CompatCase = true;

The other option too fix this is too set all the methods you want to register which is my prefered fix since it lets you have nice case in your JavaScript functions in php4

    // Create the HTML_AJAX Server
    $objServer = new HTML_AJAX_Server();

    // Create an instance of our stock quote class
    $objStockLookup = new StockQuote();

    // Register the stock quote object with the HTML_AJAX server
    $objServer->registerClass($objStockLookup,'StockQuote','GetQuote');

If you did this you’ll also have to update the JavaScript to use the cased version of the functions.

HTML_AJAX 0.4.0 has been released. You can upgrade using the PEAR package manager in the normal ways.

The biggest new feature is the addition of a setInnerHTML method that runs any JavaScript in the string your using to update and elements innerHTML property and the addition of an ordered queue. The ordered queue makes your AJAX requests return to the client in the same order they were sent. One of the biggest area’s this comes into play is when creating livesearch implementations or any other time you’re making lots of AJAX requests and overwriting the results of the earlier ones with the results of latter ones.

More details (including a place to put testing results for your browser of choice) are available in the release notes on the HTML_AJAX wiki.

I’d also like to thank Laurent Yaish for helping with the testing of this release and Arpad Ray for working with me until we got the optimal implementation of setInnerHTML.

I woke up this morning with 52 emails from Sourceforge. Nothing like being huge loads of bug spam because Greg is working on cleaning up phpDocumentor bugs.

Anyhow I just wanted to thank Greg, and make a couple notes about what good bugs contain.

phpDocumentor Bug submission guide:

• phpDocumentor Version
• PHP Version
• OS Version
• How your running phpDocumentor, CLI, CLI+ini file, Web interface
• Instructions on howto reproduce the error
  • A simplified set of code to parse that produces the error
  • How you have phpDocumentor configured, an ini file being the prefered way rather then a mile of command line parameters

Oh patches for bugs are more then welcome, just make note that phpDocumentor 1.3.x development is taking place in PEAR cvs so make it against that.

I’m not all that active in phpDocumentor development anymore, but thanks to help from Andrew Morton, Greg was able to get a release out.

I pushed the bits out to the sourceforge site this morning, so hopefully everyone who is looking for the new release will find it. Thanks for everyone who has sent in patches or signed up on the mailing list looking to help out. I know its a big bunch of code to get started on, but if you got some time and want to help out, there are lots of bugs left to triage, and clean new phpDocumentor 2.0 development to do.

Short Release Notes

This release fixes problems with php 4.4.x, 5.0.5+ and 5.1.x

A number of other bugs were fixed see the release notes for details.

Available from PEAR or from Sourceforge

Website: http://phpdoc.org
Mailing List: http://lists.bluga.net/mailman/listinfo/phpdocumentor-devel

Pear Links:
Package home: http://pear.php.net/package/PhpDocumentor
Changelog: http://pear.php.net/package/PhpDocumentor/download/1.3.0RC4
Download: http://pear.php.net/get/PhpDocumentor-1.3.0RC4.tgz

SF Links:
Project Page: http://sourceforge.net/projects/phpdocu/
Download: http://sourceforge.net/project/showfiles.php?group_id=11194&package_id=10450&release_id=374570
Release Notes: http://sourceforge.net/project/shownotes.php?release_id=374570&group_id=11194