A simple, Object Oriented wrapper for GitHub API written with PHP5.
$github = new phpGitHubApi();
$myRepos = $github->getRepoApi()->getUserRepos('ornicar');
Uses GitHub API v2. The way the Object Oriented Interface is organized is mainly inspired by the way GitHub has organized their API Documentation.
Requires php curl.
$github = new phpGitHubApi();
This instanciated API does not offer many function by itself, but provides methods to instanciate the different Sub-API's that GitHub defines in the API documentation. The main API object just provides methods for authentication.
Most GitHub services do not require authentication, but some do. For example the methods that allow you to change properties on Repositories and some others. Therefore this step is facultative.
GitHub provides some different ways of authentication. This API implementation implements three of them which are handled by one function:
$github->authenticate($username, $secret, $method);
$username is, of course, the username. $method is optional. The three allowed values are:
- phpGitHubApi::AUTH_URL_TOKEN (default, if $method is omitted)
- phpGitHubApi::AUTH_HTTP_TOKEN
- phpGitHubApi::AUTH_HTTP_PASSWORD
The required value of $secret depends on the choosen $method. For the AUTH_*_TOKEN methods, you should provide the API token here. For the AUTH_HTTP_PASSWORD, you should provide the password of the account.
After executing the $github->authenticate($username, $secret, $method); method using correct credentials, all further request are done as the given user.
The phpGitHubApi::AUTH_URL_TOKEN authentication method sends the username and API token in URL parameters. The phpGitHubApi::AUTH_HTTP_* authentication methods send their values to GitHub using HTTP Basic Authentication. phpGitHubApi::AUTH_URL_TOKEN used to be the only available authentication method. To prevent existing applications from changing their behavior in case of an API upgrade, this method is choosen as the default for this API implementation. Note however that GitHub describes this method as deprecated. In most case you should use the phpGitHubApi::AUTH_HTTP_TOKEN instead.
If you want to stop new requests from being authenticated, you can use the deAuthenticate method.
$github->deAuthenticate();
Searching users, getting user information and managing authenticated user account information. Wrap GitHub User API.
$users = $github->getUserApi()->search('ornicar');
Returns an array of users.
$user = $github->getUserApi()->show('ornicar');
Returns an array of information about the user.
Change user attributes: name, email, blog, company, location. Requires authentication.
$github->getUserApi()->update('ornicar', array('location' => 'France', 'blog' => 'http://diem-project.org/blog'));
Returns an array of information about the user.
$users = $github->getUserApi()->getFollowing('ornicar');
Returns an array of followed users.
$users = $github->getUserApi()->getFollowers('ornicar');
Returns an array of following users.
Make the authenticated user follow a user. Requires authentication.
$github->getUserApi()->follow('symfony');
Returns an array of followed users.
Make the authenticated user unfollow a user. Requires authentication.
$github->getUserApi()->unFollow('symfony');
Returns an array of followed users.
$users = $github->getUserApi()->getWatchedRepos('ornicar');
Returns an array of watched repos.
$emails = $github->getUserApi()->getEmails();
Returns an array of the authenticated user emails. Requires authentication.
$github->getUserApi()->addEmail('[email protected]');
Returns an array of the authenticated user emails. Requires authentication.
$github->getUserApi()->removeEmail('[email protected]');
Return an array of the authenticated user emails. Requires authentication.
Listing issues, searching, editing and closing your projects issues. Wrap GitHub Issue API.
$issues = $github->getIssueApi()->getList('ornicar', 'php-github-api', 'open');
Returns an array of issues.
$issues = $github->getIssueApi()->search('ornicar', 'php-github-api', 'closed', 'bug');
Returns an array of closed issues matching the "bug" term,.
$issue = $github->getIssueApi()->show('ornicar', 'php-github-api', 1);
Returns an array of information about the issue.
$github->getIssueApi()->open('ornicar', 'php-github-api', 'The issue title', 'The issue body');
Creates a new issue in the repo "php-github-api" of the user "ornicar". The issue is assigned to the authenticated user. Requires authentication. Returns an array of information about the issue.
$github->getIssueApi()->close('ornicar', 'php-github-api', 4);
Closes the fourth issue of the repo "php-github-api" of the user "ornicar". Requires authentication. Returns an array of information about the issue.
$github->getIssueApi()->reOpen('ornicar', 'php-github-api', 4);
Reopens the fourth issue of the repo "php-github-api" of the user "ornicar". Requires authentication. Returns an array of information about the issue.
$github->getIssueApi()->update('ornicar', 'php-github-api', 4, array('body' => 'The new issue body'));
Updates the fourth issue of the repo "php-github-api" of the user "ornicar". Requires authentication. Available attributes are title and body. Returns an array of information about the issue.
$comments = $github->getIssueApi()->getComments('ornicar', 'php-github-api', 4);
List an issue comments by username, repo and issue number. Returns an array of issues.
$github->getIssueApi()->addComment('ornicar', 'php-github-api', 4, 'My new comment');
Add a comment to the issue by username, repo and issue number. The comment is assigned to the authenticated user. Requires authentication.
$labels = $github->getIssueApi()->getLabels('ornicar', 'php-github-api');
List all project labels by username and repo. Returns an array of project labels.
$github->getIssueApi()->addLabel('ornicar', 'php-github-api', 'label name', 4);
Add a label to the issue by username, repo, label name and issue number. Requires authentication. If the label is not yet in the system, it will be created. Returns an array of the issue labels.
$github->getIssueApi()->removeLabel('ornicar', 'php-github-api', 'label name', 4);
Remove a label from the issue by username, repo, label name and issue number. Requires authentication. Returns an array of the issue labels.
$github->getIssueApi()->searchLabel('ornicar', 'php-github-api', 'label name')
Returns an array of issues matching the given label.
Getting information on specific commits, the diffs they introduce, the files they've changed. Wrap GitHub Commit API.
$commits = $github->getCommitApi()->getBranchCommits('ornicar', 'php-github-api', 'master');
Returns an array of commits.
$commits = $github->getCommitApi()->getFileCommits('ornicar', 'php-github-api', 'master', 'README');
Returns an array of commits.
$commit = $github->getCommitApi()->getCommit('ornicar', 'php-github-api', '726eac09a3b44411bd86');
Returns a single commit.
Getting full versions of specific files and trees in your Git repositories. Wrap GitHub objects API.
$tree = $github->getObjectApi()->showTree('ornicar', 'php-github-api', '691c2ec7fd0b948042047b515886fec40fe76e2b');
Returns an array containing a tree of the repository.
$blobs = $github->getObjectApi()->listBlobs('ornicar', 'php-github-api', '691c2ec7fd0b948042047b515886fec40fe76e2b');
Returns an array containing the tree blobs.
$blob = $github->getObjectApi()->showBlob('ornicar', 'php-github-api', '691c2ec7fd0b948042047b515886fec40fe76e2b', 'CHANGELOG');
Returns array of blob informations.
$rawText = $github->getObjectApi()->getRawData('ornicar', 'php-github-api', 'bd25d1e4ea7eab84b856131e470edbc21b6cd66b');
The last parameter can be either a blob SHA1, a tree SHA1 or a commit SHA1. Returns the raw text content of the object.
Searching repositories, getting repository information and managing repository information for authenticated users. Wrap GitHub Repo API. All methods are described on that page.
$repos = $github->getRepoApi()->search('symfony');
Returns a list of repositories.
You can filter the results by language. It takes the same values as the language drop down on http://github.com/search. $repos = $github->getRepoApi()->search('chess', 'php');
You can specify the page number: $repos = $github->getRepoApi()->search('chess' , 'php', 2);
$repo = $github->getRepoApi()->show('ornicar', 'php-github-api')
Returns an array of information about the specified repository.
$repos = $github->getRepoApi()->getUserRepos('ornicar');
Returns a list of repositories.
$repos = $github->getRepoApi()->getPushableRepos();
Returns a list of repositories.
$repo = $github->getRepoApi()->create('my-new-repo', 'This is the description of a repo', 'http://my-repo-homepage.org', true);
Creates and returns a public repository named my-new-repo.
$repo = $github->getRepoApi()->setRepoInfo('username', 'my-new-repo', array('description' => 'some new description'));
The value array also accepts the parameters
- description
- homepage
- has_wiki
- has_issues
- has_downloads
Updates and returns the repository named 'my-new-repo' that is owned by 'username'.
$token = $github->getRepoApi()->delete('my-new-repo'); // Get the deletion token
$github->getRepoApi()->delete('my-new-repo', $token); // Confirm repository deletion
Deletes the my-new-repo repository.
$github->getRepoApi()->setPublic('reponame');
$github->getRepoApi()->setPrivate('reponame');
Makes the 'reponame' repository public or private and returns the repository.
$keys = $github->getRepoApi()->getDeployKeys('reponame');
Returns a list of the deploy keys for the 'reponame' repository.
$keys = $github->getRepoApi()->addDeployKey('reponame', 'key title', $key);
Adds a key with title 'key title' to the 'reponame' repository and returns a list of the deploy keys for the repository.
$keys = $github->getRepoApi()->removeDeployKey('reponame', 12345);
Removes the key with id 12345 from the 'reponame' repository and returns a list of the deploy keys for the repository.
$collaborators = $github->getRepoApi()->getRepoCollaborators('reponame');
Returns a list of the collaborators for the 'reponame' repository.
$collaborators = $github->getRepoApi->addCollaborator('reponame', 'username');
Adds the 'username' user as collaborator to the 'reponame' repository.
$collaborators = $github->getRepoApi->removeCollaborator('reponame', 'username');
Remove the 'username' collaborator from the 'reponame' repository.
$repository = $github->getRepoApi->watch('ornicar', 'php-github-api');
$repository = $github->getRepoApi->unwatch('ornicar', 'php-github-api');
Watches or unwatches the 'php-github-api' repository owned by 'ornicar' and returns the repository.
$repository = $github->getRepoApi->fork('ornicar', 'php-github-api');
Creates a fork of the 'php-github-api' owned by 'ornicar' and returns the newly created repository.
$tags = $github->getRepoApi()->getRepoTags('ornicar', 'php-github-api');
Returns a list of tags.
$tags = $github->getRepoApi()->getRepoBranches('ornicar', 'php-github-api');
Returns a list of branches.
$watchers = $github->getRepoApi()->getRepoWatchers('ornicar', 'php-github-api');
Returns list of the users watching the 'php-github-api' owned by 'ornicar'.
$network = $github->getRepoApi()->getRepoNetwork('ornicar', 'php-github-api');
Returns list of the forks of the 'php-github-api' owned by 'ornicar', including the original repository.
$contributors = $github->getRepoApi()->getRepoLanguages('ornicar', 'php-github-api');
Returns a list of languages.
$contributors = $github->getRepoApi()->getRepoContributors('ornicar', 'php-github-api');
Returns a list of contributors.
To include non GitHub users, add a third parameter to true:
$contributors = $github->getRepoApi()->getRepoContributors('ornicar', 'php-github-api', true);
The method you need does not exist yet? You can access any GitHub route by using the "get" and "post" methods. For example,
$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/
The library is highly configurable and extensible thanks to dependency injection.
Wanna change, let's say, the request User Agent?
$github->getRequest()->setOption('user_agent', 'My new User Agent');
See all request available options in request/phpGitHubApiRequest.php
If you want to use your own request implementation, inject it to the GitHubApi:
// create a custom request
class myGitHubRequest extends phpGitHubApiRequest
{
// override things
}
// inject your request instance to the API.
$github->setRequest(new myGitHubRequest());
Your request implementation must extend phpGitHubApiRequest.
If you want to use your own implementation of an API, inject it to the GitHubApi. For example, to replace the user API:
// create a custom User API
class myGitHubApiUser extends phpGitHubApiUser
{
// overwrite things
}
$github->setApi('user', new myGitHubApiUser($github));
All code is fully unit tested. To run tests on your machine, from a CLI, run
php /path/to/php-github-api/prove.php
You should see
test/apiTest.........................................................ok
test/authenticationTest..............................................ok
test/commitTest......................................................ok
test/issueTest.......................................................ok
test/objectTest......................................................ok
test/repoTest........................................................ok
test/userTest........................................................ok
All tests successful.
Files=7, Tests=101
You can choose to run only one test; usefull when working on a feature.
php php test/commitTest.php
This library borrows ideas, code and tests from phptwitterbot.
- Thanks to noloh for his contribution on the Object API.
- Thanks to bshaffer for his contribution on the Repo API.
- Thanks to Rolf van de Krol for his countless contributions.
Thanks to GitHub for the high quality API and documentation.