joomla / github
Joomla Github Package
Fund package maintenance!
joomla
community.joomla.org/sponsorship-campaigns.html
Installs: 42 386
Dependents: 4
Suggesters: 0
Security: 0
Stars: 25
Watchers: 20
Forks: 29
Open Issues: 3
Type:joomla-package
Requires
- php: ^8.1.0
- joomla/http: ^3.0
- joomla/registry: ^3.0
- joomla/uri: ^3.0
Requires (Dev)
- phan/phan: ^5.4.2
- phpstan/phpstan: ^1.10.7
- phpunit/phpunit: ^9.5.28
- squizlabs/php_codesniffer: ^3.7.2
This package is auto-updated.
Last update: 2024-10-08 21:11:39 UTC
README
Using the GitHub Package
The GitHub package is designed to be a straightforward interface for working with GitHub. It is based on version 3 of the GitHub API. You can find documentation on the API at http://developer.github.com/v3/.
GitHub is built upon the Http package which provides an easy way to consume URLs and web services in a transport
independent way. Joomla\Http
currently supports streams, sockets and cURL. It is possible to create a custom
context and inject it into the GitHub class if one so desires.
Instantiating GitHub
Instantiating GitHub is easy:
use Joomla\Github\Github; $github = new Github;
This creates a basic GitHub object that can be used to access publicly available resources on github.com.
Sometimes it is necessary to specify additional options. This can be done by injecting in a Registry object with your preferred options. Support is available for optionally providing a custom GitHub account username and password, as well as a custom URL for the GitHub server (as would be the case for using a local instance of GitHub Enterprise).
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);
A gh.token
option is also available.
Here is an example demonstrating more of the GitHub package:
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));
Accessing the GitHub APIs
The GitHub object using magic methods to access sub-packages of the GitHub server's API that can be accessed using
the ->
object operator.
Where a result is returned by a PHP method, the result is the PHP equivalent of the JSON response that can be found in the GitHub API documentation.
Activity
See http://developer.github.com/v3/activity/.
Events
See 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');
Notifications
See 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');
Starring
See 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');
Watching
See 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');
Gists
See 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');
Comments
See 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 Data
See http://developer.github.com/v3/git/.
Blobs
See 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);
Commits
See 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);
References
See 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');
Tags
See http://developer.github.com/v3/git/tags/.
// Get a Tag $tag = $github->data->tags->get(':owner', ':repo', ':sha'); // Create a Tag Object $github->data->tags->create( ':owner', ':repo', ':tag', ':message', ':object_sha', ':type', ':tagger_name', ':tagger_email', ':tagger_date' );
Trees
See 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');
Issues
See 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);
Assignees
See 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');
Comments
See 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');
Events
See 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');
Labels
See http://developer.github.com/v3/issues/labels/.
// 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');
Milestones
See 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');
Miscellaneous
See http://developer.github.com/v3/misc/.
Gitignore
See 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
See 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
Meta
See http://developer.github.com/v3/meta/
$meta = $github->getMeta();
Ratelimit
See http://developer.github.com/v3/rate_limit/.
$rateLimit = $this->authorization->getRateLimit();
Organisations
See 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
See
// 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');
Teams
See 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
Pull Requests
See 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');
Review Comments
See 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');
TODO
See Also
The following resources contain more information: Joomla! API Reference, GitHub API Reference.
Installation via Composer
Add "joomla/github": "~2.0"
to the require block in your composer.json and then run composer install
.
{ "require": { "joomla/github": "~2.0" } }
Alternatively, you can simply run the following from the command line:
composer require joomla/github "~2.0"
If you want to include the test sources, use
composer require --prefer-source joomla/github "~2.0"