README

使用 GitHub 包

GitHub 包设计为与 GitHub 交互的简单接口。它基于 GitHub API 的第 3 版。您可以在 http://developer.github.com/v3/ 找到 API 文档。

GitHub 是基于 Http 包构建的，该包提供了一种以独立于传输的方式消费 URL 和 Web 服务的简单方法。当前 Joomla\Http 支持流、套接字和 cURL。如果需要，可以创建自定义上下文并将其注入到 GitHub 类中。

实例化 GitHub

实例化 GitHub 很简单

use Joomla\Github\Github;

$github = new Github;

这会创建一个基本的 GitHub 对象，可以用来访问 github.com 上的公共资源。

有时需要指定额外的选项。可以通过注入具有您首选选项的 Registry 对象来完成此操作。支持可选地提供自定义 GitHub 账户用户名和密码，以及 GitHub 服务器（如使用 GitHub Enterprise 的本地实例）的自定义 URL。

use Joomla\Github\Github;
use Joomla\Registry\Registry;

$options = new Registry;
$options->set('api.username', 'github_username');
$options->set('api.password', 'github_password');
$options->set('api.url', 'http://github.enterprise.example.com');

$github = new Github($options);

还有一个 gh.token 选项。

以下是一个演示 GitHub 包更多功能的示例

use Joomla\Github\Github;
use Joomla\Registry\Registry;

$options = new Registry;
$options->set('api.username', 'github_username');
$options->set('api.password', 'github_password');
$options->set('api.url', 'http://myhostedgithub.example.com');

$github = new Github($options);

// get a list of all the user's issues
$issues = $github->issues->getList();

$issueSummary = array();

foreach ($issues as $issue)
{
    $issueSummary[] = '+ ' . $issue->title;
}

$summary = implode("\n", $issueSummary);

$github->gists->create(array('issue_summary.txt' => $summary));

访问 GitHub API

GitHub 对象使用魔法方法通过 -> 对象运算符访问 GitHub 服务器 API 的子包。

当 PHP 方法返回结果时，结果是 GitHub API 文档中可以找到的 JSON 响应的 PHP 相等物。

活动

参见 http://developer.github.com/v3/activity/.

事件

参见 http://developer.github.com/v3/activity/events/.

// List public events.
$events = $github->activity->events->getPublic();

// List repository events.
$events = $github->activity->events->getRepository(':owner', ':repo');

// List issue events for a repository.
$events = $github->activity->events->getIssue(':owner', ':repo');

// List public events for a network of repositories.
$events = $github->activity->events->getNetwork(':owner', ':repo');

// List public events for an organization.
$events = $github->activity->events->getOrg(':org');

// List events that a user has received.
$events = $github->activity->events->getUser(':user');

// List public events that a user has received.
$events = $github->activity->events->getUserPublic(':user');

// List events performed by a user.
$events = $github->activity->events->getByUser(':user');

// List public events performed by a user.
$events = $github->activity->events->getByUserPublic(':user');

// List events for an organization
$events = $github->activity->events->getUserOrg(':user', ':org');

通知

参见 http://developer.github.com/v3/activity/notifications/.

// List your notifications.
$all = true;
$participating = true;
$since = new Date('2012-12-12');
$notifications = $github->activity->notifications->getList($all, $participating, $since);

// List your notifications in a repository.
$notifications = $github->activity->notifications->getListRepository(':owner', ':repo', $all, $participating, $since);

// Mark as read.
$unread = true;
$read = true;
$lastReadAt = new Date('2012-12-12');
$github->activity->notifications->getListRepository($unread, $read, $lastReadAt);

// Mark notifications as read in a repository.
$github->activity->notifications->getListRepository(':owner', ':repo', $unread, $read, $lastReadAt);

// View a single thread.
$thread = $github->activity->notifications->viewThread(':id');

// Mark a thread as read.
$github->activity->notifications->markReadThread(':id', $unread, $read);

// Get a Thread Subscription.
$subscription = $github->activity->notifications->getThreadSubscription(':id');

// Set a Thread Subscription.
$subscribed = true;
$ignored = false;
$github->activity->notifications->setThreadSubscription(':id', $subscribed, $ignored);

// Delete a Thread Subscription.
$github->activity->notifications->deleteThreadSubscription(':id');

星标

参见 http://developer.github.com/v3/activity/starring/.

// List Stargazers.
$starred = $github->activity->starring->getList(':owner', ':repo');

// List repositories being starred.
$starred = $github->activity->starring->getRepositories(':user');

// Check if you are starring a repository.
// @return  boolean  True for a 204 response, False for a 404.
$isStarred = $github->activity->starring->check(':owner', ':repo');

// Star a repository.
$github->activity->starring->star(':owner', ':repo');

// Unstar a repository.
$github->activity->starring->unstar(':owner', ':repo');

