jordanpartridge/github-client

This is my package github-client

v0.3.1 2024-12-02 04:31 UTC

Requires

• php: ^8.2
• illuminate/contracts: ^10.0||^11.0
• saloonphp/saloon: ^3.10
• spatie/laravel-data: ^4.11
• spatie/laravel-package-tools: ^1.16

Requires (Dev)

• larastan/larastan: ^2.9
• laravel/pint: ^1.14
• nunomaduro/collision: ^8.1.1||^7.10.0
• orchestra/testbench: ^9.0.0||^8.22.0
• pestphp/pest: ^2.34
• pestphp/pest-plugin-arch: ^2.7
• pestphp/pest-plugin-laravel: ^2.3
• phpstan/extension-installer: ^1.3
• phpstan/phpstan-deprecation-rules: ^1.1
• phpstan/phpstan-phpunit: ^1.3

MIT

• Jordan Partridge

• laravel
• JordanPartridge
• github-client

README

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

• Jordan Partridge
• All Contributors

Built with Saloon and Laravel