Awesome
GitHub API v3 - PHP Library
Currently under construction.
Overview
Provides access to GitHub API v3 via an Object Oriented PHP library.
The goal of this library is to provide an intuitive Object Oriented wrapper around the GitHub API v3. This is achieved using a number of methods:
- Method chaining to request the resources you require
- Consistent interface for [C]reate (create), [R]etrieve (all|get), [U]pdate (update), [D]elete (delete)
- Abstracting the specific details of the GitHub API
use GitHub\API\User\User;
// Setup the user, and authenticate (using basic HTTP auth)
$user = new User();
$user->setCredentials(new Authentication\Basic('username', 'password'));
$user->login();
// Get the user details
$response = $user->get();
// Now lets get user emails
$emails = $user->emails()->all();
// Add some new emails
$emails = $user->emails()->create(array('email1@test.com', 'email2@test.com'));
// Get my public keys
$keys = $user->keys()->all();
// Update a key
$user->keys()->update(44, 'New key title', 'ssh-rsa ABCDEF');
GitHub API Coverage
The following resources for the API are covered:
Requirements
- PHP 5.3+
Dependancies
Installation
$ git clone git@github.com:dsyph3r/github-api3-php.git
$ cd github-api3-php
$ git submodule update -i
Testing
The library is tested using phpunit. Run tests with
$ phpunit
Documentation
Full documentation is provided in this README. There is also extensive source code documentation and the actual GitHub API documentation.
Credits
Ideas from the excellent php-github-api library by ornicar have been used in this library.
Authentication
Authentication is supported for both basic HTTP and OAuth. OAuth is the recommened way to authenticate. (Note: This library does not actually deal with how you do the OAuth process to retrieve the access token. You must implement this your self. See oauth2-php lib for an implementation of this).
Authentication can be achieved as follows.
OAuth
use GitHub\API\User\User;
$user = new User();
$user->setCredentials(new Authentication\OAuth('access_token'));
$user->login();
// Perform operations that require authentication ...
$user->logout();
Basic
use GitHub\API\User\User;
$user = new User();
$user->setCredentials(new Authentication\Basic('username', 'password'));
$user->login();
// Perform operations that require authentication ...
$user->logout();
Most of the GitHub API requires authentication. Requests made to these methods
without authentication will cause a GitHub\API\AuthenticationException()
to be
thrown.
Once credentials have been set via setCredentials()
you can call login()
and
logout()
without setting the credentials again. Credentials can be cleared
with clearCredentials()
.
$user->clearCredentials();
Users
Perform operations on unauthenticated or authenticated user including retrieval, updating, listing followers, etc.
GitHub API Documentation - User API.
Get user by username
Returns user details. No authentication required.
$response = $user->get('dsyph3r');
Returns user details for authenticated user
$response = $user->get();
Update user
Updates the authenticated user. See API for full list of available update fields. The updated user is returned.
$response = $user->update(array(
'name' => 'dsyph3r',
'email' => 'd.syph.3r@gmail.com',
'location' => 'Wales, UK'
));
List followers
Lists user followers. No authentication required.
$response = $user->followers('dsyph3r');
Lists the followers for authenticated user
$response = $user->followers();
Both requests can return paginated results. The optional 2nd and 3rd parameter are provided to access this functionality. The default pagination result size is 30. GitHub limits the page result size to 100.
$response = $user->followers('dsyph3r', 2, 50); // Get page 2, 50 results per page
List following users
Lists user a user is following. No authentication required.
$response = $user->following('dsyph3r');
Lists the user the authenticated user is following.
$response = $user->following();
Access paginated results.
$response = $user->following('dsyph3r', 2, 50); // Get page 2, 50 results per page
Check user is being followed
Check if authenticated user is following a user. Returns TRUE
is user is being
followed.
$response = $user->isFollowing('octocat');
Follow a user
Follow a user for the authenticated user. Returns TRUE
if user was followed.
$response = $user->follow('octocat');
Unfollow a user
Unfollow a user for the authenticated user. Returns TRUE
if user was unfollowed.
$response = $user->unfollow('octocat');
Access user related API's
Each API can be used independent of other API's. However, proxy methods can be used
to access related API's such as Emails
for a User
. The User
API provides the following
proxies.
// Access email API
$user->emails();
// Access keys API
$user->keys();
// Access repos API
$user->repos();
// Access gists API
$user->gists();
User Emails
Perform operations on authenticated users emails.
GitHub API Documentation - User Email API.
The email API can be used independently of the other API's as follows:
use GitHub\API\User\Email;
$email = new Email();
$response = $email->all();
However, as emails are related to the user you can also access the email API via the user as follows:
use GitHub\API\User\User;
$user = new User();
$response = $user->emails()->all();
There are a number of benefits to this approach including increased readability, and authentication being carried across from each independent API, i.e. you don't have to authenticated the user and the email API.
List emails
List all email addresses for authenticated user.
$response = $user->emails()->all();
Add email address(es)
Adds single or multiple address(es) for the authenticated user. On success returns
list of all email address for user. On failure returns FALSE
. This operation
can fail if email addresses already exist for the user.
// Add single
$response = $user->emails()->create('dsyph3r@gmail.com');
// Add multiple
$response = $user->emails()->create(array('dsyph3r@gmail.com', 'octocat@github.com'));
Delete email address(es)
Deletes single or multiple address(es) for the authenticated user. On success returns
TRUE
.
// Delete single
$response = $user->emails()->delete('dsyph3r@gmail.com');
// Delete multiple
$response = $user->emails()->delete(array('dsyph3r@gmail.com', 'octocat@github.com'));
User Keys
Perform operations on authenticated users keys.
GitHub API Documentation - User Keys API.
The keys API can be used independently of the other API's as follows:
use GitHub\API\User\Key;
$key = new Key();
$response = $key->all();
However, as keys are related to the user you can also access the keys API via the user as follows:
use GitHub\API\User\User;
$user = new User();
$response = $user->keys()->all();
List keys
List all keys for authenticated user.
$response = $user->keys()->all();
Get key
Get a key for authenticated user by key ID.
$response = $user->keys()->get(1);
Add key
Adds a key for authenticated user. On success returns the created key.
On failure returns FALSE
. This operation can fail if the key is invalid.
$response = $user->keys()->create('desktop@dsyph3r', 'ssh-rsa ABCDEF');
Update key
Update a key for authenticated user by key ID. On success returns the updated key.
On failure returns FALSE
. This operation can fail if the key is invalid.
$response = $user->keys()->update(1, 'desktop@dsyph3r', 'ssh-rsa FEDCBA');
Delete key
Delete a key for authenticated user by ID. On success returns TRUE
.
$response = $user->keys()->delete(1);
Gists
Perform operations on gists.
GitHub API Documentation - Gists API.
The gists API can be used independently of the other API's as follows:
use GitHub\API\Gist\Gist;
$gist = new Gist();
$response = $gist->all();
List gists
List all public gists. No authentication required.
$response = $gist->all();
List all public gists for a user
$response = $gist->all('dsph3r');
List all public gists for authenticated user.
$gist->login();
$response = $gist->all();
List all starred gists for authenticated user.
$gist->login();
$response = $gist->all(null, Api::GIST_TYPE_STARRED);
All above operations return paginated results. Accessing paginated results is as follows.
$response = $gist->all('dsyph3r', Api::GIST_TYPE_PUBLIC, 2, 50); // Get page 2, 50 results per page
Get gist
Get a gist. Authentication maybe required depending on the gist permissions, ie. Private gist
$response = $gist->get(1);
Create gist
Creates a gist for authenticated user. On success returns the created gist.
On failure returns FALSE
.
Gists contain files and should be passed in as an array.
$files = array(
'file1.txt' => array(
'content' => 'File 1 contents',
),
'file2.txt' => array(
'content' => 'File 2 contents',
),
);
$response = $gist->create($files, true, "Gist description");
Update gist
Updates a gist for authenticated user. On success returns the updated gist.
On failure returns FALSE
.
Gists contain files and should be passed in as an array. Setting a filename key value to null will removed the file from the gist. Leaving filename keys out will cause no update to the gist file.
$files = array(
'file1.txt' => array(
// Update the contents of this file
'content' => 'File 1 contents update',
),
// This file will be removed from gist
'file2.txt' => null,
);
$response = $gist->update(1, $files, "Gist description update");
Star gist
Star a gist for the authenticated user. Returns TRUE
if gist was starred.
$response = $gist->star(1);
Unstar gist
Unstar a gist for the authenticated user. Returns TRUE
if gist was unstarred.
$response = $gist->unstar(1);
Check gist is starred
Check if gist is starred for the authenticated user. Returns TRUE
if gist is starred.
$response = $gist->isStarred(1);
Fork gist
Fork a gist for the authenticated user. Returns TRUE
if gist was forked.
$response = $gist->fork(1);
Delete gist
Delete a gist for the authenticated user. Returns TRUE
if gist was deleted.
$response = $gist->delete(1);
Access gists related API's
Each API can be used independent of other API's. However, proxy methods can be used
to access related API's such as Comments
for a Gist
. The Gist
API provides the following
proxies.
// Access gist comments API
$gist->comments();
Gist Comments
Perform operations on gist comments.
GitHub API Documentation - Gists Comments API.
The gists comments API can be used independently of the other API's as follows:
use GitHub\API\Gist\Comment;
$comment = new Comment();
$response = $comment->all();
However, as comments are related to the gists you can also access the comments API via the gist as follows:
use GitHub\API\Gist\Gist;
$gist = new Gist();
$response = $gist->comments()->all();
Custom Mime Types
Gist comments use custom mime types to return formatted results. Custom mime types can be passed in as an argument to most functions. Available formats are:
Api::FORMAT_RAW; // Default
Api::FORMAT_TEXT;
Api::FORMAT_HTML;
Api::FORMAT_FULL;
List comments
List all comments for gist. Authentication maybe required depending on the gist permissions, ie. Private gist
$response = $gist->comments()->all(1);
Get the results in HTML
format
$response = $gist->comments()->all(1, Api::FORMAT_HTML);
Get comment
Get a gist comment. Authentication maybe required depending on the gist permissions, ie. Private gist
$response = $gist->comments()->get(1);
Create comment
Creates a gist comment for authenticated user. On success returns the created comment.
On failure returns FALSE
.
$response = $gist->comments()->create(1, "Comment Body");
Update comment
Updates a gist comment for authenticated user. On success returns the updated comment.
On failure returns FALSE
.
$response = $gist->comments()->update(1, "Comment body update");
Delete comment
Delete a gist comment for the authenticated user. Returns TRUE
if gist comment was deleted.
$response = $gist->comments()->delete(1);