github php补丁,github-api3-php

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('[e-mail]', '[e-mail]'));

// 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 [e-mail]:dsyph3r/github-api3-php.git

$cdgithub-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' => '[e-mail]',

'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('[e-mail]');

// Add multiple

$response = $user->emails()->create(array('[e-mail]', '[e-mail]'));

Delete email address(es)

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

TRUE.

// Delete single

$response = $user->emails()->delete('[e-mail]');

// Delete multiple

$response = $user->emails()->delete(array('[e-mail]', '[e-mail]'));

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