There and Back Again

My blog and the rest of my sites are back up again, running on new hardware.

The 2nd backup server/thumbnail processor is still waiting on some heat sinks before it can get installed but now were running on a server with next day dell support.

I’ll have more details on webthumb changes once the dns has been updated. But the biggest difference will be a full time backup API which will be available all the time and support transparent fail over.

The pear wiki, and phpdoc.org should be back as well.

There will be a server outage today starting around 6:30pm Arizona Time

The servers will be getting new IPs during this time so assuming we don’t run into DNS problems everything should be back up in around 2 hours.

I will twitter the status of the outage since this blog will be down too.

Services affected include:

• Webthumb
• svn.pear.php.net
• phpdoc.org
• this blog
• My other random sites

If you are a webthumb customer and have any concerns email me at jeichorn at gmail.com
Hopefully I will have an alternate endpoint up during the outage, but I just heard about the data center problems 15 minutes ago so I’m not sure if i will get it up in time.

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

If you’ve ran into problems with the menus at phpdoc.org in IE7 you should be good now.

I switched from them being CSS driven to them being jquery driven.

There is nothing like jquery for dom manipulation.

$(document).ready(function() {
        $('#nav ul > li').mouseover(function(e) {
                $('#nav ul ul').hide();
                $(this).find('ul').toggle();
        });
});

The phpDocumentor team is just about ready to do a bug fix release. The code is sitting on the server and ready to be uploaded, we just want to get some extra testing done.

If you could install 1.3.2 do your normal documentation run, and leave a note on this post I’d be grateful. The bug fixes have all been tested but you never know what can creep in during the packaging process.

Pear download

pear upgrade http://bluga.net/projects/phpDocumentor/PhpDocumentor-1.3.2.tgz

Non-PEAR download (extract and go)

Update (2007-04-04) we made some small changes to the build, mainly making sure everything knows its version 1.3.2

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 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

As you might have noticed HTML_AJAX is licensed under the PHP license. It is mainly because it borrows some JavaScript for JPSpan that was released under this license. It has been brought to my attention that there are a number of conditions in the license make its distribution problematic.

The problematic items (at least from a Debian packaging prospective are)

3. The name “PHP” must not be used to endorse or promote products
derived from this software without prior written permission. For
written permission, please contact group@php.net.”

4. Products derived from this software may not be called “PHP”, nor
may “PHP” appear in their name, without prior written permission from
group@php.net. You may indicate that your software works in
conjunction with PHP by saying “Foo for PHP” instead of calling it
“PHP Foo” or “phpfoo”

6. Redistributions of any form whatsoever must retain the following
acknowledgment: “This product includes PHP, freely available from
http ://www.php.net/”.

Generally these terms don’t apply well to stuff that isn’t PHP.

Anyhow how have other people approached this problem. For phpDocumentor im looking towards just doing a dual license with PHP and BSD, just because its been PHP licensed for so long. If I can get Harry to relicense the code I used I might just release HTML_AJAX on the BSD license for the next release, otherwise I guess im stuck unless I finish up all the JS refactoring I have planned.

Update:
Charles Fry wrote up Debian’s concerns and sent them to pear-dev if you want more details on why the license is a problem.

From the release Announcement:

PHP Documentor integration

PHP Documentor is actually the best solution to generate documentation based on PHP code comments. As more and more of you are using this tool, we have integrated its features inside the IDE providing a front-end to its options. This front-end will be available both as a standalone version and an integrated module.

Download links and information about the IDE’s less important features are available in the Release notes.

This is reprint of an email I sent out to pear-dev and the php user groups im active at:

There comes a time in a projects life when even though its been successful and widely used its founders are no longer able to develop it to the extent it needs.
phpDocumentor has reached that point, Greg and I have pushed the project forward for 5 years now, but thats also the problem its just Greg and I.
The bug reports and feature requests keep coming, but the developer time doesn’t.

So this is where you come in, we need some help.

Currently were looking for people to fill in the following roles.
1. People to work on a new Task oriented phpDocumentor guide
2. People to help out with the website, finding articles about phpDocumentor, users of phpDocumentor, and working on the FAQ
3. People to review, triage, write test cases and manage bug reports
4. People to work on new features and refactoring
5. A release manager to handle releases to SourceForge and PEAR, helping with release notes, and tracking down bug fixes

