PHPackages jeffersongoncalves/laravel-github-readme - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Caching](/categories/caching) 4. / 5. jeffersongoncalves/laravel-github-readme ActiveLibrary[Caching](/categories/caching) jeffersongoncalves/laravel-github-readme ======================================== A Laravel package that fetches, renders and disk-caches GitHub repository READMEs. It uses conditional ETag requests with a short freshness window, reuses cached HTML on 304 responses, falls back to stale content on errors, and rewrites relative assets/links to absolute GitHub URLs. Rendered HTML is untrusted — sanitize it before display. v2.0.0(1mo ago)154MITPHPPHP ^8.2CI passing Since Jun 20Pushed 1mo ago1 watchersCompare [ Source](https://github.com/jeffersongoncalves/laravel-github-readme)[ Packagist](https://packagist.org/packages/jeffersongoncalves/laravel-github-readme)[ Docs](https://github.com/jeffersongoncalves/laravel-github-readme)[ GitHub Sponsors](https://github.com/jeffersongoncalves)[ RSS](/packages/jeffersongoncalves-laravel-github-readme/feed)WikiDiscussions master Synced 2w ago READMEChangelog (3)Dependencies (17)Versions (5)Used By (0) [![Laravel GitHub Readme](https://raw.githubusercontent.com/jeffersongoncalves/laravel-github-readme/master/art/jeffersongoncalves-laravel-github-readme.png)](https://raw.githubusercontent.com/jeffersongoncalves/laravel-github-readme/master/art/jeffersongoncalves-laravel-github-readme.png) Laravel GitHub Readme ===================== [](#laravel-github-readme) [![Latest Version on Packagist](https://camo.githubusercontent.com/9fb84177195d23581d21a33a29d67c047385b6fc78e6573637e838d958cd81e0/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6a6566666572736f6e676f6e63616c7665732f6c61726176656c2d6769746875622d726561646d652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/jeffersongoncalves/laravel-github-readme)[![GitHub Tests Action Status](https://camo.githubusercontent.com/9250f068313a973f407577d24f3d423357b173b120d37562ea3e3f8b0e84a011/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6a6566666572736f6e676f6e63616c7665732f6c61726176656c2d6769746875622d726561646d652f72756e2d74657374732e796d6c3f6272616e63683d6d6173746572266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/jeffersongoncalves/laravel-github-readme/actions?query=workflow%3Arun-tests+branch%3Amaster)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/b754f471820d9f965b91e93e44b72d0841f5d85b76af7d31f7baf6927f47a513/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6a6566666572736f6e676f6e63616c7665732f6c61726176656c2d6769746875622d726561646d652f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d6173746572266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/jeffersongoncalves/laravel-github-readme/actions?query=workflow%3A%22Fix+PHP+code+styling%22+branch%3Amaster)[![Total Downloads](https://camo.githubusercontent.com/460dc269fa929a99b92d4e0caf3417e93242a0790939094b04cfe2f4ef0384ff/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6a6566666572736f6e676f6e63616c7665732f6c61726176656c2d6769746875622d726561646d652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/jeffersongoncalves/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 `` in a README cannot become stored XSS, but you should still run the output through an HTML sanitizer (for example [`jeffersongoncalves/laravel-html-sanitizer`](https://github.com/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 ------------ [](#installation) You can install the package via composer: ``` composer require jeffersongoncalves/laravel-github-readme ``` Publish and run the migration (it creates the `github_readme_cache` table): ``` php artisan vendor:publish --tag="laravel-github-readme-migrations" php artisan migrate ``` Optionally publish the config file: ``` php artisan vendor:publish --tag="laravel-github-readme-config" ``` Usage ----- [](#usage) ``` use JeffersonGoncalves\GitHubReadme\GitHubReadme; use JeffersonGoncalves\HtmlSanitizer\Facades\HtmlSanitizer; // example sanitizer // Fetch the default-branch README, rendered to HTML and cached on disk. $html = GitHubReadme::fetchHtml('https://github.com/owner/repo'); // Fetch a specific branch/tag/ref. $html = GitHubReadme::fetchHtml('https://github.com/owner/repo', '2.x'); // ALWAYS sanitize before display — the HTML is untrusted. echo HtmlSanitizer::clean($html); ``` ### Post-processing helpers [](#post-processing-helpers) The rendered HTML can be further decorated with the following static helpers (all pure, all safe to chain): ``` // Open off-site links in a new tab with rel="nofollow noopener". $html = GitHubReadme::markExternalLinks($html, 'mysite.test'); // Lazy-load every image except the first (kept eager as the LCP candidate). $html = GitHubReadme::lazyloadImages($html); // Wrap wide tables in a horizontally-scrollable container. $html = GitHubReadme::wrapTables($html); ``` Other available helpers: `GitHubReadme::repoFromUrl()`, `GitHubReadme::rewriteRelativeAssets()`, and `GitHubReadme::rewriteRelativeLinks()`. How caching works ----------------- [](#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 ------------- [](#configuration) ``` return [ // The filesystem disk used to store rendered README HTML files. 'disk' => env('GITHUB_README_DISK', 'local'), // Minutes a freshly verified README is served without contacting GitHub. 'check_interval_minutes' => (int) env('GITHUB_README_CHECK_INTERVAL', 10), // Optional GitHub token (falls back to config('services.github.token')). 'token' => env('GITHUB_TOKEN', env('GITHUB_README_TOKEN')), // User-Agent header sent on every GitHub API request. 'user_agent' => env('GITHUB_README_USER_AGENT', 'laravel-github-readme'), // Request timeout in seconds. 'timeout' => (int) env('GITHUB_README_TIMEOUT', 8), // Optional renderer callable: fn (string $markdown): string. // Null uses the internal League\CommonMark renderer (GFM + heading permalinks). 'renderer' => null, ]; ``` ### Using a dedicated disk [](#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: ``` // config/filesystems.php 'disks' => [ 'github' => [ 'driver' => 'local', 'root' => storage_path('app/github'), 'throw' => false, ], ], ``` ``` GITHUB_README_DISK=github ``` ### Custom renderer [](#custom-renderer) Provide your own markdown renderer (for example to add server-side syntax highlighting) by setting `renderer` to any callable: ``` 'renderer' => fn (string $markdown): string => \JeffersonGoncalves\Markdown\Markdown::render($markdown, headingPermalinks: true), ``` 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 ------- [](#testing) ``` composer test ``` Changelog --------- [](#changelog) Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. Contributing ------------ [](#contributing) Please see [CONTRIBUTING](.github/CONTRIBUTING.md) for details. Security Vulnerabilities ------------------------ [](#security-vulnerabilities) Please review [our security policy](../../security/policy) on how to report security vulnerabilities. Credits ------- [](#credits) - [Jèfferson Gonçalves](https://github.com/jeffersongoncalves) - [All Contributors](../../contributors) License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 43 — FairBetter than 89% of packages Maintenance91 Actively maintained with recent releases Popularity14 Limited adoption so far Community9 Small or concentrated contributor base Maturity49 Maturing project, gaining track record Bus Factor1 Top contributor holds 87.5% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~0 days Total 3 Last Release 44d ago Major Versions v1.0.1 → v2.0.02026-06-21 ### Community Maintainers ![](https://avatars.githubusercontent.com/u/411493?v=4)[Jefferson Gonçalves](/maintainers/jeffersongoncalves)[@jeffersongoncalves](https://github.com/jeffersongoncalves) --- Top Contributors [![jeffersongoncalves](https://avatars.githubusercontent.com/u/411493?v=4)](https://github.com/jeffersongoncalves "jeffersongoncalves (7 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)") --- Tags cachecomposergithubgithub-apijeffersongoncalveslaravellaravel-packagemarkdownphpreadmelaraveljeffersongoncalveslaravel-github-readme ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/jeffersongoncalves-laravel-github-readme/health.svg) ``` [![Health](https://phpackages.com/badges/jeffersongoncalves-laravel-github-readme/health.svg)](https://phpackages.com/packages/jeffersongoncalves-laravel-github-readme) ``` ### Alternatives [spatie/laravel-medialibrary Associate files with Eloquent models 6.2k45.4M679](/packages/spatie-laravel-medialibrary)[spatie/laravel-health Monitor the health of a Laravel application 88212.7M180](/packages/spatie-laravel-health)[psalm/plugin-laravel Psalm plugin for Laravel 3355.4M352](/packages/psalm-plugin-laravel)[simplestats-io/laravel-client Server-side analytics for Laravel that follows the full funnel from visit to registration to payment, attributed to the channel that drove it. Revenue, MRR, churn and ad-spend profit (ROAS/CAC) per channel. GDPR compliant, ad-blocker proof. 5222.6k](/packages/simplestats-io-laravel-client)[api-platform/laravel API Platform support for Laravel 58174.6k18](/packages/api-platform-laravel)[forjedio/inertia-table Backend-driven dynamic tables for Laravel + Inertia.js 272.0k](/packages/forjedio-inertia-table) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)