jordanpartridge/github-client

This is my package github-client


README

Latest Version on Packagist GitHub Tests Action Status GitHub Code Style Action Status Total Downloads

A powerful, Laravel-first GitHub API client built on Saloon that makes integrating with GitHub's API simple and intuitive.

Features

  • Built on Saloon for reliable API handling in Laravel
  • Full type-hinting support with typed responses
  • Seamless integration with Laravel's configuration and authentication
  • Comprehensive test coverage
  • Support for facades and dependency injection
  • Modern PHP 8.1+ codebase
  • Laravel-style resource pattern

Installation

Install the package via Composer:

composer require jordanpartridge/github-client

Configuration

  1. Generate a GitHub token in your GitHub Settings
  2. Add the token to your .env file:
GITHUB_TOKEN=your-token-here

Usage

Laravel-Style Resource Pattern

This package follows a Laravel-inspired resource pattern for intuitive API interaction:

use JordanPartridge\GithubClient\Facades\GitHub;

// Working with Repositories
$repos = GitHub::repos(); // Get the repository resource
$allRepos = $repos->all(); // Get all repositories
$specificRepo = $repos->get('jordanpartridge/github-client'); // Get specific repository

// Working with Commits
$commits = GitHub::commits()->all('jordanpartridge/github-client'); // Get all commits for a repository
$specificCommit = GitHub::commits()->get('abc123...'); // Get a specific commit by SHA

// Working with Pull Requests
$prs = GitHub::pullRequests()->all('owner/repo'); // Get all pull requests
$specificPr = GitHub::pullRequests()->get('owner/repo', 123); // Get specific pull request

Each resource follows a consistent pattern similar to Laravel's basic resource operations:

  • all() - Retrieve all resources
  • get() - Retrieve a specific resource

Available Resources

// Repositories
GitHub::repos()->all(); // List all repositories
GitHub::repos()->get('owner/repo'); // Get a specific repository

// Commits
GitHub::commits()->all('owner/repo'); // List all commits for a repository
GitHub::commits()->get('sha'); // Get a specific commit by SHA

// Pull Requests
GitHub::pullRequests()->all('owner/repo'); // List all pull requests
GitHub::pullRequests()->get('owner/repo', 123); // Get a specific pull request
GitHub::pullRequests()->create('owner/repo', 'Title', 'feature-branch', 'main', 'Description'); // Create a pull request
GitHub::pullRequests()->merge('owner/repo', 123, 'Merge message', null, MergeMethod::Squash); // Merge a pull request

// Pull Request Reviews
GitHub::pullRequests()->reviews('owner/repo', 123); // List reviews
GitHub::pullRequests()->createReview('owner/repo', 123, 'LGTM!', 'APPROVE'); // Create a review

// Pull Request Comments
GitHub::pullRequests()->comments('owner/repo', 123); // List comments
GitHub::pullRequests()->createComment('owner/repo', 123, 'Nice work!', 'commit-sha', 'path/to/file.php', 5); // Create a comment

Working with Pull Requests

The package provides comprehensive support for working with GitHub Pull Requests:

use JordanPartridge\GithubClient\Facades\GitHub;
use JordanPartridge\GithubClient\Enums\MergeMethod;

// List pull requests
$pullRequests = GitHub::pullRequests()->all('owner/repo');

// Create a pull request
$pullRequest = GitHub::pullRequests()->create(
    owner: 'owner',
    repo: 'repo',
    title: 'New Feature',
    head: 'feature-branch',
    base: 'main',
    body: 'This PR adds a new feature',
    draft: false
);

// Get a specific pull request
$pullRequest = GitHub::pullRequests()->get('owner', 'repo', 123);

// Update a pull request
$updated = GitHub::pullRequests()->update('owner', 'repo', 123, [
    'title' => 'Updated Title',
    'body' => 'Updated description',
]);

// Merge a pull request
$merged = GitHub::pullRequests()->merge(
    owner: 'owner',
    repo: 'repo',
    number: 123,
    commitMessage: 'Merging new feature',
    mergeMethod: MergeMethod::Squash
);

// Work with reviews
$reviews = GitHub::pullRequests()->reviews('owner', 'repo', 123);
$review = GitHub::pullRequests()->createReview(
    owner: 'owner',
    repo: 'repo',
    number: 123,
    body: 'Looks good!',
    event: 'APPROVE'
);

// Work with comments
$comments = GitHub::pullRequests()->comments('owner', 'repo', 123);
$comment = GitHub::pullRequests()->createComment(
    owner: 'owner',
    repo: 'repo',
    number: 123,
    body: 'Consider this approach',
    commitId: 'abc123',
    path: 'src/File.php',
    position: 5
);

All responses are properly typed using data transfer objects (DTOs) powered by spatie/laravel-data:

  • PullRequestDTO
  • PullRequestReviewDTO
  • PullRequestCommentDTO

Using Dependency Injection

use JordanPartridge\GithubClient\Contracts\GitHub;

public function __construct(
    private readonly GitHub $github
) {}

Custom Configuration

Publish the configuration file:

php artisan vendor:publish --tag="github-client-config"

Documentation

For detailed documentation, please visit our documentation page.

Testing

Run the test suite:

composer test

Contributing

Contributions are welcome! Please:

  1. Add tests for new functionality
  2. Follow PSR-12 coding standards
  3. Submit a Pull Request with a clear description of changes

License

This package is open-source software licensed under the MIT license.

Credits

Built with Saloon and Laravel