README

PHP GitHub API

一个简单的面向对象的GitHub API包装器，使用PHP5编写。

    $github = new Github_Client();
    $myRepos = $github->getRepoApi()->getUserRepos('ornicar');

使用 GitHub API v2。对象API与RESTful API非常相似。

功能

使用PHP方法覆盖了100%的GitHub API
支持3种认证方法
遵循PEAR约定和编码标准：易于自动加载
由于API类的延迟加载，轻量且快速
由于依赖注入，灵活且可扩展
经过广泛测试和文档化

要求

PHP 5.2或5.3。
php curl，但可以编写另一个传输层。
PHPUnit运行测试。

自动加载

使用php-github-api的第一步是注册其自动加载器

    require_once '/path/to/lib/Github/Autoloader.php';
    Github_Autoloader::register();

将 /path/to/lib/ 路径替换为您用于php-github-api安装的路径。

php-github-api遵循其类的PEAR约定名称，这意味着您可以将php-github-api类的加载集成到自己的自动加载器中。

实例化一个新的GitHub客户端

    $github = new Github_Client();

从这个对象，您可以访问以下列出的所有GitHub API。

用户

返回导航

搜索用户，获取用户信息和管理认证用户账户信息。包装GitHub用户API。

通过用户名搜索用户

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

返回用户数组。

获取用户信息

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

返回用户信息的数组。

更新用户信息

更改用户属性：姓名、电子邮件、博客、公司、位置。需要身份验证。

    $github->getUserApi()->update('ornicar', array('location' => 'France', 'blog' => 'http://diem-project.org/blog'));

返回用户信息的数组。

获取特定用户关注的用户

    $users = $github->getUserApi()->getFollowing('ornicar');

返回一个关注的用户数组。

获取关注特定用户的用户

    $users = $github->getUserApi()->getFollowers('ornicar');

返回一个关注用户的数组。

关注一个用户

使认证用户关注一个用户。需要身份验证。

    $github->getUserApi()->follow('symfony');

返回一个关注的用户数组。

取消关注一个用户

使认证用户取消关注一个用户。需要身份验证。

    $github->getUserApi()->unFollow('symfony');

返回一个关注的用户数组。

获取特定用户正在关注的仓库

    $users = $github->getUserApi()->getWatchedRepos('ornicar');

返回一个关注的仓库数组。

获取认证用户的电子邮件

    $emails = $github->getUserApi()->getEmails();

返回一个认证用户电子邮件的数组。需要身份验证。

向认证用户添加电子邮件

    $github->getUserApi()->addEmail('my-email@provider.org');

返回一个认证用户电子邮件的数组。需要身份验证。

从认证用户中删除电子邮件

    $github->getUserApi()->removeEmail('my-email@provider.org');

返回一个认证用户电子邮件的数组。需要身份验证。

问题

返回导航

列出问题、搜索、编辑和关闭你的项目问题。封装 GitHub Issue API。

列出项目中的问题

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

返回一个问题数组。

在项目中搜索问题

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

返回一个匹配“bug”术语的关闭问题的数组。

获取关于一个问题的信息

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

返回关于问题的信息数组。

打开一个新的问题

    $github->getIssueApi()->open('ornicar', 'php-github-api', 'The issue title', 'The issue body');

在用户“ornicar”的“php-github-api”仓库中创建一个新的问题。问题分配给认证用户。需要身份验证。返回关于问题的信息数组。

关闭一个问题

    $github->getIssueApi()->close('ornicar', 'php-github-api', 4);

关闭用户“ornicar”的“php-github-api”仓库的第四个问题。需要身份验证。返回关于问题的信息数组。

重新打开一个问题

    $github->getIssueApi()->reOpen('ornicar', 'php-github-api', 4);

重新打开用户“ornicar”的“php-github-api”仓库的第四个问题。需要身份验证。返回关于问题的信息数组。

更新一个问题

    $github->getIssueApi()->update('ornicar', 'php-github-api', 4, array('body' => 'The new issue body'));

更新用户“ornicar”的“php-github-api”仓库的第四个问题。需要身份验证。可用的属性是标题和正文。返回关于问题的信息数组。

列出一个问题评论

    $comments = $github->getIssueApi()->getComments('ornicar', 'php-github-api', 4);

按用户名、仓库名和问题编号列出问题评论。返回问题数组。

在问题上添加评论

    $github->getIssueApi()->addComment('ornicar', 'php-github-api', 4, 'My new comment');

通过用户名、仓库名和问题编号向问题添加评论。评论分配给认证用户。需要认证。

列出项目标签

    $labels = $github->getIssueApi()->getLabels('ornicar', 'php-github-api');