If you’re interested just sign up on the mailing list at: http://lists.bluga.net/mailman/listinfo/phpdocumentor-devel
Send a email introducing yourself and say what you’d like to help with. I’ll currently in London, England so if your in a different time zone
there might be a bit of delay on me replying but if I’m around i’ll attempt to respond as soon as possible.

thanks
-Joshua Eichorn

http://phpdoc.org

Ok I had a bit of a talk with Greg today about phpDocumentor’s future.

I think I convinced him we don’t want to go off into rewrite never-never land for a couple years (read what Joel has to say about rewrites).

So the current plan looks something like this.

1. Merge release_1_2_0 branch back to head (done)
2. Create a quick destination overview (below)
3. Start refactoring

Ok so we want to end up with a model like this:

CommandLineInterface----|
			|------------FlowControl
WebInterface------------|		  |
			|		  |
			|		  |
		ConfigurationStore	  |-------Parser
					  |
					  |-------ClassReflectionTree
					  |
					  |-------DocblockReflectTree
					  |
					  |-------UsesCalculator
					  |
					  |-------DependencyCalculator
					  |
					  |-------TreeWalker
					  |
					  |-------ConvertorCore
							|
				-----------------------------------------
				|					|
			EventImplementation			    Renderer
									|
								     Savant

This means two things, we have a target. Just checkout head to submit patches from.

If you want to help just subscribe to the developer mailing list and introduce yourself.

I just found an article on builder.net about phpDocumentor. Gives a nice overview of what can be done. Our web monkey is also working on updating the phpDocumentor website so soon i’ll have a listing there of all the articles I can find.

If you know of any phpDocumentor articles out there please post them as a trackback or a comment on this article.

phpDocumentor is a big project, and that might make it a little harder for people to get started on it, but just like any project there are a number of easy entries points.

