Skip to content
This repository has been archived by the owner on Jul 28, 2022. It is now read-only.

Latest commit

 

History

History
622 lines (420 loc) · 14.1 KB

README.md

File metadata and controls

622 lines (420 loc) · 14.1 KB
Raw

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('[email protected]', '[email protected]'));

    // 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 [email protected]: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'     => '[email protected]',
      '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('[email protected]');
    // Add multiple
    $response = $user->emails()->create(array('[email protected]', '[email protected]'));

Delete email address(es)

Deletes single or multiple address(es) for the authenticated user. On success returns TRUE.

    // Delete single
    $response = $user->emails()->delete('[email protected]');
    // Delete multiple
    $response = $user->emails()->delete(array('[email protected]', '[email protected]'));

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);