jeffersongoncalves/laravel-github-client

A lightweight GitHub REST API client for Laravel with tri-state repository status detection and built-in rate-limit handling.

v1.0.0 2026-06-20 19:51 UTC

Requires

• php: ^8.2
• illuminate/support: ^11.0|^12.0|^13.0
• spatie/laravel-package-tools: ^1.14.0

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/pint: ^1.21
• orchestra/testbench: ^9.0|^10.0|^11.0
• pestphp/pest: ^3.0|^4.0
• pestphp/pest-plugin-laravel: ^3.0|^4.0

MIT

• Jefferson Gonçalves

• http
• rest
• client
• github
• laravel
• GitHub-API
• rate-limit

README

Laravel GitHub Client

A lightweight GitHub REST API client for Laravel. It wraps the api.github.com and raw.githubusercontent.com calls behind a small static client, threads your API token, and centralises rate-limit detection so callers get a thrown GitHubRateLimitException rather than a silent failure during a limit window.

Features

• Tri-state repo status — repoStatus() distinguishes a definitive 404 (gone) from a transient/unknown failure (unknown) so you never prune on doubt
• Repository metadata — fetchRepo() and fetchDefaultBranchForSlug()
• README detection — subdirectoryHasReadme() for monorepo subfolders
• Raw content — fetchManifest() to read JSON files and fileExists() to HEAD a path without downloading it
• Branch listing — fetchBranches() returns the branch names
• Rate-limit aware — throws GitHubRateLimitException on a primary (403 + X-RateLimit-Remaining: 0) or secondary (403/429 + Retry-After) limit, carrying the retryAfter seconds

Installation

composer require jeffersongoncalves/laravel-github-client

Optionally publish the config file:

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

Configuration

Add to your .env:

GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

Create a Personal Access Token to lift the unauthenticated rate limit and access private repositories.

Config Options

// config/github-client.php
return [
    'token' => env('GITHUB_TOKEN'),
    'user_agent' => env('GITHUB_USER_AGENT', 'laravel-github-client'),
    'timeout' => (int) env('GITHUB_TIMEOUT', 8),
];

When github-client.token is null the client falls back to config('services.github.token').

Usage

use JeffersonGoncalves\GitHubClient\GitHubClient;
use JeffersonGoncalves\GitHubClient\Exceptions\GitHubRateLimitException;

// Tri-state existence probe
$status = GitHubClient::repoStatus('jeffersongoncalves/laravel-github-client');
// GitHubClient::REPO_EXISTS | REPO_GONE | REPO_UNKNOWN

// Repository metadata
$repo = GitHubClient::fetchRepo('jeffersongoncalves/laravel-github-client');
$branch = GitHubClient::fetchDefaultBranchForSlug('jeffersongoncalves/laravel-github-client');

// Branches
$branches = GitHubClient::fetchBranches('jeffersongoncalves/laravel-github-client');

// Raw content
$composer = GitHubClient::fetchManifest('jeffersongoncalves/laravel-github-client', 'main', 'composer.json');
$hasDockerfile = GitHubClient::fileExists('jeffersongoncalves/laravel-github-client', 'main', 'Dockerfile');

// Monorepo README detection
$hasReadme = GitHubClient::subdirectoryHasReadme('alpinejs/alpine', 'packages/anchor');

Handling rate limits

try {
    $status = GitHubClient::repoStatus('owner/repo');
} catch (GitHubRateLimitException $e) {
    // Back off for $e->retryAfter seconds (queue jobs can release($e->retryAfter)).
}

Testing

composer test

Static Analysis

composer analyse

Code Formatting

composer format

Changelog

Please see CHANGELOG for more information on what has changed recently.

License

The MIT License (MIT). Please see License File for more information.