The Git-based project hosting service GitHub is certainly the belle of today's technology ball, having attracted more than 1 million registered users and amassed more than 2 million hosted projects in less than three years. On a personal note, during this time it has become an incredibly important part of my own professional activities, with GitHub playing a role in my client work, website development, management of source code associated with several of my books, and for keeping tabs on other cool projects.

The GitHub team does a pretty impressive job of responding to user feedback, adding and improving service features, all of which are blogged about in detail on the official blog, and itemized within the changelog. If keeping track of your various projects via your laptop isn't enough, a great iPhone app is also available. In addition, GitHub follows an approach embraced by many of today's successful software companies, allowing users to extend the service in new and interesting ways via a powerful and well-documented API.

GitHub High Scores and GitHub Badges are two examples of third-party services created using the GitHub API, which is capable of carrying out any task you might wish to perform via GitHub.com. With it you can create, edit and search repositories, learn more about fellow GitHub users, and manage repository issues.

Using the PHP GitHub API Library

A number of libraries are available for interacting with the API, among them php-github-api (PHP), py-github (Python), and github-api (JavaScript). Perhaps not surprisingly, all three of the aforementioned libraries are available via public GitHub repositories, meaning that getting started using one is as easy as cloning the project:

$ git clone https://github.com/ornicar/php-github-api

Once cloned, consider moving the lib/Github directory into your project's root directory, or move the Github directory into your existing libdirectory if one is already available. Next, include the library autoloader:

<?php

  require_once 'lib/Github/Autoloader.php'; 
  Github_Autoloader::register();

?>

Next, you should instantiate the Github_Client() class:

  $github = new Github_Client();

With the Github_Client class instantiated, it's time to begin interacting with GitHub!

Searching GitHub Repositories with PHP

Suppose you wanted to create a simple service that searched for all public GitHub repositories with a description containing a particular keyword, such as Zend. You can easily do so like this:

$repos = $github->getRepoApi()->search('Zend');

The $repos variable contains an array of multidimensional arrays, each of which contains useful information about the returned repositories such as the description, number of followers, and whether a download is available. Once retrieved, you can use PHP's relatively new anonymous function feature to sort the multidimensional arrays by a specific key value, such as the description, and output the results to the screen:

// Sort by description
usort($repos, function($a, $b) {
  return strcmp($a['description'], $b['description']); 
});

// Iterate over the alphabetized descriptions
foreach($repos AS $repo) 
{
  printf("<p>%s</p>", $repo['description']); 
}

Executing this code will output an alphabetical list of up to 100 repositories, the first five of which are found here:

A SQL database abstraction layer strongly inspired by the PHP Zend 
Framework Zend_Db API, with support of multiple Node.js database engines

A Simple blogging application based on CouchDB, Sopha and Zend Framework

A Social authentication library for Zend Framework. Currently supported:
facebook oauth 2.0, twitter oauth, foursquare oauth 2.0, vkontakte, mail.ru
oauth 2.0, google open id, flickr, gowalla

A Zend Framework 1.x and Doctrine 1.2 Integration

A Zend Framework Implementation

If more than 100 returned repositories exist, you can page between subsequent sets of 100 using the page parameter:

$repos = $github->getRepoApi()->search('Zend', 2);

Learning More About GitHub Users

Each repository is accompanied by an owner attribute which contains the username associated with the repository owner. For instance, the owner associated with the project described as A Zend Framework 1.X and Doctrine 1.2 Integration is beberlei, who happens to be Benjamin Eberlei, and active contributor to a number of high-profile open source projects, among them Doctrine. We can learn more about beberlei's GitHub activity via the API:

$user = $github->getUserApi()->show('beberlei');

The $user variable is an array containing all sorts of interesting tidbits about a particular user, including the country-of-residence, public repository count, and contact information (which I've changed to thwart spammers). Here's a dump of the array contents:

array(15) { 
  ["gravatar_id"]=> string(32) "75f5fb3ddda052e46f1daed314ae69ab" 
  ["company"]=> string(18) "direkt effekt GmbH" 
  ["name"]=> string(16) "Benjamin Eberlei" 
  ["created_at"]=> string(25) "2008/09/30 08:47:34 -0700" 
  ["location"]=> string(7) "Germany" 
  ["public_repo_count"]=> int(43) 
  ["public_gist_count"]=> int(24) 
  ["blog"]=> string(26) "http://www.whitewashing.de" 
  ["following_count"]=> int(5) ["id"]=> int(26936) 
  ["type"]=> string(4) "User" 
  ["permission"]=> NULL ["followers_count"]=> int(231) 
  ["login"]=> string(8) "beberlei" 
  ["email"]=> string(19) "kontakt@example.com" 

Learning More About a Specific GitHub User's Repositories

As you can see from the public_repo_count value, user eberlei is a very active GitHub user. You can retrieve a list of a user's repositories like this:

$repos = $github->getRepoApi()->getUserRepos('eberlei');

Like the first example, the $repos variable is an array containing a number of multidimensional arrays. Using the

Yet Another TSP Solution

Observatoire Photographique du Paysage

A simple PHP GitHub API client, Object Oriented, tested and documented. For PHP 5.1 to 5.3.

Provides php-github-api and some front widgets

Allows to add comments to your records.

Easily display configurable google maps

Performing Restricted Tasks on GitHub

So far this overview of the GitHub API has focused on publicly accessible data. However, the API also supports quite a few capabilities which are available only to an authenticated user. To authenticate your account, use the Github_Client's authenticate() method, providing your GitHub username and either your password or API token (the latter of which you can retrieve from your GitHub account management console). The authenticate() method can accept either the password or token as its second parameter:

$github->authenticate('wjgilmore', 'my-secret-password-or-token');

Once authenticated, you can carry out all sorts of useful tasks associated with account or repository management, such as updating a repository description:

$repo = $github->getRepoApi()
               ->setRepoInfo('wjgilmore', 'z2d2', array('description' => 'some new 
description'));

In addition to changing subscriptions, you can toggle repository visibility (public or private), create and delete repositories, and even add collaborators. See the php-github-api documentation for all of the details.

Conclusion

Have you done anything interesting with the GitHub API, or regularly use a third-party service? Tell us about it in the comments!