Lot 49: Greg Beaver's blog

Update #2: the latest go-pear.phar works in PHP 5.1b3 now. We're up to 814k. It still doesn't work on linux, no idea why.

Update: a new go-pear.phar is available containing fixes for some of the problems noted in the comments below. If you've had trouble, give it a try, it may work now.

The beginning of a new era in PEAR has arrived. I have just uploaded the first ever self-contained single file installation of PEAR, based on PHP_Archive. Unlike the pre-existing http://go-pear.org, go-pear.phar (a 768k draft is available at http://pear.chiaraquartet.net/go-pear.phar) provides a simple method for those with limited internet access or finicky firewall/proxy issues to download and install PEAR with tremendous ease. In addition, earlier problems with versioning have been eliminated as all packages are bundled directly inside go-pear.phar itself.

go-pear.phar REQUIRES PHP 4.3.0 or newer, so don't even try it with PHP 4.2.x or older. You've been warned.

Other improvements include:

1. Understanding of the differences between a system-wide installation and a local PEAR installation is built into the install process.
2. The location of the PEAR configuration file (pear.ini/pear.conf) is now explicit and configurable.
3. The default name of the configuration file matches that expected by the PEAR_Config class
4. PEAR 1.4.0 is used for all installation tasks, and the code is contained directly within go-pear.phar - no external code is needed or used, even if available, providing simpler debugging.
5. The go-pear script has been vastly simplified by entirely eliminating download/bootstrap code that was necessary before.
6. The spaghetti-code nature of a single-file script has been eliminated - all code can be debugged and designed in the traditional multi-file method prior to pharring.

There are a few issues to know about. First and foremost, I am on the road, meaning I do not have access to a unix-based box on which to test the code. There are slight but important differences that may have minor typos or major logic errors in them that my eyeball debug missed. Second, I have not yet converted the web install of go-pear over to the .phar format. This will happen later once I'm satisfied the CLI version is stable.

In my tests on windows, it works fabulously, so I hope other brave souls will have the same experience. To use, download, and simply run:

$ php go-pear.phar

Then, follow the prompts and answer questions. That's it!

Installation of PEAR has generally been quite difficult. Grabbing go-pear remotely requires downloading a whole bunch of packages, and it has often been necessary to hard-code in specific package versions directly in go-pear to work around bugs in core packages. In addition, maintaining the PEAR bundles distributed with PHP has been a royal pain in the rear end.

This is all about to change. In the past few days, I realized that with the advent of PHP_Archive-based .phar files, it is possible to distribute a self-contained .phar that contains all of the packages needed to install PEAR from scratch. I've blogged about this in the past. What I hadn't realized is that I could simply bundle in an uncompressed PEAR in the .phar itself and use it instead of all the complex download/install stuff in go-pear. This means, for one thing, that it is finally possible to separate go-pear classes into separate files. It also means that instead of maintaining uncompressed copies of PEAR in cvs/php-src for PHP 4.4, 5.0 and 5.1, we can provide a single .phar that will automatically install PEAR the way that the install-pear.php file in cvs/pear-core does now.

my initial foray into the bug list at sourceforge for phpDocumentor has led to an unshakable conclusion: the docblock "parsing" currently used in phpDocumentor, well, sucks.

So, to solve problems such as this code breaking:

/**
* Watch the @include_once become a tag...
*
* Example:
* <code>
* @include_once 'oops_stupid_docblock_Parser.php';
* </code>
*/

I have started a hand-written lexer with an eye towards a phpJay-generated docblock parser. I had originally attempted a phpLex auto-generated lexer for docblocks, but it quickly became a 2000-line plus undebuggable mess of spaghetti. In addition, it simply couldn't do some things it needs to do, and so the docblock parser was far more complex than is healthy. With the current code in cvs (700-something lines), the lexer supports everything the current one does plus proper handling of things like {@internal}} and special tags <code></code>. More interesting, it supports nested simple lists (something humans intuitively can read) and has unit tests. There's work to be done (edge cases, and I just realized I forgot to implement <ul><ol><li>) but mostly we're fast on the way to an improved docblock parsing system, the first in a series of minor refactors that will add up to a major improvement in code, performance, and memory usage of phpDocumentor.