通过用户名和仓库名列出所有项目标签。返回项目标签数组。

在问题上添加标签

    $github->getIssueApi()->addLabel('ornicar', 'php-github-api', 'label name', 4);

通过用户名、仓库名、标签名和问题编号向问题添加标签。需要认证。如果标签尚未在系统中，则将创建它。返回问题标签数组。

从问题上删除标签

    $github->getIssueApi()->removeLabel('ornicar', 'php-github-api', 'label name', 4);

通过用户名、仓库名、标签名和问题编号从问题上删除标签。需要认证。返回问题标签数组。

搜索匹配标签的问题

    $github->getIssueApi()->searchLabel('ornicar', 'php-github-api', 'label name')

返回匹配给定标签的问题数组。

提交

返回导航

获取特定提交的信息、它们引入的差异以及它们更改的文件。封装GitHub Commit API。

列出分支中的提交

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

返回提交数组。

列出文件的提交

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

返回提交数组。

获取单个提交

    $commit = $github->getCommitApi()->getCommit('ornicar', 'php-github-api', '726eac09a3b44411bd86');

返回单个提交。

对象

返回导航

获取Git仓库中特定文件和树的完整版本。封装GitHub objects API。

列出树的目录内容

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

返回包含仓库树的数组。

列出树的全部blob

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

返回包含树blob的数组。

显示blob的信息

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

返回blob信息数组。

显示对象的原始内容

    $rawText = $github->getObjectApi()->getRawData('ornicar', 'php-github-api', 'bd25d1e4ea7eab84b856131e470edbc21b6cd66b');

最后一个参数可以是blob SHA1、tree SHA1或commit SHA1。返回对象的原始文本内容。

仓库

返回导航

搜索仓库、获取仓库信息以及管理认证用户的仓库信息。封装GitHub Repo API。所有方法都描述在该页上。

通过关键词搜索仓库

简单搜索

    $repos = $github->getRepoApi()->search('symfony');

返回一系列仓库列表。

高级搜索

您可以通过语言进行结果筛选。它接受的值与http://github.com/search上的语言下拉菜单相同。

    $repos = $github->getRepoApi()->search('chess', 'php');

您可以指定页码。

    $repos = $github->getRepoApi()->search('chess' , 'php', 2);

获取仓库的详细信息

    $repo = $github->getRepoApi()->show('ornicar', 'php-github-api')

返回关于指定仓库的信息数组。

获取特定用户的仓库

    $repos = $github->getRepoApi()->getUserRepos('ornicar');

返回一系列仓库列表。

获取认证用户可以推送到的仓库

    $repos = $github->getRepoApi()->getPushableRepos();

返回一系列仓库列表。

创建仓库

    $repo = $github->getRepoApi()->create('my-new-repo', 'This is the description of a repo', 'http://my-repo-homepage.org', true);

创建并返回一个名为my-new-repo的公共仓库。

更新仓库

    $repo = $github->getRepoApi()->setRepoInfo('username', 'my-new-repo', array('description' => 'some new description'));

值数组还接受以下参数

描述
主页
has_wiki
has_issues
has_downloads

更新并返回由'username'拥有的名为'my-new-repo'的仓库。

删除仓库

    $token = $github->getRepoApi()->delete('my-new-repo'); // Get the deletion token
    $github->getRepoApi()->delete('my-new-repo', $token);  // Confirm repository deletion

删除my-new-repo仓库。

将仓库设为公开或私有

    $github->getRepoApi()->setPublic('reponame');
    $github->getRepoApi()->setPrivate('reponame');

将'reponame'仓库设为公开或私有，并返回仓库信息。

获取仓库的部署密钥

    $keys = $github->getRepoApi()->getDeployKeys('reponame');

返回'reponame'仓库的部署密钥列表。

向仓库添加部署密钥

    $keys = $github->getRepoApi()->addDeployKey('reponame', 'key title', $key);

向'reponame'仓库添加一个标题为'key title'的密钥，并返回仓库的部署密钥列表。

从仓库中移除部署密钥

    $keys = $github->getRepoApi()->removeDeployKey('reponame', 12345);

从'reponame'仓库中移除id为12345的密钥，并返回仓库的部署密钥列表。

获取仓库的协作者

    $collaborators = $github->getRepoApi()->getRepoCollaborators('username', 'reponame');

返回'reponame'仓库的协作者列表。

向仓库添加协作者

    $collaborators = $github->getRepoApi->addCollaborator('reponame', 'username');

将用户'username'添加为'reponame'仓库的协作者。

从仓库中移除协作者

    $collaborators = $github->getRepoApi->removeCollaborator('reponame', 'username');

从'reponame'仓库中移除协作者'username'。

