Download the PHP package jeffersongoncalves/laravel-github-readme without Composer

Laravel GitHub Readme

Fetch, render and disk-cache GitHub repository READMEs in your Laravel application. The package issues conditional If-None-Match (ETag) requests with a short freshness window, reuses the cached HTML on 304 Not Modified responses, falls back to stale content on network/API errors, and rewrites relative assets and links to absolute GitHub URLs.

[!WARNING] The HTML returned by this package is untrusted — it comes from third-party GitHub READMEs. The built-in renderer strips raw HTML (html_input => 'strip') so an embedded <script> in a README cannot become stored XSS, but you should still run the output through an HTML sanitizer (for example jeffersongoncalves/laravel-html-sanitizer) before rendering it in a browser. If you supply a custom renderer that allows raw HTML, sanitizing the output is mandatory.

[!CAUTION] Pass only trusted repository URLs to fetchHtml(). The URL determines which GitHub API endpoint is called with your configured token. An attacker-controlled URL can therefore drive token-scoped requests against arbitrary repositories (private-repo read access, rate-limit abuse). If the URL can come from user input, validate it against an allowlist of owner/repo values you control before calling fetchHtml() — for example in_array(GitHubReadme::repoFromUrl($url), $allowedRepos, true).

Installation

You can install the package via composer:

Publish and run the migration (it creates the github_readme_cache table):

Optionally publish the config file:

Usage

Post-processing helpers

The rendered HTML can be further decorated with the following static helpers (all pure, all safe to chain):

Other available helpers: GitHubReadme::repoFromUrl(), GitHubReadme::rewriteRelativeAssets(), and GitHubReadme::rewriteRelativeLinks().

How caching works

1. Freshness window — within check_interval_minutes of the last successful check, the cached HTML file is served straight from disk with no GitHub call at all.
2. Conditional request — outside the window a conditional If-None-Match request is made. A 304 Not Modified reuses the cached file (and does not count against the rate limit).
3. Re-render — a 200 response re-renders the markdown, rewrites relative assets/links, stores the file on disk and updates the github_readme_cache row.
4. Stale fallback — on a network/API error the stale cached file is served when present.

Configuration

Using a dedicated disk

By default the framework's built-in local disk is used. To isolate cached READMEs, define a dedicated disk in config/filesystems.php and point the disk option at it:

Custom renderer

Provide your own markdown renderer (for example to add server-side syntax highlighting) by setting renderer to any callable:

The built-in renderer strips raw HTML (html_input => 'strip'). If your custom renderer keeps raw HTML (e.g. html_input => 'allow'), you are responsible for sanitizing the result before it reaches a browser.

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Jèfferson Gonçalves
• All Contributors

License

The MIT License (MIT). Please see License File for more information.