Laravel Github Stats Laravel Package

Getting Started

v1.5.0 is a minor bump and the release notes are only a compare link (v1.4.1...v1.5.0) with no described features, breaking changes, or deprecations. Treat it as a non-breaking update and confirm scope with composer diff / the GitHub compare view before rolling it across repos. Nothing here changes the day-to-day workflow below.

1. composer require jeffersongoncalves/laravel-github-stats
2. Publish the config (php artisan vendor:publish --tag=...) and look at it first — it is the real documentation for this family of packages: repo list, cache TTL, token key, and any route/view toggles live there.
3. Add GITHUB_TOKEN to .env (a token with no scopes is enough for public repo data) and mirror the key into config/ so config:cache works.
4. First use case: drop a star/fork count on a landing page or footer. Pull it in a controller (or a small view composer) and render numbers, not the raw API payload.

Sanity check before building on it:

php artisan about            # provider registered?
php artisan config:show github-stats

Implementation Patterns

Facade in a controller, cached. The package's value is caching + a thin GitHub API client. Call it from a controller or dedicated GitHubStatsService rather than a Blade template, so you can fall back cleanly and test it.

Scheduled refresh, not request-time fetch. Don't hit the API on page render. Put a scheduled job/command that refreshes a cache entry every 15–60 minutes and let the request path read the cache only. This keeps you far under the 5,000/hr authenticated limit and keeps page latency flat.

Wrap it. Inject a small repository/service class that returns a typed DTO (stars, forks, openIssues, pushedAt) and is bound in a service provider. When the package's return shape or method names shift — likely in a thin wrapper like this — you change one file, not every view.

Config-driven repo list. For multi-repo sites, loop the config array and hydrate a collection, so adding a repo is a config edit, not a code change.

Testing. The package almost certainly uses Laravel's HTTP client under the hood, so Http::fake([...]) with a captured fixture is the reliable path. Assert your DTO mapping and your "API returns 404/rate-limited" fallback, which is the failure mode users actually see.

Inertia/Livewire. Pass the DTO as a prop; don't ship the raw GitHub response to the frontend.

Gotchas and Tips

• Unauthenticated rate limits are 60/hr per IP. In CI or on a shared host you'll silently see stale/empty data. Always ship a token, even in local dev.
• Assume the package degrades quietly. Wrappers like this often return null/empty collections on error instead of throwing. Guard with ?? 0 and render a neutral state; a broken badge is worse than no badge.
• Cache TTL vs. config:cache. TTL is read from config; if you change it in .env and forget php artisan config:cache (or clear it), nothing changes and you'll debug the wrong layer. php artisan cache:clear for the data, config:clear for the settings.
• Renamed/private repos return 404, not an empty success. Handle 404 and 403 (rate limit / abuse detection) distinctly in logs so you can tell which one bit you.
• API shape drift. GitHub's REST payload evolves; if the package maps fields directly, pin the version in composer.json ("^1.5") and keep your fixture tests fresh rather than relying on *.
• Extension points to prefer: the published config, the container binding for the client (swap in a fake/mock), and the cache store. Avoid subclassing internals — thin packages rename things between minors.
• Upgrading: minor version, so composer update jeffersongoncalves/laravel-github-stats is low risk, but re-publish the config and diff it (vendor:publish --force into a temp dir) — silent new config keys are the usual cause of "it stopped working after upgrade."
• Debugging order when numbers look wrong: (1) token present and valid, (2) cache key/TTL, (3) raw API call with curl -H "Authorization: Bearer $TOKEN" https://api.github.com/repos/owner/repo, (4) your wrapper. That sequence isolates package vs. GitHub vs. your code in four steps.