Skip to content
This repository has been archived by the owner on Feb 1, 2023. It is now read-only.

Commit

Permalink
completed v2.0 : complete rewrite of code, docs and tests. BC compati…
Browse files Browse the repository at this point in the history
…bility preserved.
  • Loading branch information
ornicar committed Apr 8, 2010
1 parent b9c6241 commit 60a8128
Show file tree
Hide file tree
Showing 15 changed files with 569 additions and 231 deletions.
10 changes: 10 additions & 0 deletions CHANGELOG
@@ -1,3 +1,13 @@
v2.0 - 2010-04-09

* refactored the whole API for better extensibility and performance; BC compatibility preserved
* each API part has a dedicated class
* request instance can be injected with phpGitHubApi->setRequest($request)
* API instances can be injected with phpGitHubApi->setApi($name, $api)
* request and API instances are lazy loaded for best performance
* added phpGitHubApiUser->update method
* 100% unit test coverage

v1.2 - 2010-04-08

* addition of the deAuthenticate method
Expand Down
97 changes: 72 additions & 25 deletions README.markdown
@@ -1,99 +1,142 @@
# PHP GitHub API

A simple, Object Oriented API wrapper for GitHub written with PHP5.

Uses [GitHub API v2](http://develop.github.com/).
Requires [curl](http://php.net/manual/en/book.curl.php).

Requires [php curl](http://php.net/manual/en/book.curl.php).

## Instanciate a new API

$api = new phpGitHubApi();
$github = new phpGitHubApi();

### Authenticate a user

This step is facultative, as most of GitHub services do not require authentication.

$api->authenticate('ornicar', 'my-token');
$github->authenticate('ornicar', 'my-token');

All next requests will use the user "ornicar", instead of anonymous access.
Next requests will use the user "ornicar", instead of anonymous access.

### Deauthenticate a user

Cancels authentication.

$api->deAuthenticate();
$github->deAuthenticate();

All next requests will anonymous access.
Next requests will use anonymous access.

## Users

[Searching users, getting user information and managing authenticated user account information.](http://develop.github.com/p/users.html)

### Search for users by username

$users = $api->searchUsers('ornicar');
$users = $github->getUserApi()->search('ornicar');

Returns an array of users as described in [http://develop.github.com/p/users.html#searching_for_users](http://develop.github.com/p/users.html#searching_for_users)

### Get information about a user

$user = $api->showUser('ornicar');
$user = $github->getUserApi()->show('ornicar');

Returns an array of information about the user as described in [http://develop.github.com/p/users.html#getting_user_information](http://develop.github.com/p/users.html#getting_user_information)

## Issues

[Listing issues, searching, editing and closing your projects issues.](http://develop.github.com/p/issues.html)

### List issues in a project

$issues = $api->listIssues('ornicar', 'php-github-api', 'open');
$issues = $github->getIssueApi()->getList('ornicar', 'php-github-api', 'open');

Returns an array of issues as described in [http://develop.github.com/p/issues.html#list_a_projects_issues](http://develop.github.com/p/issues.html#list_a_projects_issues)

### Search issues in a project

$issues = $api->searchIssues('ornicar', 'php-github-api', 'closed', 'bug');
$issues = $github->getIssueApi()->search('ornicar', 'php-github-api', 'closed', 'bug');

Returns an array of closed issues matching the "bug" term, as described in [http://develop.github.com/p/issues.html#search_issues](http://develop.github.com/p/issues.html#search_issues)

### Get information about an issue

$users = $api->showIssue('ornicar', 'php-github-api', 1);
$users = $github->getIssueApi()->show('ornicar', 'php-github-api', 1);

Returns an array of information about the issue as described in [http://develop.github.com/p/issues.html#view_an_issue](http://develop.github.com/p/issues.html#view_an_issue)

## Commits

[Getting information on specific commits, the diffs they introduce, the files they've changed.](http://develop.github.com/p/commits.html)

### List commits in a branch

$commits = $api->listBranchCommits('ornicar', 'php-github-api', 'master');
$commits = $github->getCommitApi()->getBranchCommits('ornicar', 'php-github-api', 'master');

Returns an array of commits as described in [http://develop.github.com/p/commits.html#listing_commits_on_a_branch](http://develop.github.com/p/commits.html#listing_commits_on_a_branch)

### List commits for a file

$commits = $api->listFileCommits('ornicar', 'php-github-api', 'master', 'README');
$commits = $github->getCommitApi()->getFileCommits('ornicar', 'php-github-api', 'master', 'README');

Returns an array of commits as described in [http://develop.github.com/p/commits.html#listing_commits_for_a_file](http://develop.github.com/p/commits.html#listing_commits_for_a_file)

## Objects

[Getting full versions of specific files and trees in your Git repositories.](http://develop.github.com/p/objects.html)

### List contents of a tree

$tree = $github->getObjectApi()->showTree('ornicar', 'php-github-api', '691c2ec7fd0b948042047b515886fec40fe76e2b');

Returns an array containing a tree of the repository

### Show the data of a blob

$blob = $github->getObjectApi()->showBlob('ornicar', 'php-github-api', '691c2ec7fd0b948042047b515886fec40fe76e2b', 'CHANGELOG');

Returns array of blob of specified path

### List all blobs of repository

$blobs = $github->getObjectApi()->listBlobs('ornicar', 'php-github-api', '691c2ec7fd0b948042047b515886fec40fe76e2b');

Returns an array containing all blobs

## Request any route

The method you need does not exist yet?
You can access any GitHub route by using the "get" and "post" methods.
For example,

$repo = $api->get('repos/show/ornicar/php-github-api');
$repo = $github->get('repos/show/ornicar/php-github-api');

Returns an array describing the php-github-api repository.

See all GitHub API routes: [http://develop.github.com/](http://develop.github.com/)

## Objects
## Configure the request

### List contents of a tree
$tree = $api->listObjectTree('ornicar', 'php-github-api', '691c2ec7fd0b948042047b515886fec40fe76e2b');
Returns an array containing a tree of the repository
Wanna change, let's say, the request User Agent?

### Show the data of a blob
$blob = $api->showObjectBlob('ornicar', 'php-github-api', '691c2ec7fd0b948042047b515886fec40fe76e2b', 'CHANGELOG');
Returns array of blob of specified path
$github->getRequest()->setOption('user_agent', 'My new User Agent');

### List all blobs of repository
$blobs = $api->listObjectBlobs('ornicar', 'php-github-api', '691c2ec7fd0b948042047b515886fec40fe76e2b');
Returns an array containing all blobs
See all request available options in request/phpGitHubApiRequest.php

## Inject a new request instance

If you want to use your own request implementation, inject it to the GitHubApi:

$github->setRequest($myRequest);

$myRequest must extend phpGitHubApiRequest.

## Inject a new API part instance

If you want to use your own implementation of the user API, inject it to the GitHubApi:

$github->setApi('user', $myUserApi);

$myUserApi should extend phpGitHubApiUser.

## Run test suite

Expand All @@ -103,4 +146,8 @@ All code is fully unit tested. To run tests on your server, from a CLI, run

## Credits

This library borrows ideas, code and tests from [phptwitterbot](http://code.google.com/p/phptwitterbot/).
This library borrows ideas, code and tests from [phptwitterbot](http://code.google.com/p/phptwitterbot/).

Thanks to [noloh](http://github.com/noloh) for his contribution on the Object API.

Thanks to GitHub for the high quality API and documentation.
17 changes: 17 additions & 0 deletions lib/apis/phpGitHubApiAbstract.php
@@ -0,0 +1,17 @@
<?php

/**
* Abstract class for phpGitHubApi classes
*
* @author Thibault Duplessis <thibault.duplessis at gmail dot com>
* @license MIT License
*/
abstract class phpGitHubApiAbstract
{
protected $api;

public function __construct(phpGitHubApi $api)
{
$this->api = $api;
}
}
46 changes: 46 additions & 0 deletions lib/apis/phpGitHubApiCommit.php
@@ -0,0 +1,46 @@
<?php

require_once(dirname(__FILE__).'/phpGitHubApiAbstract.php');

/**
* Getting information on specific commits, the diffs they introduce, the files they've changed.
*
* @author Thibault Duplessis <thibault.duplessis at gmail dot com>
* @license MIT License
*/
class phpGitHubApiCommit extends phpGitHubApiAbstract
{

/**
* List commits by username, repo and branch
* http://develop.github.com/p/commits.html#listing_commits_on_a_branch
*
* @param string $username the username
* @param string $repo the repo
* @param string $branch the branch
* @return array list of users found
*/
public function getBranchCommits($username, $repo, $branch)
{
$response = $this->api->get('commits/list/'.$username.'/'.$repo.'/'.$branch);

return $response['commits'];
}

/**
* List commits by username, repo, branch and path
* http://develop.github.com/p/commits.html#listing_commits_for_a_file
*
* @param string $username the username
* @param string $repo the repo
* @param string $branch the branch
* @param string $path the path
* @return array list of users found
*/
public function getFileCommits($username, $repo, $branch, $path)
{
$response = $this->api->get('commits/list/'.$username.'/'.$repo.'/'.$branch.'/'.$path);

return $response['commits'];
}
}
62 changes: 62 additions & 0 deletions lib/apis/phpGitHubApiIssue.php
@@ -0,0 +1,62 @@
<?php

require_once(dirname(__FILE__).'/phpGitHubApiAbstract.php');

/**
* Listing issues, searching, editing and closing your projects issues.
*
* @author Thibault Duplessis <thibault.duplessis at gmail dot com>
* @license MIT License
*/
class phpGitHubApiIssue extends phpGitHubApiAbstract
{

/**
* List issues by username, repo and state
* http://develop.github.com/p/issues.html#list_a_projects_issues
*
* @param string $username the username
* @param string $repo the repo
* @param string $state the issue state, can be open or closed
* @return array list of users found
*/
public function getList($username, $repo, $state = 'open')
{
$response = $this->api->get('issues/list/'.$username.'/'.$repo.'/'.$state);

return $response['issues'];
}

/**
* Search issues by username, repo, state and search term
* http://develop.github.com/p/issues.html#list_a_projects_issues
*
* @param string $username the username
* @param string $repo the repo
* @param string $state the issue state, can be open or closed
* @param string $searchTerm the search term to filter issues by
* @return array list of users found
*/
public function search($username, $repo, $state, $searchTerm)
{
$response = $this->api->get('issues/search/'.$username.'/'.$repo.'/'.$state.'/'.$searchTerm);

return $response['issues'];
}

/**
* Get extended information about an issue by its username, repo and number
* http://develop.github.com/p/issues.html#view_an_issue
*
* @param string $username the username
* @param string $repo the repo
* @param string $number the issue number
* @return array informations about the issue
*/
public function show($username, $repo, $number)
{
$response = $this->api->get('issues/show/'.$username.'/'.$repo.'/'.$number);

return $response['issue'];
}
}
63 changes: 63 additions & 0 deletions lib/apis/phpGitHubApiObject.php
@@ -0,0 +1,63 @@
<?php

require_once(dirname(__FILE__).'/phpGitHubApiAbstract.php');

/**
* Getting full versions of specific files and trees in your Git repositories.
*
* @author Thibault Duplessis <thibault.duplessis at gmail dot com>
* @license MIT License
*/
class phpGitHubApiObject extends phpGitHubApiAbstract
{

/**
* Get a listing of the root tree of a project by the username, repo, and tree SHA
* http://develop.github.com/p/object.html#trees
*
* @param string $username the username
* @param string $repo the repo
* @param string $treeSHA the tree sha
* @return array root tree of the project
*/
public function showTree($username, $repo, $treeSHA)
{
$response = $this->api->get('tree/show/'.$username.'/'.$repo.'/'.$treeSHA);

return $response['tree'];
}

/**
* Get the data about a blob by tree SHA and file path.
* http://develop.github.com/p/object.html#blobs
*
* @param string $username the username
* @param string $repo the repo
* @param string $treeSHA the tree sha
* @param string $path the path
* @return array data blob of tree and path
*/
public function showBlob($username, $repo, $treeSHA, $path)
{
$response = $this->api->get('blob/show/'.$username.'/'.$repo.'/'.$treeSHA .'/'.$path);

return $response['blob'];
}

/**
* Lists the data blobs of a tree by tree SHA
* http://develop.github.com/p/object.html#blobs
*
* @param string $username the username
* @param string $repo the repo
* @param string $treeSHA the tree sha
* @param string $path the path
* @return array data blobs of tree
*/
public function listBlobs($username, $repo, $treeSHA)
{
$response = $this->api->get('blob/all/'.$username.'/'.$repo.'/'.$treeSHA);

return $response['blobs'];
}
}

0 comments on commit 60a8128

Please sign in to comment.