There has been quite a bit of confusion recently due to the best resource for setting up a channel being located on Toby's blog, and now being quite a few versions out of date. First of all, let it be known that the PEAR_Server package located at pear.chiaraquartet.net has been superseded by the Chiara_PEAR_Server package at pear.chiaraquartet.net.[1]

This means that in order to set up your own personal channel, you need to take these steps:

Before you begin (preconditions):

You need:

• PHP 5.0.3 or newer (PHP 5.1.0 or newer is recommended)
• PEAR 1.4.3 or newer (all earlier versions have a security hole).
• a MySQL database and the mysql or mysqli extension enabled in php.ini
• a web site containing no underscores "_" in its name.
• shell access to your web site - this is essential

Even if your web site has a global PEAR, you will want to install a local copy.

To acquire PEAR, the easiest methods are

1. for PHP 5.1.0 and newer, download go-pear.phar and run php go-pear.phar
2. for other versions, download go-pear.php and run php go-pear.php

You should see a screen like so:

[ ~]$ php5 go-pear.phar

Below is a suggested file layout for your new PEAR installation. To
change individual locations, type the number in front of the
directory. Type 'all' to change all of them or simply press Enter to
accept these locations.

1. Installation base ($prefix) : /home/youruser/pear
2. Binaries directory : /home/youruser/pear/bin
3. PHP code directory ($php_dir) : /home/youruser/pear/share/pear
4. Documentation directory : /home/youruser/pear/share/pear/docs
5. Data directory : /home/youruser/pear/share/pear/data
6. Tests directory : /home/youruser/pear/share/pear/tests
7. Name of configuration file : /home/youruser/.pearrc

1-7, 'all' or Enter to continue:

After installation, run this command to make sure things are working:

~/pear/bin/pear -V

You should see something like "PEAR version 1.X.X" where X.X is the latest version (1.4.9 at the time of this entry).. You may want to create a soft link (ln -s) to this so that you can type ~/pear install blah instead of ~/pear/bin/pear install blah.

if you are running an earlier version of pear, then you should upgrade via normal techniques:

pear clear-cache
pear upgrade PEAR

NOTE: if you are running a REALLY old version of PEAR (1.3.3 or older), you need to run these commands:

pear upgrade PEAR-1.3.6
pear upgrade PEAR

Acquiring Chiara_PEAR_Server

This is easy. Using your preferred pear binary (either pear or ~/pear) run these commands:

pear channel-discover pear.chiaraquartet.net
pear upgrade chiara/Chiara_PEAR_Server

At this point, you should see something very similar to:

downloading Chiara_PEAR_Server-0.18.4.tgz ...
Starting to download Chiara_PEAR_Server-0.18.4.tgz (32,479 bytes)
.........done: 32,479 bytes
upgrade ok: channel://pear.chiaraquartet.net/Chiara_PEAR_Server-0.18.4
Chiara_PEAR_Server: Optional feature pearweb available (Public frontend for users to browse channel packages)
To install use "pear install chiara/Chiara_PEAR_Server#featurename"
chiara/Chiara_PEAR_Server has post-install scripts:
/usr/local/lib/php/Chiara/PEAR/Server/mysqlinstall.php
Use "pear run-scripts chiara/Chiara_PEAR_Server" to run
DO NOT RUN SCRIPTS FROM UNTRUSTED SOURCES

ALWAYS READ THE TEXT!! It may contain important error messages. If your PEAR installation is using a php4 binary, for instance, the installation will fail and tell you why (PHP version < 5.0.0). You can fix this by setting your php_bin to a php5 binary (like pear config-set php_bin /path/to/php5), but this should not occur if you've set up your PEAR correctly.

Next, you need to run the post-installation script. To do this, type:

pear run-scripts chiara/Chiara_PEAR_Server

Answer "yes" to all yes/no questions, and then the script will ask you questions about the database. If your mysql user does not have create permission, you must create the database prior to running the script. The post-install script will create and populate the necessary database tables, and will create the administrative backend. Once you have successfully run the post-installation script, we can continue with the next steps.

Configuring Chiara_PEAR_Server

First, try these steps to ensure that the post-installation script worked:

1. using an external database browser (phpMyAdmin or the like) verify that tables like "packages" "channels" "maintainers" "handles" and so on were properly created in the database
2. verify that your channel's document root contains "channel.xml" by browsing to http://yourchannel.com/channel.xml using any web browser such as FireFox.
3. verify that you can access the administrative frontend by browsing to http://yourchannel.com/frontend.php where frontend.php is the name you chose for the administrative frontend in the post-installation script. Log in

Creating a pretty frontend for your end-users

To set up a frontend, simply run:

pear upgrade chiara/Chiara_PEAR_Server#pearweb

This will install the frontend package Davey Shafik has written. This requires some configuration, so please read more about it at http://pear.crtx.org.

Creating a package/adding users

Before you can merrily start using your channel, you need to create a package and add users to it. This is a security feature. Although users in a release's package.xml will be automatically added, only a registered lead developer assigned to a package can release. This includes administrators. This feature is designed to prevent unauthorized releases of packages.

So, to get started, let's imagine you are creating a package named "Foo_Bar" and that your username is "joeshmoe". You will need to take these steps:

