Getting started with Pyrus

Greetings all, Christian had a good suggestion that I send this to PEAR-dev, so here it is – I've put together some notes on getting started with Pyrus, and offer them up for your benefit and/or criticism. Feel free to send any comments... I hope everyone can take some time to get some experience with Pyrus & PEAR2, and lend a hand in testing and finding any bugs. First of all, the following is a copy/paste of my Google doc page, which you can view online with syntax highlighting and some html formatting. http://docs.google.com/Doc?id=dgtbrg66_50d5c68d I will keep the Google Doc version of this updated, as these are my personal notes... but if someone has a better suggestion for hosting a copy (even peardoc).. I will gladly move them. Getting started with Pyrus - the new installer for PEAR compatible packages There are quite a few reasons to start playing with the new PEAR package manager - named Pyrus. The first of which is that it is filled with PHP 5 goodness, utilizing many features of the SPL. And secondly, PEAR2 is just around the corner and these are exciting times for PHP development. Prerequisites: PHP >= 5.2? (I believe you need libxml > 2.6.16, but could use some help verifying this) SQLite Extension, should be included by default (sudo apt-get install php5-sqlite) The first thing we need to do, is create a temporary directory to checkout the PEAR2 files from the repository: Note: In case you haven't heard, PEAR2 source files are in subversion at http://svn.pear.php.net/PEAR2 mkdir ~/PEAR2_SVN cd ~/PEAR2_SVN/ svn co http://svn.pear.php.net/PEAR2 Great, now you have a copy of the latest files for Pyrus and PEAR2. (r 314 when this was written). The following packages are the backbone of the new package manager: PEAR2_Autoload PEAR2_Exception PEAR2_Pyrus PEAR2_HTTP_Request PEAR2_Developer (if you'd like to build some PEAR2/Pyrus installable packages) The PEAR2 channel is not available yet, but we can install the individual packages in Pyrus by using their respective package.xml files within the svn checkout. Before we install the new packages, let's create a directory to place our Pyrus installation. Previously, users would create a system PEAR install in /usr/share/pear or similar, or a local PEAR install in ~/pear/. And at this point, you would have to make a decision you might have to live with for the rest of the installed packages' lives. But, don't worry! With PEAR2 we can move this Pyrus managed installation later if needed. mkdir ~/pyrus cd ~/pyrus/ Note: it is important to change the directory to where you wish to install the packages as the current directory will be used as the default install location for pyrus commands. Now let's install some packages php ~/PEAR2_SVN/PEAR2/Pyrus/trunk/pyrus.phar install ~/PEAR2_SVN/PEAR2/Autoload/trunk/package.xml php ~/PEAR2_SVN/PEAR2/Pyrus/trunk/pyrus.phar install ~/PEAR2_SVN/PEAR2/Exception/trunk/package.xml php ~/PEAR2_SVN/PEAR2/Pyrus/trunk/pyrus.phar install ~/PEAR2_SVN/PEAR2/HTTP_Request/trunk/package.xml php ~/PEAR2_SVN/PEAR2/Pyrus/trunk/pyrus.phar install ~/PEAR2_SVN/PEAR2/Pyrus/trunk/package.xml php ~/PEAR2_SVN/PEAR2/Pyrus/trunk/pyrus.phar install ~/PEAR2_SVN/PEAR2/Pyrus_Developer/package.xml Now you have Pyrus and all the necessary dependencies installed! To get started, you can create your PHP files which reference the PEAR2 autoloader by using: <?php require 'pyrus/src/PEAR2/Autoload.php'; ... How to create a PEAR2 package The easiest way to create a Pyrus installable package is to set up a standard filesystem layout, and auto-generate the package.xml manifest for installation. The source layout is as follows: PackageName/src/ [role="php"] PackageName/examples/ [role="doc"] PackageName/doc/ [role="doc"] PackageName/data/ [role="data"] PackageName/tests/ [role="test"] PackageName/www/ [role="www"] In the root of your package directory create the following files: CREDITS (this file contains the project lead info) example ; maintainers of PackageName Brett Bieber [saltybeagle] <brett.bieber@gmail.com> (lead) README (this file contains the summary and description for the package) example This package is for use with blah With this package you can do blah, blah, blah blah. My extended description goes here. RELEASE-0.1.0 (This file contains the release notes) example This is the first alpha release. Take a look at the Pyrus_Developer package for more info. You can create your PEAR2 installable package by using the Pyrus_Developer package and using a file like this: makepackage.php <?php error_reporting(E_ALL); ini_set('display_errors',true); require 'pyrus/src/PEAR2/Autoload.php'; $a = new PEAR2_Pyrus_Developer_PackageFile_PEAR2SVN(dirname(__FILE__), 'PEAR2_MyNewPackage'); Then run the file to generate the package.xml and install your package: php makepackage.php cd ~/pyrus php ~/PEAR2_SVN/PEAR2/Pyrus/trunk/pyrus.phar install PackageName/package.xml Hopefully this gives you all a quick understanding of how to get started, and some idea of where things are headed. Some api docs for Pyrus - http://ucommbieber.unl.edu/workspace/Pyrus/docs/ -- Brett Bieber http://saltybeagle.com/