Here’s a quick tutorial I put together to help you get started on Pearhub.
The Differences Between Pear, the Pear Package System and the Pear Repository
First of all you may be wondering what is Pear? From the Pear Documentation - “PEAR is short for “PHP Extension and Application Repository” and is pronounced just like the fruit”. It is an umbrella-term that encompasses a package management system, an official package repository, a coding standard and a command-line tool. For more information please read the Wikipedia page: http://en.wikipedia.org/wiki/PEAR.
What is Pearhub?
Now that we have learnt about Pear, you might be wondering what is Pearhub? From Pearhub.org - "Pearhub is a pear channel and a pear package publishing platform. As a user, you can install packages. As a developer, you can publish packages". You can read Troels Knak-Nielsen's introductory blog post here: http://www.sitepoint.com/blogs/2010/01/08/introducing-pearhub/.
See my Sample Project
For the purposes of this tutorial I have created a sample repository on my Github account. You can have a look before we get started or even fork it to your own account. The project has been published on Pearhub here: http://pearhub.org/projects/pearhub_tutorial.
Getting Started
First of all you will need a couple of things - an OpenID account, an account on GitHub and a working copy of Git installed. Pearhub also supports Subversion, but we'll be using Git for this tutorial. You can get a free OpenID account at myopenid.com. Also this tutorial was written for Mac OS X, so you'll need to adapt it for other platforms. Finally, you should have a basic understanding of pear, php and git.
Developing a Project Locally
Start by creating a new directory. I have labelled mine 'pearhub-tutorial'. This is going to be the root of the Git repository and contain your new project. Open up your favorite text editor or IDE (I happen to use TextMate) and insert the following code:
| <?php | |
| /** | |
| * Pearhub Tutorial Script. | |
| * | |
| * @package PearhubTutorial | |
| * @version $Id$ | |
| */ | |
| /** | |
| * Pearhub Tutorial Class. | |
| * | |
| * @package PearhubTutorial | |
| */ | |
| class PearhubTutorial | |
| { | |
| /** | |
| * Simple Method that Returns 'Hello World'. | |
| * | |
| * @return string | |
| */ | |
| public static function getString() | |
| { | |
| return 'Hello World'; | |
| } | |
| } |
Now save the file (I named my file 'pearhubtutorial.php').
Note: You can skip this step and use the code from any pre-existing project you may have. Next we will need to create a new repository on GitHub to push this project to.
Creating a Repository on GitHub
Sign into GitHub and create a new repository. This is where we'll develop your project before publishing it on Pearhub.
Next fire up the OS X Terminal and switch to your working directory. We are going to initialize a local Git repository and push it up to GitHub. This can be achieved by issuing the following commands:
$ git init $ git add pearhubtutorial.php $ git commit -m 'initial commit' $ git remote add origin [email protected]:yourusername/yourrepository.git $ git push origin master
Note: Be sure to substitute 'yourusername' and 'yourrepository' with your respective details. The terminal output should look similar to this:
If you were successfully able to push your project up to GitHub, then the repository browser should show your source-code:
We are now ready to publish your project on Pearhub.
Publishing Your Project on Pearhub
Navigate to Pearhub.org and log in using your OpenID. Click the 'Register your project on pearhub' link and fill out the form. In the files section I have chosen to set the path to my repository root (/). You could also set this to something like '/lib' if you wanted to include sample code in your repository. See the following screenshot for more information:
Note: At the time of writing you must specify a value in the license field. Enter the value ‘None’ in the ’title’ field and your Github repository URL in the ’href’ field. Also make sure you enter an email address in the lead maintainer section as Pear requires this. Leave the release policy as ‘Automatic’ and hit ‘Create project’.
Pearhub will create your project and show you its summary page. Next click 'Show releases'. You will notice Pearhub has added your project to it's build queue. It will now begin polling your specified repository for tags. When it detects a new tag it will connect to your GitHub repository and package up your release. In the next step we will tag your first release.
Tagging the Initial Release
Now that your project has been published on Pearhub we are ready to tag a release. Pearhub requires you to tag your releases so it can keep track of them. In order for Pearhub to recognize a tagged release, you will need to follow a naming convention called Semantic Versioning. Switch back to your terminal window and execute the following commands to tag a release and push it up to GitHub:
$ git tag -a v0.0.1 -m 'Tagged Release 0.0.1' $ git push origin : v0.0.1
The version you pushed up to GitHub should now be visible under the 'Tags' drop down in the repository browser. In the next few minutes Pearhub will detect the new version and begin building a release. It is now a good time to head back over to your project's Pearhub release page and wait for the first version to start building. When the status of your release changes from 'building' to 'completed' we are ready to move to the next step.
Installing Your Package
To install your newly published package, we need to add the Pearhub channel to your local Pear installation. This step is quite simple:
$ sudo pear channel-discover pearhub.org
Next execute the following command to install the latest version of your Pear package (Be sure to replace 'yourpackagename' with the name of your package):
$ sudo pear install pearhub/yourpackagename
Pear will connect to Pearhub and install your newly published package. In my case I can find the file here on my filesystem: '/usr/lib/php/pearhubtutorial.php'. You can now use your package like you would with any other standard Pear release.
Using Your Package
If you published the tutorial package it's usage is quite simple. Simply include the script and call the 'getString()' method. This method returns 'Hello World'.
| <?php | |
| require_once 'pearhubtutorial.php'; | |
| echo PearhubTutorial::getString(); // returns 'Hello World' |
Conclusion
Hopefully this tutorial has given you a basic understanding of using Pearhub. You should be able to adapt these instructions to suit your own code/projects. If you still have any questions you can read the Pearhub FAQ or follow me on Twitter and send me a Direct Message.
