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