Github Api Laravel Package

Getting Started

Start by installing the package and a PSR-18/PSR-17-compliant HTTP client (e.g., Guzzle). In a Laravel app, prefer using the Graham Campbell Laravel-GitHub wrapper for automatic service provider and facade setup.

composer require knplabs/github-api:^3.0 guzzlehttp/guzzle:^7.0 http-interop/http-factory-guzzle:^1.0

Then create and configure the client. For basic unauthenticated use (rate-limited at 60 req/h):

use Github\Client;

$client = new Client();
$repos = $client->api('user')->repositories('ornicar');

For authenticated operations (higher rate limit, access to private data), use an OAuth token or GitHub App token:

$client->authenticate($accessToken, Client::AUTH_HTTP_TOKEN);

Implementation Patterns

• API Grouping by Resource: Use $client->api('resource') to access endpoint groups (user, repo, organization, actions, enterprise, secretScanning, etc.). Methods map closely to GitHub API v3 paths (e.g., client->api('repo')->show('KnpLabs', 'php-github-api')).

• Laravel Integration: Install graham-campbell/github, then use Github::api('repo')->list('KnpLabs') via facade or inject Github\Client via dependency injection. Configure via config/github.php (token, cache, HTTP options).

• Caching: Attach a PSR-6 cache pool (e.g., Redis, Doctrine) to reduce calls and avoid rate limiting:

use Cache\Adapter\Redis\RedisCachePool;
$pool = new RedisCachePool(new Redis());
$client->addCache($pool);

• HTTP Customization: For custom headers, middlewares, or client switching (Symfony HttpClient, Amp, etc.), inject via Client::createWithHttpClient() or an HttpClient\Builder with plugins.

• Fallback via Raw Requests: If missing coverage (e.g., newer GitHub APIs), use low-level methods:

$response = $client->getHttpClient()->get('repos/{owner}/{repo}/actions/runs');
$runs = \Github\HttpClient\Message\ResponseMediator::getContent($response);

Gotchas and Tips

• PSR Compliance Dependency: Ensure a PSR-17 factory and PSR-18 client are installed. PHP-HTTP discovery may fail silently if none found — explicitly inject one for reliability.

• Rate Limits & Pagination: All endpoints have rate limits (unauth: 60/h, auth: 5000/h). Use $client->getHttpClient()->getLastResponse() to inspect X-RateLimit-* headers. Paginated responses require manual iteration (?page=N via list($items, $headers) or ->list...($params, $page)).

• Authentication Gotcha: Don’t pass tokens as strings in URLs — use authenticate() only. Some endpoints (e.g., Actions secrets) require fine-grained scopes (repo, admin:org, actions).

• Typed Responses: Responses are always associative arrays (no DTOs). Use docblocks and IDE hints to infer structure. For large payloads, enable caching or stream with stream_context_create.

• Enterprise vs GitHub.com: Enterprise APIs often require api('enterprise') or api('admin') paths. Secret scanning, organization roles, and SSO require admin/authz tokens and are only available on Enterprise Cloud or GitHub Enterprise Server 3.5+.

• Extensibility: Extend Github\Client or write custom API wrappers for unsupported endpoints. Use Github\HttpClient\Plugin\RateLimitPlugin (via Github\HttpClient\Builder) to auto-throttle requests.

• Testing: Mock Client and stub returned arrays. Avoid real HTTP calls in unit tests — use MockHttpClient from Nyholm/psr7 or HttpMock.