# Laravel Badge — Full Documentation

> Free, open-source dynamic SVG badge service that shows which Laravel versions a Packagist package supports. Embed a compatibility badge in any Laravel package README in seconds — no manual updates needed when you release new versions.

Hosted at https://laravel-badge.peterfox.me — built with Laravel, served via Laravel Octane.

## Why Laravel Badge exists

When you publish a Laravel package, one of the most common questions from users is: "Does this package support my version of Laravel?" Historically, package authors answered this by manually adding version ranges to their README, or by linking to the composer.json.

Laravel Badge automates this entirely. It reads the live composer requirements from Packagist, resolves which Laravel versions are satisfied by those constraints, and serves a dynamic SVG badge. When you release a new version of your package with updated constraints, the badge updates automatically within 24 hours — no README edit required.

## How to add a Laravel compatibility badge to your package README

Step 1: Find your package's Packagist vendor/package name (e.g. `spatie/laravel-permission`).

Step 2: Add this Markdown to your README.md:

```markdown
![Laravel Compatibility](https://laravel-badge.peterfox.me/badge/{vendor}/{package})
```

Step 3: The badge is live immediately. Example:

```markdown
![Laravel Compatibility](https://laravel-badge.peterfox.me/badge/spatie/laravel-permission)
```

## Badge URL format

```
GET https://laravel-badge.peterfox.me/badge/{vendor}/{package}
GET https://laravel-badge.peterfox.me/badge/{vendor}/{package}?style=flat
GET https://laravel-badge.peterfox.me/badge/{vendor}/{package}?style=for-the-badge
```

Parameters:
- `vendor` — the Packagist vendor name (e.g. `spatie`)
- `package` — the Packagist package name (e.g. `laravel-permission`)
- `style` — optional; one of `flat` or `for-the-badge` (default is the standard style with gradient)

## Badge styles

Three styles are available to match your README's aesthetic:

1. **Default** — rounded badge with subtle gradient, matches shields.io default style
2. **Flat** — no gradient, clean and modern
3. **For the Badge** — larger, bold, all-caps label

## How version detection works

Laravel Badge fetches package metadata from the Packagist API (`packagist.org/p2/{vendor}/{package}.json`) and inspects the `require` section of the latest stable release's `composer.json`. It then checks constraints on:

- `laravel/framework` — direct Laravel dependency
- `illuminate/*` — any individual Illuminate component (e.g. `illuminate/support`, `illuminate/console`)

It uses the `composer/semver` library to resolve these constraints against known Laravel major versions (6.x through the latest). Complex constraints like `^10.0 || ^11.0 || ^12.0` are fully supported.

## Custom version override

If your package's Packagist constraints don't accurately reflect supported Laravel versions (for example, if you test against versions not explicitly constrained), you can add a custom override to your `composer.json`:

```json
{
    "extra": {
        "laravel-badge": "^11.0 || ^12.0"
    }
}
```

When present, Laravel Badge uses this value instead of the detected framework constraints.

## Illuminate package support

Packages that depend on individual Illuminate components rather than the full `laravel/framework` are fully supported. If your `composer.json` requires `illuminate/support: ^11.0`, the badge will correctly display "Laravel 11.x" compatibility.

## Caching

- Badge responses are cached for 24 hours at the server level
- HTTP headers include `Cache-Control: public, max-age=86400` and `ETag` for browser-level caching
- `stale-while-revalidate=3600` allows browsers to show the cached badge while a fresh one is being fetched

## Frequently Asked Questions

**Q: Is this free?**
A: Yes. Laravel Badge is completely free and open-source (MIT license).

**Q: What if my package is not on Packagist?**
A: The badge only works for packages published on Packagist. Private packages or GitHub-only packages are not supported.

**Q: Does the badge update automatically?**
A: Yes. When you publish a new version to Packagist with updated composer constraints, the badge will reflect the change within 24 hours (one cache cycle).

**Q: Can I use this in GitHub README files?**
A: Yes. GitHub renders the SVG badge inline in Markdown. Copy the Markdown snippet from the preview page at https://laravel-badge.peterfox.me/preview and paste it into your README.

**Q: Does it support Laravel 6, 7, 8, 9, 10, 11, 12?**
A: Yes. All major Laravel versions from 6 through the current latest are supported.

**Q: What if the badge shows wrong versions?**
A: Use the `extra.laravel-badge` override in your composer.json to specify exact supported versions. See "Custom version override" above.

**Q: Are there different styles?**
A: Yes — default (with gradient), flat, and for-the-badge. Switch between them using the `?style=` query parameter or use the preview tool at https://laravel-badge.peterfox.me/preview.

**Q: Does it support illuminate/* packages?**
A: Yes. Packages that require individual `illuminate/*` components instead of `laravel/framework` are fully detected.

## Related tools and alternatives

- **shields.io** — general-purpose badge service; does not provide Laravel version detection
- **Packagist badges** — shows download counts, version numbers, license; not compatibility ranges
- **Laravel Badge** (this service) — specifically designed for Laravel version compatibility display

## Source code and contributing

Source: https://github.com/peterfox/laravel-badge

Built with PHP 8.5, Laravel 13, Laravel Octane (FrankenPHP), and Tailwind CSS v4.

Contributions are welcome. Before opening a pull request for anything beyond a small fix, please open an issue first.

## License

MIT — https://opensource.org/licenses/MIT

Created by Peter Fox — https://peterfox.me