关注

参见 http://developer.github.com/v3/activity/watching/.

// List watchers.
$watchers = $github->activity->watching->getList(':owner', ':repo');

// List repositories being watched.
$repos = $github->activity->watching->getRepositories(':user');

// Get a Repository Subscription.
$github->activity->watching->getSubscription(':owner', ':repo');

// Set a Repository Subscription.
$subscribed= true;
$ignored = false;
$subscription = $github->activity->watching->setSubscription(':owner', ':repo', $subscribed, $ignored);

// Delete a Repository Subscription.
$github->activity->watching->deleteSubscription(':owner', ':repo');

// Check if you are watching a repository (LEGACY).
// @return  boolean  True for a 204 response, False for a 404.
$github->activity->watching->check(':owner', ':repo');

// Watch a repository (LEGACY).
$github->activity->watching->watch(':owner', ':repo');

// Stop watching a repository (LEGACY).
$github->activity->watching->unwatch(':owner', ':repo');

代码片段

参见 http://developer.github.com/v3/gists/.

// List gists.
$page = 0;
$limit = 20;
$gists = $github->gists->getList($page, $limit);

// List a user’s gists.
$gists = $github->gists->getListByUser(':user', $page, $limit);

// List all public gists
$gists = $github->gists->getListPublic($page, $limit);

// List the authenticated user’s starred gists.
$gists = $github->gists->getListStarred($page, $limit);

// Get a single gist.
$gist = $github->gists->get(':id');

// Create a gist.
$public = true;
$github->gists->create(array(':local-file-path'), $public, ':description');

// Edit a gist.
$github->gists->edit(':id', $files = array(':local-file-path'), $public, ':description');

// Star a gist.
$github->gists->star(':id');

// Unstar a gist.
$github->gists->unstar(':id');

// Check if a gist is starred.
// @return  boolean  True for a 204 response, False for a 404.
$github->gists->isStarred(':id');

// Fork a gist.
$github->gists->fork(':id');