关注和取消关注仓库

    $repository = $github->getRepoApi->watch('ornicar', 'php-github-api');
    $repository = $github->getRepoApi->unwatch('ornicar', 'php-github-api');

关注或取消关注'ornicar'拥有的'php-github-api'仓库，并返回仓库信息。

复制仓库

    $repository = $github->getRepoApi->fork('ornicar', 'php-github-api');

创建'ornicar'拥有的'php-github-api'的副本，并返回新创建的仓库。

获取仓库的标签

    $tags = $github->getRepoApi()->getRepoTags('ornicar', 'php-github-api');

返回标签列表。

获取仓库的分支

    $tags = $github->getRepoApi()->getRepoBranches('ornicar', 'php-github-api');

返回分支列表。

获取仓库的观察者

    $watchers = $github->getRepoApi()->getRepoWatchers('ornicar', 'php-github-api');

返回“ornicar”拥有的“php-github-api”仓库的观察者列表。

获取仓库的网络（分叉）

    $network = $github->getRepoApi()->getRepoNetwork('ornicar', 'php-github-api');

返回“ornicar”拥有的“php-github-api”仓库的分叉列表，包括原始仓库。

获取仓库的语言

    $contributors = $github->getRepoApi()->getRepoLanguages('ornicar', 'php-github-api');

返回语言列表。

获取仓库的贡献者

    $contributors = $github->getRepoApi()->getRepoContributors('ornicar', 'php-github-api');

返回贡献者列表。

要包括非 GitHub 用户，请将第三个参数设置为 true

    $contributors = $github->getRepoApi()->getRepoContributors('ornicar', 'php-github-api', true);

拉取请求

返回导航

允许您列出特定仓库的拉取请求，列出特定的拉取请求及其讨论，并创建一个拉取请求。封装了 GitHub 拉取请求 API，仍标记为 BETA。所有方法都在那里进行了描述。

按仓库列出所有拉取请求

列出开放拉取请求

    $openPullRequests = $github->getPullRequestApi()->listPullRequests( "ezsystems", "ezpublish", 'open' );

listPullRequests 方法的最后一个参数默认为 'open'。上面的调用等同于

    $openPullRequests = $github->getPullRequestApi()->listPullRequests( "ezsystems", "ezpublish" );

$openPullRequests 包含了这个仓库所有开放拉取请求的数组。

列出已关闭拉取请求

    $closedPullRequests = $github->getPullRequestApi()->listPullRequests( "ezsystems", "ezpublish", 'closed' );

$closedPullRequests 包含了这个仓库所有已关闭拉取请求的数组。

列出特定的拉取请求及其讨论

    $pullRequest15 = $github->getPullRequestApi()->show( "ezsystems", "ezpublish", 15 );

这个调用最后一个参数，拉取请求 ID，可以是从 listPullRequests 的结果中提取的（列出的拉取请求的 'number' 键），或者手动添加的。

$pullRequest15 数组包含了从 listPullRequests 调用的结果中的每个条目相同的元素，加上一个 "discussion" 键，不言而喻。

创建一个拉取请求

拉取请求可以通过提供标题和正文，或者一个 Issue ID 来创建。关于 create 方法的第 3 和 4 个参数的内容细节在此处呈现： http://develop.github.com/p/pulls.html .

填充标题和正文

需要认证。

    $title = "My nifty pull request";
    $body  = "This pull request contains a bunch of enhancements and bug-fixes, happily shared with you";
    $github->getPullRequestApi()->create( "ezsystems", "ezpublish", "master", "testbranch", $title, $body );

这返回了拉取请求的详细信息。

填充 Issue ID

需要认证。提供 issue ID 而不是标题和正文。

    $issueId = 15;
    $github->getPullRequestApi()->create( "ezsystems", "ezpublish", "master", "testbranch", null, null, $issueId );

这返回了拉取请求的详细信息。

请求任何路由

返回导航

您需要的方法尚未存在？您可以通过使用“get”和“post”方法访问任何GitHub路由。例如，

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

返回描述php-github-api仓库的数组。

查看所有GitHub API路由：http://develop.github.com/

身份验证 & 安全

返回导航

大多数GitHub服务不需要身份验证，但有些需要。例如，允许您更改仓库属性的方法和其他一些方法。因此，这一步骤是可选的。

身份验证

GitHub提供了一些不同的身份验证方式。此API实现实现了其中的三种，这些方式由一个函数处理

    $github->authenticate($username, $secret, $method);

$username当然是用户名。$method是可选的。允许的三个值是

Github_Client::AUTH_URL_TOKEN（默认值，如果省略$method）
Github_Client::AUTH_HTTP_TOKEN
Github_Client::AUTH_HTTP_PASSWORD