The first is the basic command line and web interfaces. They are made up of only a couple files but that the developers main interaction with the project and also for a number of bugs (#2 and #5 on my last post).

The most important file for both web and cli interfaces is phpDocumentor/Io.inc, the methods in there build and parse options as well as containing some pretty cool methods for matching and ignoring files.

Interface files:

• phpdoc – Shell/Php loader script for cli interface
• phpdoc.bat – Windows equiv to phpdoc
• index.html – Loader file for the web interface
• phpDocumentor.ini – base configuration file
• docbuilder/* – The web interface
• phpDocumentor/phpdoc.inc – Cli bootstrap
• phpDocumentor/common.inc.php – Load ini files setup basic constants
• phpDocumentor/Io.inc – Find files, parse command line parameters

Now I don’t know if basics like this are actually useful, some feedback on what would help a person get started would be great.

I was going to use this as an introduction to my overview post but it seems my lack of shell scripting made things a little harder then I thought.

Anyhow if you don’t count html or compiled templates the 1.2.0 branch of phpDocumentor (these is where 1.3.0x lives), contains 69,847 lines of code. If you add in the documentation that Greg has written were up to 75,257 lines.

Thanks to my co-worker Charles for helping me out.

And the code I ended up using is:
cat `find * | egrep "php$|inc$" | egrep -v "templates_c"` |wc -l

Update:
I ended up including ini files and html files and removing the embedded Smarty and Html Tree menu, for maybe a more accurate count.
Without ini files: 60,322
With ini files: 70,335

Below is a list of bug that I think are easy fixes.

1. 940932 – Manual Version is wrong
2. 951902 - Shell return values for automatic scripting
3. 935785 - the new CSS unviewable with Konqueror
4. 924760 - source rendering in FireFox contains extra newlines
5. 1043330 - Make Command Line Parser support shorter syntax
6. 964248 - Convert invalid characters in package/subpackage names to _

If your interesting on getting started on one of these bugs sign up on the developer list and send an email. I can point you to the classes/files you’ll need to look at to get started hacking.

Since were working on a branch you’ll want to use something like the commands below to checkout code to get started:

cvs -d :pserver:anonymous@phpdoc.org:/opt/cvsroot login
cvs -d :pserver:anonymous@phpdoc.org:/opt/cvsroot co -r release_1_2_0 phpdoc


Another great PhpLondon meeting, made it home by 1am, and didn’t miss any trains.

Spent a lot of time talking about requirments, and saw a demo of an interesting project that implemented dynamic proxying in php (though the code seemed to be a lot more complex then it needed to be).

But i ended the evening on a topic that i’ve been working at for the last 5 years, phpDocumentor.

Now some might saw that phpDocumentor is a successful project, and in some ways it is (all time rank on source forge of 829, 50,000 sf downloads + another 40,000 from pear) but on the number that really drives an open source project were not doing so good.

That important # is active developers, at the moment its really 0. Yep thats right 0, I’m more or less in maintenance mode, put a patch in, respond to bugs queries. And while Greg will be back at some point for now he is working on the PEAR installer. So that leaves no one.

So this is my plan to change things a bit. It means i’ll get a bit more involved for the next few months, and will try to see what it takes to take “I want to help out phpDocumentor” to a new member of the phpDocumentor team.

I will do:

1. Create a list of getting started bugs for new developers to work on
2. Create test cases using simple test for each bug (Marcus promised to help)
3. Create a new mailing list for the project at phpdoc.org (developer-list@phpdoc.org)
4. Commit any back logged patches, and create a short howto how to make a patch
5. Annouce a contest to the PhpLondon and AzPHP users groups where bug fixes will be rewared with prizes (pints of beer unless anyone has a better suggestion)
6. Write up an overview of the phpDocumentor design, and show how to tackle just one part of it, instead of the whole huge code base
7. Blog lots about phpDocumentor and try to get people excited about helping.

What im trying to get out of this is:

1. 2 new developers who fix bugs/commit code on a regular basis
2. Activity outside of some php user groups besides posting on a list or going to a meeting (ie giving back to the php community)
3. A developer to take over the phpDocumentor release process, i’ll still be around but I just don’t have the time and energy to keep pushing in patches, keeping people organized and keeping up a regular release schedule

So if you want to help here’s what you do sign up on the new list (or comment right here). And post on how you think I can help people getted started working on phpDocumentor. If you have time and energy to help that would be even better, sign up and will get the process rolling.

Please remember, I don’t want to spend time setting up source forge and cvs accounts, I don’t need 10 more I want to helps that go no where. So these starter bug fixes will all be patch based, and once you’ve proven your ready to stay with things will set accounts up from there.

Jason Sweat has slides from a presentation titled “Documenting PHP Applications” that he gave at PHP|Works in Toronto. I wish I could have seen the presentation, the slides are great.

If your new to phpDocumentor reading the slides is a great place to start. He does a great job of showing off the basic features, and gives some nice examples of the code -> document path. Made me feel like Jason knows more about phpDocumentor then me .

On a slightly related note, there are some people having problems running phpDocumentor on OSX if someone runs it and would be willing to help debug, I’d be greatful.

I’ve been seeing brute force attempts on the phpdoc.org server for about 2 weeks now.

Stuff like:
sshd:
Invalid Users:
Unknown Account: 16 Time(s)
Authentication Failures:
unknown (colob166074.serverpark.com ): 4 Time(s)
unknown (cmcc203.cm.nctu.edu.tw ): 12 Time(s)
root (cmcc203.cm.nctu.edu.tw ): 6 Time(s)

Illegal user test from 140.113.236.203
Illegal user test from 140.113.236.203
Illegal user guest from 140.113.236.203
Illegal user guest from 140.113.236.203
Illegal user admin from 140.113.236.203
Illegal user admin from 140.113.236.203
Illegal user admin from 140.113.236.203
Illegal user admin from 140.113.236.203
Illegal user user from 140.113.236.203
Illegal user user from 140.113.236.203
Illegal user test from 140.113.236.203
Illegal user test from 140.113.236.203
Illegal user test from 69.67.166.74
Illegal user test from 69.67.166.74
Illegal user guest from 69.67.166.74
Illegal user guest from 69.67.166.74

Not that i know anyone who has a guest,test,user, or admin account, but if you have one i would suggest, renaming it, and making sure it has a good password.

Also i would interested to know if someone else is seeing this same pattern or has some more info about it.

I’ll be giving the presentation at my local PHP users group, AzPHP, tonight. The topic will be “an Introduction to phpDocumentor” i’ll be going through a number of hello world type examples, and then showing some of the more complex functionality by looking at some of the ways phpDocumentor documents itself. I’ll also be answering any questions that people might have.

The meeting starts at 7pm at Walts TV in Tempe.

The AzPHP website has more details and a map.