Laravel GitHub Client

https://github.com/jeffersongoncalves/laravel-github-client
Admin
Laravel GitHub Client is a lightweight GitHub REST API client for Laravel with tri-state repository...
Tokens:3,523
Snippets:44
Trust Score:9.8
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Laravel GitHub Client

Source: https://github.com/jeffersongoncalves/laravel-github-client/blob/master/README.md

Install the package via Composer.

```bash
composer require jeffersongoncalves/laravel-github-client
```

--------------------------------

### Usage Examples

Source: https://github.com/jeffersongoncalves/laravel-github-client/blob/master/README.md

Basic usage examples for the static client methods: repoStatus, fetchRepo, fetchDefaultBranchForSlug, fetchBranches, fetchManifest, fileExists, and subdirectoryHasReadme.

```php
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');
```

--------------------------------

### Publish Config File

Source: https://github.com/jeffersongoncalves/laravel-github-client/blob/master/README.md

Optionally publish the configuration file.

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

--------------------------------

### Run Tests

Source: https://github.com/jeffersongoncalves/laravel-github-client/blob/master/README.md

Run the test suite.

```bash
composer test
```

--------------------------------

### Config Options

Source: https://github.com/jeffersongoncalves/laravel-github-client/blob/master/README.md

Configuration options for the package. When 'token' is null, the client falls back to config('services.github.token').

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

--------------------------------

### Run static analysis with PHPStan (level 5 + Larastan)

Source: https://github.com/jeffersongoncalves/laravel-github-client/blob/master/resources/boost/skills/github-client-development/SKILL.md

Runs PHPStan static analysis at level 5 with Larastan. Run from the project root.

```bash
vendor/bin/phpstan analyse
```

--------------------------------

### Format code with Pint (Laravel preset)

Source: https://github.com/jeffersongoncalves/laravel-github-client/blob/master/resources/boost/skills/github-client-development/SKILL.md

Formats code using Pint with the Laravel preset. Run from the project root.

```bash
vendor/bin/pint
```

--------------------------------

### Run Static Analysis

Source: https://github.com/jeffersongoncalves/laravel-github-client/blob/master/README.md

Run static analysis with PHPStan.

```bash
composer analyse
```

--------------------------------

### Configure config/github-client.php

Source: https://github.com/jeffersongoncalves/laravel-github-client/blob/master/resources/boost/skills/github-client-development/SKILL.md

Defines the configuration structure for the GitHub client, including token, user agent, and timeout settings. These values are read lazily to allow runtime overrides.

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

--------------------------------

### Configure GitHub Client Environment Variables

Source: https://github.com/jeffersongoncalves/laravel-github-client/blob/master/resources/boost/skills/github-client-development/SKILL.md

Environment variables for the GitHub client. GITHUB_TOKEN is optional but raises rate limits and unlocks private repos. GITHUB_USER_AGENT sets the user agent, GITHUB_TIMEOUT sets the timeout in seconds.

```env
GITHUB_TOKEN=ghp_your_personal_access_token
GITHUB_USER_AGENT=laravel-github-client
GITHUB_TIMEOUT=8
```

--------------------------------

### Run Code Formatting

Source: https://github.com/jeffersongoncalves/laravel-github-client/blob/master/README.md

Run code formatting.

```bash
composer format
```

--------------------------------

### Test raw-content file existence

Source: https://github.com/jeffersongoncalves/laravel-github-client/blob/master/resources/boost/skills/github-client-development/SKILL.md

Verifies that fileExists returns false when a HEAD request to raw.githubusercontent.com results in a 404 error.

```php
it('returns false when a file HEAD fails', function () {
    Http::fake([
        'raw.githubusercontent.com/*' => Http::response('', 404),
    ]);

    expect(GitHubClient::fileExists('owner/repo', 'main', 'missing.json'))->toBeFalse();
});
```

--------------------------------

### Register Config File in Service Provider

Source: https://github.com/jeffersongoncalves/laravel-github-client/blob/master/resources/boost/skills/github-client-development/SKILL.md

Minimal service provider that registers the config file via spatie/laravel-package-tools. The package short name is github-client, so the published config lives at config/github-client.php.

```php
public function configurePackage(Package $package): void
{
    $package
        ->name('laravel-github-client')
        ->hasConfigFile();
}
```

--------------------------------

### Publish GitHub Client Config with Artisan

Source: https://github.com/jeffersongoncalves/laravel-github-client/blob/master/resources/boost/skills/github-client-development/SKILL.md

Publish the package configuration file to config/github-client.php. The publish tag is github-client-config.

```bash
php artisan vendor:publish --tag=github-client-config
```

--------------------------------

### Run tests with Pest

Source: https://github.com/jeffersongoncalves/laravel-github-client/blob/master/resources/boost/skills/github-client-development/SKILL.md