1. log into your administrative frontend as "joeshmoe" (http://yourchannel.com/frontend.php or whatever you've named it)
2. Click "Create a Package"
3. Fill in the necessary details
4. Save it
5. Under "Manage Packages" you will see "Foo_Bar (Maintainers)"
6. click "(Maintainers)"
7. Choose "joeshmoe" in the "New Maintainer" dropdown
8. Choose "lead" in the "Role" dropdown
9. Choose "yes" in the "Active Maintainer " dropdown
10. Click "Add Maintainer"

That's it! Now, let's upload a release.

Uploading a release

Once you have performed these steps, you should be good to go. To upload a release (make sure you use package.xml version 2.0 so you can specify your channel) click on "Upload a release" and upload it. If you have a problem, an error message will be displayed. Most common is "unknown channel yourchannel.com" This occurs when you fail to provide the correct path to your pear.ini or .pearrc in the post-installation script.

To determine the location of the pear script you wish to use, run:

pear config-show

and look for the bottom lines:

User Configuration File Filename /home/foobar/.pearrc
System Configuration File Filename /usr/local/etc/pear.conf

The file you want to use is the User Configuration File, "/home/foobar/.pearrc" in this case. The other common problem is forgetting to add yourself in package.xml. For our example user joeshmoe, you need to add this to package.xml:

Remotely testing your channel

To remotely test the channel, simply run these commands from a remote machine that is running PEAR 1.4.0 or newer (I assume "yourchannel.com" is aliased to "yourchannel"):

pear channel-discover yourchannel.com
pear upgrade yourchannel/Foo_Bar

That's it!

[1] PEAR_Server has been renamed Chiara_PEAR_Server for licensing reasons. Although it is the intention of the (super-busy) developers of the Chiara_PEAR_Server package to eventually propose this package to pear.php.net as an official package, until that time, it is best to prefix the name so that it is readily distinguishable as a non-pear.php.net-based package.

The latest stable release of the PEAR installer, version 1.4.9, has been released at pear.php.net. This release addresses a critical bug introduced in the release of PEAR 1.4.8 earlier this month. This version has been rigorously tested to ensure no future breakage (the last release had inordinate time pressure due to external circumstances). You can read about it and retrieve it at http://pear.php.net/PEAR.

Also, development has begun on PEAR version 1.5.0. This will not be a earth-shattering feature addition from the 1.4.x series like version 1.4.0 was to the 1.3.x series of releases. In fact, most new features have already been implemented. First of all, support for PHP 4.2.x will be officially dropped in version 1.5.0, and we will use version 4.3.0 as the minimum version. Several cosmetic features have been introduced, such as improved post-installation scripts for the CLI interface, and TAP-compliant output of the run-tests command. The most major area for improvement will be the way PECL extensions are installed. We will announce specifics when the implementation is worked out, so stay tuned to the pear-core mailing list for details.

UPDATE:Some internal classes define their own cast handlers, such as simplexml. So, if you cast internal objects to bool, the result depends on the particular object. simplexml objects always cast their internal value to string prior to casting to other values, so an empty tag will cast to false. The actual source is viewable at http://lxr.php.net/source/php-src/ext/simplexml/simplexml.c#1539

Recently, some code in the PEAR installer was discovered to be invalid in PHP 4. After a bit of investigation, I realized that the significant difference in the way objects are represented internally in PHP 5 was the culprit. In essence, the difference shows itself in this code:

In PHP 5, this displays as bool(true), but in PHP 4, it displays bool(false). The reason is that in PHP 4, objects are simply glorified associative arrays, and so PHP treats the above code exactly the same as if it were:

As we know, an empty array evaluates to false in both PHP 4 and PHP 5. Note that modifying the code above even slightly like so:

removes this difference. Why PHP 4 then treats the code as if it were:

This results in true, as the array is no longer empty.

In short, if you're writing code that you expect to work in both PHP 4 and PHP 5 that tests for the type of a variable, always use the is_object() function, and never test with a boolean conversion as in:

[geshi lang=php]

This past September, my soon-to-be wife and I picked up a cat from Lincoln Nebraska's Cat House, a no-kill shelter. From the start, we knew he was a brilliant addition to our lives because of his extraordinary personality, but only later did we discover the true depth of his oddness. His name is "Dirty" because he had a little poo problem until we switched his food to another brand.

Every April Fool's day, PHP displays a different logo on its phpinfo() page. In the past, this has included a rabbit, Zeev's dog, and others. Perhaps it is Dirty's time to be enshrined in PHP forever

Click here to see Dirty in action. Here are some previews:

Just a quick note to all of you PEAR channel administrators:

Please take a moment to either join the pear-qa@lists.php.net mailing list, or follow php.pear.qa at news.php.net. Why

Every time a new release of the core PEAR package is slated, I (or whoever is in charge of the release) will post a message to the pear-qa list asking for testing of the new version 1 full week ahead of the scheduled release date. This is the one opportunity to test for critical errors that unit tests or myself have missed.

PEAR version 1.4.7 suffered from one such error - channel names containing "-" were invalidated by changes to the channel validation code, but since none of the standard channels (and none of my private ones) contain a hyphen, this error went undetected until the release. Users who had added the midcom channel, or symfony channel suddenly found that simple actions like "pear list-upgrades" caused fatal errors. This is a bad thing.

It would be very helpful to have channel administrators take a second to try out stable versions of PEAR as they approach release.

Because of the extreme nature of this bug, PEAR 1.4.8 will be released on Sunday, March 6. If you have a second, please grab the testing tarball via:

pear upgrade http://pear.php.net/~greg/PEAR-1.4.8.tgz

and make sure that nothing else is broken - this will be very helpful as the release date nears.