Laravel Github Readme Laravel Package

Getting Started

• Install with composer require jeffersongoncalves/laravel-github-readme and publish the config (php artisan vendor:publish --tag="github-readme-config"). The config file is the first place to look — it holds the repository owner/name defaults, GitHub token, cache TTL, and rendering options.
• Add a GITHUB_TOKEN (and optionally GITHUB_REPOSITORY) to .env. Unauthenticated GitHub API calls are rate-limited to 60/hour, so a token is effectively required for anything beyond local tinkering. Look at the package's config keys first to confirm exact env names before wiring them into .env.example.
• The first, most common use case: render a project's README on a marketing/landing page. A typical Blade call looks like a component or facade method that returns rendered HTML — check the package's src/ for the facade accessor and the Blade component namespace to get the exact syntax.
• Verify the integration quickly with php artisan tinker (call the facade/service and dump the returned string) before embedding it in a view. This isolates API/config problems from HTML/CSS problems.
• If the package ships migrations or views, run php artisan vendor:publish with the relevant tags and php artisan migrate as instructed in the README. Many of these small packages only need the config, so read the publish tags carefully.

Implementation Patterns

• Cache-first rendering. These packages almost always wrap the GitHub call in Cache::remember. Keep the TTL in config, not hardcoded, and consider a longer TTL in production (e.g. 1–6 hours) since READMEs change infrequently and every cache miss is a rate-limit hit.
• Render in a Blade component, not the controller. Keeps the controller thin and lets you swap the README widget in/out of layouts. Wrap the output in a prose-style container (Tailwind Typography or similar) so Markdown-rendered HTML matches your design system.
• Multiple repositories. If the config only exposes one repository, the most reliable pattern is to instantiate/resolve the service per-repository (constructor argument or a forRepository()-style setter, depending on the API surface) rather than mutating global config at runtime — mutating config mid-request is a classic source of bleed-through bugs in queued/octane contexts.
• Warm the cache out-of-band. Create a small artisan command or scheduled job that calls the package on a schedule so user requests never block on the GitHub API. Combine with Cache::forget on deploy if you want fresh content after a release.
• Graceful degradation in views. Wrap the component call so a null/empty result renders a fallback ("Documentation unavailable — see GitHub") rather than an empty box. This is the integration tip most teams skip until the first incident.
• Test with HTTP fakes. Point the package at a faked GitHub response in feature tests (Http::fake) and assert on the rendered HTML. Avoid hitting the real API in CI; without a token you'll flake on rate limits.

Gotchas and Tips

• Timeouts are now handled (v2.0.3). This release catches ConnectionException when the GitHub API times out, so a slow/unreachable GitHub no longer throws an unhandled exception. If you were previously wrapping calls in your own try/catch for Illuminate\Http\Client\ConnectionException, you can likely remove that defensive code — but confirm what the handler returns (null, empty string, or a cached fallback) and make your Blade fallback tolerant of it. Don't assume it returns cached content.
• Rate limiting is the #1 day-to-day failure. A 403 with X-RateLimit-Remaining: 0 means you've exhausted the quota (60/hr unauthenticated, 5000/hr authenticated). Check GITHUB_TOKEN is actually being read, and cache aggressively. Log the X-RateLimit-Reset header when debugging.
• A caught timeout is not a caught 404. Private repositories, typos in the repo name, or renamed repos will 404 rather than time out. Make sure your error handling covers non-2xx responses separately from connection failures.
• Markdown → HTML sanitization. GitHub READMEs can contain relative image/link paths (./assets/logo.png) that break on your domain. Expect to post-process the HTML to rewrite relative URLs to raw.githubusercontent.com, or accept broken images. Also confirm whether the package sanitizes HTML — if not, be cautious rendering arbitrary README content from repos you don't control.
• Cache key collisions. If you render multiple repos, verify the cache key includes the repository identifier. If it doesn't, you'll silently serve one repo's README in place of another — a confusing bug to chase.
• Octane/queue workers. Config and any memoized service state should be resolved per-request or be stateless; long-lived workers can hold stale config. Clear caches and restart workers after config changes.
• Version pinning. v2.0.3 is a patch fix, so it's a safe drop-in from 2.0.2. Pin to ^2.0 and read the changelog between minor bumps — the surrounding release history (v2.0.x) suggests the 2.0 line is where breaking API/config changes landed.