Executes the test suite using Pest. Run from the project root.

```bash
vendor/bin/pest
```

--------------------------------

### GitHubClient Public API Methods

Source: https://github.com/jeffersongoncalves/laravel-github-client/blob/master/resources/boost/skills/github-client-development/SKILL.md

Public API of the GitHubClient class. Use repoStatus() for a tri-state existence probe (REPO_EXISTS, REPO_GONE, REPO_UNKNOWN) and the other methods for fetching repo data, branches, manifests, and checking file existence. All methods return nullable or typed values as indicated.

```php
use JeffersonGoncalves\GitHubClient\GitHubClient;

// Tri-state existence probe — distinguishes a definitive 404 from doubt
GitHubClient::repoStatus('owner/repo');
// GitHubClient::REPO_EXISTS  — 200
// GitHubClient::REPO_GONE    — 404 (deleted/renamed/private)
// GitHubClient::REPO_UNKNOWN — network error, 5xx, 451, or other refusal

GitHubClient::fetchRepo('owner/repo');                    // array<string,mixed>|null
GitHubClient::fetchDefaultBranchForSlug('owner/repo');    // ?string
GitHubClient::subdirectoryHasReadme('owner/repo', 'dir'); // bool
GitHubClient::fetchManifest('owner/repo', 'main', 'composer.json'); // array<string,mixed>|null
GitHubClient::fetchBranches('owner/repo');                // list<string>
GitHubClient::fileExists('owner/repo', 'main', 'Dockerfile'); // bool
```

--------------------------------

### Mock GitHub API 404 response

Source: https://github.com/jeffersongoncalves/laravel-github-client/blob/master/resources/boost/skills/github-client-development/SKILL.md

Demonstrates how to use Http::fake to simulate a 404 Not Found response from the GitHub API when checking repository status.

```php
use Illuminate\
Support\\Facades\\Http;
use JeffersonGoncalves\\GitHubClient\\GitHubClient;

it('reports a repo as gone on a 404', function () {
    Http::fake([
        'api.github.com/repos/*' => Http::response(['message' => 'Not Found'], 404),
    ]);

    expect(GitHubClient::repoStatus('owner/repo'))->toBe(GitHubClient::REPO_GONE);
});
```

--------------------------------

### Set GitHub Token in .env

Source: https://github.com/jeffersongoncalves/laravel-github-client/blob/master/README.md

Add your GitHub Personal Access Token to the .env file to lift the unauthenticated rate limit and access private repositories.

```env
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
```

--------------------------------

### throwIfRateLimited() Rate-Limit Detection

Source: https://github.com/jeffersongoncalves/laravel-github-client/blob/master/resources/boost/skills/github-client-development/SKILL.md

Detects GitHub rate limits (403/429) and throws GitHubRateLimitException with a retryAfter value floored at 60 seconds. Runs outside the network try/catch so the exception propagates to the caller. Use in queued jobs with release($e->retryAfter) instead of burning attempts.

```php
private static function throwIfRateLimited(Response $response): void
{
    $status = $response->status();

    if ($status !== 403 && $status !== 429) {
        return;
    }

    $retryAfterHeader = $response->header('Retry-After');
    $remaining = $response->header('X-RateLimit-Remaining');

    // Not a rate limit: a plain 403 with remaining > 0 and no Retry-After.
    if ($remaining !== '0' && $retryAfterHeader === '') {
        return;
    }

    $retryAfter = $retryAfterHeader !== ''
        ? (int) $retryAfterHeader
        : ((int) $response->header('X-RateLimit-Reset')) - time();

    throw new GitHubRateLimitException(max(60, $retryAfter));
}
```

--------------------------------

### Assert GitHubRateLimitException on 429

Source: https://github.com/jeffersongoncalves/laravel-github-client/blob/master/resources/boost/skills/github-client-development/SKILL.md

Tests that the client correctly throws a GitHubRateLimitException when receiving a 429 status code, verifying the Retry-After header value.

```php
use JeffersonGoncalves\\GitHubClient\\Exceptions\\GitHubRateLimitException;

it('throws on a 429 honouring Retry-After', function () {
    Http::fake([
        'api.github.com/repos/*' => Http::response('', 429, ['Retry-After' => '120']),
    ]);

    try {
        GitHubClient::repoStatus('owner/repo');
        $this->fail('Expected GitHubRateLimitException.');
    } catch (GitHubRateLimitException $e) {
        expect($e->retryAfter)->toBe(120);
    }
});
```

--------------------------------

### Handling Rate Limits

Source: https://github.com/jeffersongoncalves/laravel-github-client/blob/master/README.md

Handling rate limit exceptions. The exception carries retryAfter seconds; queue jobs can release($e->retryAfter).

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