doing the PEAR thing

The first contact I had with PEAR was through development on phpDocumentor (link is to the left). Demand rose from PEAR developers to get phpDocumentor inside PEAR to replace its unmaintained rival, PHPDoc (www.phpdoc.de).

Back then, PEAR's reputation was almost as good for developers as some forms of the Ebola virus. The installer didn't even work on windows, and much of PEAR's code didn't measure up to solutions found through phpclasses.org or more importantly through sourceforge.net. Even more annoying, in my efforts to get phpDocumentor installable at all through PEAR, I had to jump through several annoying hoops. phpDocumentor is not a library, and is intended to work from a single location. PEAR splits up all the files and puts them into a series of unknown locations as determined by the user. I had to redesign (read: hack) some things in phpDocumentor, including double maintenance of some files. Yuck.

Unfortunately, this was not the only issue. Because of the use of Smarty and of pathnames to differentiate converters and their templates, some files were longer than 100 characters, something the .tar format does not natively support. Archive_Tar had to be modified to support filenames longer than 100 characters (and I must say Vincent Blavet did a great job of fast turnaround on this one). In addition, pear.php.net did not support uploads of files larger than 2 MB, and believe it or not, phpDocumentor is larger due to bundling of PDF fonts.

Finally, Pierre-Alain Joye managed to get the CLI installer and the web installer working on Windows, and PEAR went to version 1.0 stable. At this point, it was discovered that PEAR couldn't grapple with pathnames containing spaces, which is a real problem for users that have the default install locations of Apache (C:\Program Files\Apache Group\Apache), and that included phpDocumentor, with it's web interface.

So, I went about designing a patch to make the darn thing work. It turned out to be simple, but then I was told that the lack of support for spaces in pathnames was "not a bug." Suffice it to say that I strong-armed my patch into the PEAR installer, and that I have yet to hear anyone complain that it does support spaces in pathnames.

Next, it was getting annoying to try to install packages with dependencies, as you had to both know all of them and type all of them on the command-line. Double yuck.

I wrote the patches for --alldeps and --onlyreqdeps to solve this, which was a nice feeling.

Throughout the whole process, I was sprinting at full speed ahead through a tremendous much of political dreck. Every change had to be approved by developers who often took 6 months or more to do any review. I saw a major release of PHP go by (4.1 to 4.2) between the original approval of phpDocumentor and the time that the installer could actually install it. The nit-picking over details of my code often left me feeling vivisected.

However, I persevered because the ease of setting up phpDocumentor through PEAR turned out to be awesome. Only through PEAR can you do this and have it work out of the box:

$ pear install phpDocumentor
$ phpdoc -c myconfig.ini

For the unzip-and-go install that most PHP users are accustomed to, quite a bit of configuration is needed, including hand-editing of code.

Let me reiterate: the PEAR installer is the best thing about PEAR.

For the past year, I have been working on the aspects of the PEAR installer that still make developing phpDocumentor through PEAR living hell.

#1) sloooow blooooat.

There are two complaints I've heard consistently about PEAR:

1. it's slow
2. it's bloated

Examples cited include the PEAR.php file, which seemed to cause everything to run slowly (like DB), and the DB package, which comes with every single kind of driver for all databases ever created, whether you need them or not.

phpDocumentor also suffers from bloat, as we bundle rarely used converters (PDF, CHM, DocBook) along with the common ones (HTML flavors).

I went about fixing bloat, by devising some clever dependency support in PEAR 1.4.0, and can proudly say that it is now quite easy to safely split a package into several components and distribute them as a big lump, or split up into smaller chewable sizes.

To my surprise, I discovered that the largest problem with speed in PEAR.php was the fact that a shutdown function was registered no matter what. Most classes do not use PEAR's incredibly slow destructor emulation for PHP4, and do not need the shutdown function. So, with a small change, PEAR is no slower than any other file you might include for many packages. I haven't done any benchmarking of the change to packages like DB, so I can't speak for that.

#2) Using code from other sites is just plain impossible unless you bundle it.

This has been the single most annoying part of developing phpDocumentor through PEAR. phpDocumentor bundles:

1) HTML_TreeMenu
2) Smarty
3) Cezpdf

