Accessing PEAR server information with PHP

The number of PEAR servers has increased dramatically in recent times. Maybe due to the availability of Pirum - a simple PEAR server. Whatever the cause: there are plenty of package lists and package datasets available on the net these days. Accessing this data is not always easy though.

PEAR servers provide a well defined REST API that is usually queried using the PEAR toolset available via the basic PEAR package. That package however does not provide anything that I would consider to be a decent developers API.

So let me provide you with an alternative that is available via the Horde framework libraries: The Horde_Pear library.

The package comes with the Horde_Pear_Remote class wich provides you with high-level access to the REST interface of a PEAR server.

Creating an instance of this class without providing any arguments to the constructor will allow you to access the PEAR server at pear.horde.org.

$pear = new Horde_Pear_Remote();
print(join("\n", $pear->listPackages()));

Horde_ActiveSync
Horde_Alarm
Horde_Argv
Horde_Auth
Horde_Autoloader
...

Alternative servers can be specified in the first argument to the constructor:

$pear = new Horde_Pear_Remote('pear.phpunit.de');
print(join("\n", $pear->listPackages()));

DbUnit
File_Iterator
Object_Freezer
PHPUnit
...

The full set of the functionality provided by Horde_Pear_Remote is detailed on our website.

The library section of the Horde website supports component documentation now.

Our new libraries section has been started a while ago to further push the PHP components we offer. Now this section supports publishing the component documentation as well. You can take a look at the documentation of the Cli_Modular package for example. In fact: it is pretty much the only package that fully uses the new system already. So there is still work ahead.

If you use any of the components: We are grateful if you start writing a bit of documenation or describe some examples on how to successfully use the package. It will help us and others tremendously. Thanks!

Let me try to explain how the system is currently intended to work - feedback and critical comments of course welcome:

1. When creating new documentation for one of the Horde components you start a new section on the developer documentation of our wiki. See the Horde_Cli_Modular link below Library components for example. Please note: It is not mandatory to write the documentation in the wiki. You can have static documentation files within a component as well. This is just meant as an option for those situations where it makes sense to work on documentation files together with people that do not have direct git commit access. Hopefully there will be many component consumers interested in updating and fixing the documentation.
2. How you structure that new section is up to you. For a simple package you might wish to keep all documentation in a single file but for the more complex one it might make sense to have several files. In that case the new section page should probably just be a link list to the various wiki pages that document the component. In case of Horde_Cli_Modular I used a single page.
3. Once the documentation has been written in the wiki format it is time to download it into the doc directory of the component. The horde-components helper is what you should use for that operation. The tool expects to find a DOCS_ORIGIN file within the doc or docs (for the applications) directory of the component. This file must conform to the reStructuredText format and map remote URLs to local file paths relative to the component root. The DOCS_ORIGIN from Cli_Modular links the wiki page exported as reStructuredText to the path doc/Horde/Cli/Modular/README. The links can of course point anywhere so you are in principle free to use any remote source. But you should ensure the page provides readable reStructuredText.
4. Now you can run horde-components fetchdocs and it should fetch the URLs into the respective local files. You can then run horde-components update to refresh the file list in the package.xml file if the documentation files were not included before.
5. Once a component was released we can now run something like this: horde-components Horde_Cli_Modular webdocs -D ~/git/horde-web/ --html-generator=git/horde-support/maintainer-tools/docutils/html.py --allow-remote in order to update the documentation on the website. Right now this does not happen automatically during a release but I plan to add this soon.

There are of course still a few problems with this approach:

• The reStructuredText exporter of our wiki engine "Wicked" is not yet complete. You may experience problems with the export if you use constructs it does not know yet. Please ping me if you experience problems with the export.
• The wiki syntax and the syntax required by reStructuredText is not 100% aligned. You can write a wiki page that looks just fine but leads to errors or formatting problems in the reStructuredText export. After creating / updating a new wiki documentation page it make sense to run the horde-components fetchdocs/horde-components webdocs sequence to check for problems.
• We still have some components with documentation files not in reStructuredText format. These will result in non-existing links on our website for now but I plan to fix the few faulty packages soon.

Jenkins on ci.horde.org got a major update

The Horde continuous integration setup saw a major upgrade and a number of fixes during the last week.

The take home message for everyone that does not wish to read the full log: ci.horde.org will now run horde/framework/bin/test_framework after a new commit has been pushed. This reduces the load on the system significantly and you will get results faster. If you develop Horde code you should run horde/framework/bin/test_framework as well in order to check if your recent commits could cause failures on our continuous integration server.

The full recap of the recent changes:

• Update to the newest version of the Horde components tool. This allows to use the improved templating system.
• New configuration and build templates that allow to reduce the job build time by avoiding to rebuild the set of package dependencies if this is not necessary. This has an important implication: A code change in one package (e.g. Horde_Imap_Client) will be tested against unchanged dependencies (e.g. Horde_Mime). Even if the commit also touched one or several of the dependencies (e.g. Horde_Mime). The packages should be backward compatible - so this should result in no error. The dependencies of one package will only get updated in case the dependency list in the package.xml of that package changes.
• Running horde/framework/bin/test_framework has been integrated into the horde-git job. With the new "rebuild dependencies only when necessary" policy (see above) the component jobs do not fully test the integrity of the latest commit anymore. When the dependencies do not get updated the focus of shifts a bit more towards checking for backward compatibility. In order to not loose the integrity check for the "bleeding edge" our test_framework script is now executed right after updating the code from git.
• Running test_framework also allows to run component jobs only if the code of the component has actually been touched. This significantly reduces the load on ci.horde.org as it removes the need for rebuilding all components for each and every commit.
• An update to the newer CodeSniffer which included an update to the checklist for the Horde style. The new ruleset is available from our horde-support repository.
• A customizable ruleset for the PHP mess detector has been added as well. We still need to tweak the exact configuration of PMD to match it with what we consider reasonable defaults for Horde code.
• DocBlox has been added to allow generating experimental API documentation. DocBlox is significantly faster and less memory hungry than PHPDocumentor. It has already been adopted by large frameworks such as Zend. So I figured it is worth taking a look at it. Feedback welcome!
• The Jenkins configuration has been updated with the latest fixes and improvements from the Jenkins-PHP project.
• The setup procedure has been fixed so that it should be possible to generate a local setup - comparable to ci.horde.org - again.