$secret的所需值取决于选择的$method。对于AUTH_*_TOKEN方法，您应在此处提供API令牌。对于AUTH_HTTP_PASSWORD，您应提供账户的密码。

使用正确的凭据执行$github->authenticate($username, $secret, $method);方法后，所有后续请求都将以指定的用户身份进行。

关于身份验证方法

Github_Client::AUTH_URL_TOKEN身份验证方法将用户名和API令牌发送到URL参数中。Github_Client::AUTH_HTTP_*身份验证方法使用HTTP基本身份验证将它们的值发送到GitHub。Github_Client::AUTH_URL_TOKEN曾经是唯一可用的身份验证方法。为了防止现有应用程序在API升级时更改其行为，此方法被选为此API实现的默认值。但是请注意，GitHub将此方法描述为已弃用。在大多数情况下，您应使用Github_Client::AUTH_HTTP_TOKEN。

取消身份验证

如果您想停止新请求进行身份验证，可以使用deAuthenticate方法。

    $github->deAuthenticate();

自定义php-github-api

返回导航

由于依赖注入，该库具有高度的可配置性和可扩展性。

配置http客户端

想更改，比如，http客户端User Agent吗？

    $github->getHttpClient()->setOption('user_agent', 'My new User Agent');

在Github/HttpClient.php中查看所有可用选项

注入新的http客户端实例

php-github-api提供了一个基于curl的http客户端实现。如果您想使用您自己的http客户端实现，将其注入到Github_Client实例

    // create a custom http client
    class MyHttpClient extends Github_HttpClient
    {
        public function doRequest($url, array $parameters = array(), $httpMethod = 'GET', array $options = array())
        {
            // send the request and return the raw response
        }
    }

您的http客户端实现可能不扩展Github_HttpClient，但只需实现Github_HttpClientInterface。

现在您可以通过Github_Client构造函数注入您的http客户端

    $github = new Github_Client(new MyHttpClient());

或者注入到现有的Github_Client实例

    $github->setHttpClient(new MyHttpClient());

注入新的API部分实例

如果您想使用您自己的API实现，将其注入到GitHubApi中。例如，要替换用户API

    // create a custom User API
    class MyGithubApiUser extends Github_Api_User
    {
      // overwrite things
    }

    $github->setApi('user', new MyGithubApiUser($github));

运行测试套件

返回导航

代码是单元测试的。要在您的机器上运行测试，从CLI运行

phpunit

致谢

此库借鉴了phptwitterbot的想法、代码和测试。

贡献者荣誉榜

感谢 noloh 在对象API上的贡献。
感谢 bshaffer 在仓库API上的贡献。
感谢 Rolf van de Krol 无数次的贡献。
感谢 Nicolas Pastorino 在拉取请求API上的贡献。

感谢GitHub提供高质量的API和文档。

ornicar / github-api

维护者

详细信息

README

PHP GitHub API

功能

要求

自动加载

实例化一个新的GitHub客户端

导航

用户

通过用户名搜索用户

获取用户信息

更新用户信息

获取特定用户关注的用户

获取关注特定用户的用户

关注一个用户

取消关注一个用户

获取特定用户正在关注的仓库

获取认证用户的电子邮件

向认证用户添加电子邮件

从认证用户中删除电子邮件

问题

列出项目中的问题

在项目中搜索问题

获取关于一个问题的信息

打开一个新的问题

关闭一个问题

重新打开一个问题

更新一个问题

列出一个问题评论

在问题上添加评论

列出项目标签

在问题上添加标签

从问题上删除标签

搜索匹配标签的问题

提交

列出分支中的提交

列出文件的提交

获取单个提交

对象

列出树的目录内容

列出树的全部blob

显示blob的信息

显示对象的原始内容

仓库

通过关键词搜索仓库

简单搜索

高级搜索

获取仓库的详细信息

获取特定用户的仓库

获取认证用户可以推送到的仓库

创建仓库

更新仓库

删除仓库

将仓库设为公开或私有

获取仓库的部署密钥

向仓库添加部署密钥

从仓库中移除部署密钥

获取仓库的协作者

向仓库添加协作者

从仓库中移除协作者

关注和取消关注仓库

复制仓库

获取仓库的标签

获取仓库的分支

获取仓库的观察者

获取仓库的网络（分叉）

获取仓库的语言

获取仓库的贡献者

拉取请求

按仓库列出所有拉取请求

列出开放拉取请求

列出已关闭拉取请求

列出特定的拉取请求及其讨论

创建一个拉取请求

填充标题和正文

填充 Issue ID

请求任何路由

身份验证 & 安全