Maintaining, or even "upgrading" these packages is difficult, time-consuming and severly prone to error. It also means updating anything in phpDocumentor just for minor re-organization is a huge pain in the ass.

In addition, the political squabbling and control-freakishness of pear-dev over new packages is ridiculous. PEAR prides itself on only accepting high quality code except for what has been there for years. Because of two good intentions (don't duplicate code and confuse users; existing developers have 99% ownership of their packages), PEAR has a political nightmare any time someone comes along with an innovative package that could be a better solution to issues. For instance, when the Calendar package was proposed by Harry Fuecks, he did some benchmarking and determined that the largest performance hit was from requiring files, so he designed an internal inclusion system that requires minimal files, upping performance to match any functional code you can find. Very impressive. However, it doesn't fit the PEAR Coding Standards which say you have to do it the "require_once 'File.php';" way, and there was some squabbling over this point.

Recently, several good programs have been excluded, including the popular Savant template engine. The reasoning is sound (too many duplicate template engines as it is), but it doesn't change the fact that PEAR is slowly aiming a large weapon at its collective foot and squeezing the trigger.

To solve this issue, I designed channels for PEAR 1.4.0. Channels are a method of distributed development that are supposed to make it easy to install these packages without forcing the user to make any annoying configuration changes. In other words, it would legitimize code outside of PEAR.

Here is the main sticking point: I happen to believe that there are a very few sites that distribute truly high quality code. You can probably name all of them in one sitting. We know the big names in PHP - there's Smarty, the various *Nuke (popular even if you dislike coding for them as much as I do), Xaraya, Horde, PAT, Savant, WACT, Phing, and so on (not a complete list by any means).

None of them inter-operate in terms of installation. Remember the days when installing programs in MS-DOS was hit-or-miss Then, the advent of the centralized installer came and our lives all changed (mostly) for the better.

Today, PEAR has a choice. It can either use its .php.net officialdom to recognize good PHP code that is possibly not quite as anal retentive about tabs vs. spaces, or it can continue to flounder in political refuse. You can probably tell where I stand on this issue by now. I've devoted tons of my time, including all of my available coding time, to improving the PEAR installer so that it can be thought of as the PHP installer. More importantly, so that it will WORK as the PHP installer.

Obviously, there is some more work to be done technically to address scalability/ease issues, mainly completing the REST-based server so that static files can be used, and making the installer for PEAR a one-shot file.

My point is: if the developers of PEAR can't recognize the good that will come from simply listing a few important channels at pear.php.net, I'm at a loss for words. It's beyond incredibly short-sighted.

Some concerns people have that are bogus:

1. the list of channels will grow exponentially and overload PEAR
2. the quality of code on those channels will reflect poorly on PEAR

I've already described why #1 is bogus - there's only a few reputable sites. You can tell at a glance whether a site is a major distribution point or just Joe Podunk distributing an installer for his Grandma's apple pie recipes.

The quality of code on those channels can only reflect positively on PEAR. Most of it is BETTER than what we have in PEAR. If it can be installed just as easily as PEAR, then we have a win-win situation. PEAR should be about promoting PHP, but that is my opinion again.

Now, to end on a positive note, PEAR has improved by leaps and bounds thanks to the efforts of everyone other than me (I take some credit, but let's be fair!). Helgi Bormar, Lukas Smith, Dan Convissor, and others have taken the reins and really harped on folks to improve their code and make it usable in critical situations. Tobias Schlitt's work on PEPr along with the others named above have nearly eliminated much of the arguing over new packages. Martin Jansen's calm work on the pear.php.net site gradually fixing things, and adding the phpDocumentor API docs has been pretty successful (scalability problems are the only issue so far). Pierre and Martin's work on speeding up pear.php.net has been very successful.

The QA Group has really helped to address the ownership issue in PEAR. Orphaned packages have acquired new maintainers, and bugs have begun to get killed off one by one.

Even the documentation has gradually improved to the point where I haven't heard nearly as many complaints (more work to do here).

Gradually, PEAR is attracting dynamic PHP developers who used to work alone or look elsewhere.

This is just it: PHP can't be as useful as it should be unless PEAR is at its best.