New

Just launched: Vueblocks, a brand-new search engine for Vue packages! Explore Vueblocks →

jeffersongoncalves/laravel-github-client

A lightweight GitHub REST API client for Laravel with tri-state repository status detection and built-in rate-limit handling.
1,654 1
Install
composer require jeffersongoncalves/laravel-github-client
Latest Version:v1.2.0
PHP:^8.2
Laravel:11 · 12 · 13
License:MIT
Last Updated:Nov 2, 2026
Links: GitHub  ·  Packagist
Maintainer: jeffersongoncalves

Laravel GitHub Client

Laravel GitHub Client

Buy Me A Coffee

Tests PHPStan Code Style Latest Version on Packagist Total Downloads License

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, following pagination up to $maxPages (default 10 × 100 branches, one REST call per page); fetchVersionBranches() returns only *.x branches in a single GraphQL call (token required)
  • 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'); // up to 10 pages
$versions = GitHubClient::fetchVersionBranches('jeffersongoncalves/laravel-github-client'); // ['1.x', '2.x', ...]

// 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.

Related Packages

laragear/api-manager

Manage multiple REST servers to make requests in few lines and fluently.

2,693 16
cline/relay

A modern, attribute-driven HTTP client for PHP

12,212 0
rap2hpoutre/jacky

Opinionated REST JSON HTTP API client for laravel

4,407 17
othercode/rest

Rest client to make GET, POST, PUT, DELETE, PATCH, etc calls.

49,549 11

Version History

Version Released PHP Laravel License
v1.2.0 ^8.2 ^11.0|^12.0|^13.0 MIT
v1.1.0 ^8.2 ^11.0|^12.0|^13.0 MIT
v1.0.0 ^8.2 ^11.0|^12.0|^13.0 MIT