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. v1.0.0(today)10MITPHPPHP ^8.2CI passing Since Jun 20Pushed today1 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 today READMEChangelog (2)Dependencies (8)Versions (3)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. Always run it through an HTML sanitizer (for example [`jeffersongoncalves/laravel-html-sanitizer`](https://github.com/jeffersongoncalves/laravel-html-sanitizer)) before rendering it in a browser. 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), ``` 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 41 — FairBetter than 87% of packages Maintenance100 Actively maintained with recent releases Popularity2 Limited adoption so far Community9 Small or concentrated contributor base Maturity47 Maturing project, gaining track record Bus Factor1 Top contributor holds 83.3% 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 Unknown Total 1 Last Release 0d ago ### 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 (5 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 ### 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-responsecache Speed up a Laravel application by caching the entire response 2.8k8.7M64](/packages/spatie-laravel-responsecache)[spatie/laravel-health Monitor the health of a Laravel application 87411.3M152](/packages/spatie-laravel-health)[psalm/plugin-laravel Psalm plugin for Laravel 3325.1M337](/packages/psalm-plugin-laravel)[clickbar/laravel-magellan This package provides functionality for working with the postgis extension in Laravel. 436834.4k1](/packages/clickbar-laravel-magellan)[simplestats-io/laravel-client Analytics for Laravel. Track visitors, registrations, and payments. Discover which channels actually drive revenue, not just traffic. Server-side, GDPR compliant, ad-blocker proof. 5019.3k](/packages/simplestats-io-laravel-client)[masterix21/laravel-licensing Laravel licensing package with polymorphic assignment to any model, activation keys, expirations/renewals, and seat control via LicenseUsage. Supports offline verification with public-key–signed tokens, a CLI to generate/rotate/revoke keys, and an extensible architecture via config and contracts. 1432.1k4](/packages/masterix21-laravel-licensing) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)