// Delete a gist.
$github->gists->create(array(':id');

参见 http://developer.github.com/v3/gists/comments/.

// List comments on a gist.
$comments = $github->gists->comments->getList(':gistId');

// Get a single comment.
$comment = $github->gists->comments->get(':commentId');

// Create a comment.
$github->gists->comments->create(':gistId', 'Comment');

// Edit a comment.
$github->gists->comments->edit(':commentId', 'Comment');

// Delete a comment.
$github->gists->comments->delete(':gistId');

Git 数据

参见 http://developer.github.com/v3/git/.

对象

参见 http://developer.github.com/v3/git/blobs/.

// Get a Blob
$blob = $github->data->blobs->get(':owner', ':repo', ':sha');

// Create a Blob
$encoding = 'utf-8';
$github->data->blobs->create(':owner', ':repo', ':content', $encoding);

提交

参见 http://developer.github.com/v3/git/commits/.

// Get a Commit
$commit = $github->data->commits->get(':owner', ':repo', ':sha');

//Create a Commit
$parents = array(':sha');
$commit = $github->data->commits->get(':owner', ':repo', ':message', ':tree', $parents);

引用

参见 http://developer.github.com/v3/git/refs/.

// Get a Reference
$ref = $github->data->refs->get(':owner', ':repo', ':ref');

// Get all References
$namespace = ':namespace';
$page = 0;
$perPage = 20;
$refs = $github->data->refs->getList(':owner', ':repo', ':ref', $namespace, $page, $perPage);

// Create a Reference
$github->data->refs->create(':owner', ':repo', ':ref', ':sha');

// Update a Reference
$force = false;
$github->data->refs->edit(':owner', ':repo', ':ref', ':sha', $force);

// Delete a Reference
$github->data->refs->delete(':owner', ':repo', ':ref');

树

查看 http://developer.github.com/v3/git/trees/。

// Get a Tree
$tree = $github->data->trees->get(':owner', ':repo', ':sha');

// Get a Tree Recursively
$tree = $github->data->trees->getRecursively(':owner', ':repo', ':sha');

// Create a Tree
$tree = array(
    'path' => ':path',
    'mode' => ':mode',
    'type' => 'blob|tree|commit',
    'sha' => ':sha',
    'content' => ':content',
);
$github->data->trees->create(':owner', ':repo', $tree, ':base_tree');

问题

查看 http://developer.github.com/v3/issues/。

// List issues
$filter = 'assigned|created|mentioned|subscribed';
$state = 'open|closed';
$labels = ':label1,:label2';
$sort = 'created|updated|comments';
$direction = 'asc|desc';
$since = new Date('2012-12-12');
$page = 0;
$perPage = 20;
$issues = $github->issues->getList($filter, $state, $labels, $sort, $direction, $since, $page, $perPage);

// List issues for a repository
$milestone = ':milestone|*|none';
$assignee = ':user|none';
$mentioned = ':user';
$issues = $github->issues->getListByRepository(
    ':owner', ':repo', $milestone, $state, $assignee, $mentioned, $labels, $sort, $direction, $since, $page, $perPage
);

// Get a single issue
$issue = $github->issues->get(':user', ':repo', ':issueId');

// Create an issue
$labels = array(':label');
$github->issues->create(':user', ':repo', ':title', ':body', ':assignee', ':milestone', $labels);

// Edit an issue
$github->issues->edit(':user', ':repo', ':issueId', 'open|closed', ':title', ':body', ':assignee', ':milestone', $labels);

分配者

查看 http://developer.github.com/v3/issues/assignees/。

// List assignees
$assignees = $github->issues->assignees->getList(':owner', ':repo');

// Check assignee
$isUserAssigned = $github->issues->assignees->check(':owner', ':repo', ':user');

查看 http://developer.github.com/v3/issues/comments/

// List comments on an issue
$page = 0;
$perPage = 20;
$comments = $github->issues->comments->getList(':owner', ':repo', ':issueId', $page, $perPage);

// List comments in a repository
$sort = 'created|updated';
$direction = 'asc|desc';
$since = new Date('2012-12-12');
$comments = $github->issues->comments->getRepositoryList(':owner', ':repo', $sort, $direction, $since);

// Get a single comment
$comment = $github->issues->comments->get(':owner', ':repo', ':commentId');

// Create a comment
$github->issues->comments->get(':owner', ':repo', ':commentId');

// Edit a comment
$github->issues->comments->edit(':owner', ':repo', ':commentId', ':body');

// Delete a comment
$github->issues->comments->delete(':owner', ':repo', ':commentId');

事件

查看 http://developer.github.com/v3/issues/events/。

// List events for an issue
$page = 0;
$perPage = 20;
$events = $github->issues->events->getList(':owner', ':repo', ':issueId', $page, $perPage);

// List events for a repository
$events = $github->issues->events->getListRepository(':owner', ':repo', ':issueId', $page, $perPage);

// Get a single event
$event = $github->issues->events->get(':owner', ':repo', ':issueId');

// List all labels for this repository
$labels = $github->issues->labels->getList(':owner', ':repo');

// Get a single label
$label = $github->issues->labels->get(':owner', ':repo', ':labelName');

// Create a label
$github->issues->labels->create(':owner', ':repo', ':labelName', ':labelColor');

// Update a label
$github->issues->labels->update(':owner', ':repo', ':oldLableName', ':newLabelName', ':labelColor');

// Delete a label
$github->issues->labels->delete(':owner', ':repo', ':labelName');

// List labels on an issue
$labels = $github->issues->labels->getListByIssue(':owner', ':repo', ':issueNumber');

// Add labels to an issue
$labels = array(':label1', ':label2');
$github->issues->labels->add(':owner', ':repo', ':issueNumber', $labels);

// Remove a label from an issue
$github->issues->labels->removeFromIssue(':owner', ':repo', ':issueNumber', ':labelName');

// Replace all labels for an issue
$github->issues->labels->replace(':owner', ':repo', ':issueNumber', $labels);

// Remove all labels from an issue
$github->issues->labels->removeAllFromIssue(':owner', ':repo', ':issueNumber');

// Get labels for every issue in a milestone
$labels = $github->issues->labels->getListByMilestone(':owner', ':repo', ':milestoneNumber');

里程碑

查看 http://developer.github.com/v3/issues/milestones/。

// List milestones for a repository
$state = 'open|closed';
$sort = 'due_date|completeness';
$direction = 'asc|desc';
$page = 0;
$perPage = 20;
$milestones = $github->issues->milestones->getList(':owner', ':repo', $state, $sort, $direction, $page, $perPage);

// Get a single milestone
$milestone = $github->issues->milestones->get(':owner', ':repo', ':milestoneId');

// Create a milestone
$github->issues->milestones->create(':owner', ':repo', ':title', $state, ':description', ':due_on');

// Update a milestone
$github->issues->milestones->edit(':owner', ':repo', ':milestoneId', ':title', $state, ':description', ':due_on');

// Delete a milestone
$github->issues->milestones->delete(':owner', ':repo', ':milestoneId');

杂项

查看 http://developer.github.com/v3/misc/。

Gitignore

查看 http://developer.github.com/v3/gitignore/

// Listing available templates
$templates = $github->gitignore->getList();

// Get a single template
$raw = false;
$template = $github->gitignore->get(':name', $raw);

Markdown

查看 http://developer.github.com/v3/markdown/。

// Render an arbitrary Markdown document
$mode = 'gfm|markdown';
$context = ':context';
$github->markdown->render(':text', $mode, $context);

// Render a Markdown document in raw mode

元数据

查看 http://developer.github.com/v3/meta/。

$meta = $github->getMeta();

速率限制

查看 http://developer.github.com/v3/rate_limit/。

$rateLimit = $this->authorization->getRateLimit();

组织

查看 http://developer.github.com/v3/orgs/。

// List User Organizations
$orgs = $github->orgs->getList(':user');

// Get an Organization
$orgs = $github->orgs->get(':org');

// Edit an Organization
$github->orgs->edit(':org', ':billingEmail', ':company', ':email', ':location', ':name');

成员

查看

// Members list
$members = $github->orgs->members->getList(':org');

// Check membership
$isUserMember = $github->orgs->members->check(':org', ':user');

// Remove a member
$github->orgs->members->remove(':org', ':user');

// Public members list
$publicMembers = $github->orgs->members->getListPublic(':org');

// Check public membership
$isUserPublicMember = $github->orgs->members->checkPublic(':org', ':user');

// Publicize a user’s membership
$github->orgs->members->publicize(':org', ':user');

// Conceal a user’s membership
$github->orgs->members->conceal(':org', ':user');

团队

查看 http://developer.github.com/v3/orgs/teams/。

// List teams
$teams = $github->orgs->teams->getList(':org');

// Get team
$team = $github->orgs->teams->get(':teamId');

// Create team
$repos = array(':repoName');
$permission = 'pull|push|admin';
$github->orgs->teams->create(':org', ':name', $repos, $permission);

// Edit team
$github->orgs->teams->edit(':teamId', ':name', $permission);

// Delete team
$github->orgs->teams->delete(':teamId');

// List team members
$members = $github->orgs->teams->getListMembers(':teamId');

// Get team member
$isUserMember = $github->orgs->teams->isMember(':teamId', ':user');

// Add team member
$github->orgs->teams->addMember(':teamId', ':user');

// Remove team member
$github->orgs->teams->removeMember(':teamId', ':user');

// List team repos
$repos = $github->orgs->teams->getListRepos(':teamId');

// Get team repo
$isRepoManagedByTeam = $github->orgs->teams->checkRepo(':teamId', ':repo');

// Add team repo
$github->orgs->teams->addRepo(':teamId', ':org', ':repo');

// Remove team repo
$github->orgs->teams->removeRepo(':teamId', ':owner', ':repo');

// List user teams - TODO

拉取请求

查看 http://developer.github.com/v3/pulls/。

// List pull requests
$state = 'open|closed';
$page = 0;
$perPage = 20;
$pulls = $github->pulls->getList(':owner', ':repo', $state, $page, $perPage);

// Get a single pull request
$pull = $github->pulls->get(':owner', ':repo', ':pullId');

// Create a pull request
$github->pulls->create(':owner', ':repo', ':title', ':branch|ref', ':head|ref', ':body');

// Create from issue
$github->pulls->createFromIssue(':owner', ':repo', ':issueId', ':branch|ref', ':head|ref');

// Update a pull request
$state = 'open|closed';
$github->pulls->edit(':owner', ':repo', ':pullId', ':title', ':body', $state);

// List commits on a pull request
$commits = $github->pulls->commits(':owner', ':repo', ':pullId', $page, $perPage);

// List pull requests files
$files = $github->pulls->commits(':owner', ':repo', ':pullId', $page, $perPage);

// Get if a pull request has been merged
$isMerged = $github->pulls->isMerged(':owner', ':repo', ':pullId');

// Merge a pull request
$isMerged = $github->pulls->merge(':owner', ':repo', ':pullId', ':message');

审查评论

查看 http://developer.github.com/v3/pulls/comments/。

// List comments on a pull request
$page = 0;
$perPage = 20;
$comments = $github->pulls->comments->get(':owner', ':repo', ':pullId', $page, $perPage);

// List comments in a repository - TODO

// Get a single comment
$comment = $github->pulls->comments->get(':owner', ':repo', ':commentId');

// Create a comment
$github->pulls->comments->create(':owner', ':repo', ':pullId', ':body', ':commitId', ':filePath', ':position');

// Create a comment
$github->pulls->comments->createReply(':owner', ':repo', ':pullId', ':body', ':replyingToCommentId');

// Edit a comment
$github->pulls->comments->edit(':owner', ':repo', ':commentId', ':body');

// Delete a comment
$github->pulls->comments->delete(':owner', ':repo', ':commentId');

待办事项

另请参阅

以下资源包含更多信息： Joomla! API 参考。

通过 Composer 安装

将 "joomla/github": "~2.0" 添加到 composer.json 中的 require 块，然后运行 composer install。

{
	"require": {
		"joomla/github": "~2.0"
	}
}

或者，您可以直接从命令行运行以下操作

composer require joomla/github "~2.0"

如果您想包含测试源，使用

composer require --prefer-source joomla/github "~2.0"

joomla / github

维护者

详细信息