Php Badge Laravel Package

Getting Started

The package is a single, small SVG badge generator — think a self-hosted, PHP-native slice of shields.io. There is no service, no config file, no database: you feed it a label, a message, and a colour, and it hands back an SVG string.

Install (pin it — the package is archived):

composer require yakeing/php_badge:^1.0

Because the last release was January 2020 and the repo is archived, commit composer.lock and treat the version as frozen. Don't rely on composer update picking up fixes that will never come.

Where to look first:

1. src/ — the whole library is essentially one Badge class. Read it end-to-end before writing any glue code; it's faster than trusting the README.
2. composer.json — confirm the PSR-4 namespace (Yakeing\PhpBadge in most releases) and the minimum PHP constraint.
3. Any examples/ or demo/ folder in the repo — the author's own usage is the de-facto documentation.

First use case — a live README badge endpoint:

// public/badge.php
require __DIR__ . '/../vendor/autoload.php';

use Yakeing\PhpBadge\Badge;

$badge = new Badge('build', 'passing', 'green'); // verify arg order in src/Badge.php

header('Content-Type: image/svg+xml; charset=utf-8');
header('Cache-Control: public, max-age=300');
echo $badge->render();

Then in your README:

![build](https://your-app.test/badge.php)

That's the 5-minute win. Everything below is about doing it without regretting it six months later.

Implementation Patterns

1. Controller route instead of a raw PHP file (Laravel).

// routes/web.php
Route::get('/badge/{status}', function (string $status) {
    $map = [
        'passing' => 'green',
        'failing' => 'red',
        'unknown' => 'lightgrey',
    ];

    abort_unless(isset($map[$status]), 404);

    $svg = (new \Yakeing\PhpBadge\Badge('tests', $status, $map[$status]))->render();

    return response($svg, 200, [
        'Content-Type'  => 'image/svg+xml; charset=utf-8',
        'Cache-Control' => 'public, max-age=60',
    ]);
})->name('badge.tests');

Keep the label/colour vocabulary in a single map. Badges are read by humans skimming a README, so the set of statuses should be small and stable — passing / failing / unknown beats ten bespoke strings.

2. Build-time generation for static docs. If the badge content only changes on deploy (coverage %, version number), don't serve it dynamically at all — render it in a Composer script or CI step and write the file:

file_put_contents(
    __DIR__ . '/docs/badges/coverage.svg',
    (new Badge('coverage', $percent . '%', $percent >= 80 ? 'green' : 'orange'))->render()
);

This sidesteps the whole question of whether the archived package behaves correctly on your PHP version at request time; you find out once, in CI, instead of in production.

3. Data-driven badges. The natural Laravel integration is pulling the message from the same place your dashboard does:

$count = Cache::remember('badge.open_issues', 300, fn () => Issue::whereNull('closed_at')->count());

$svg = (new Badge('open issues', (string) $count, $count > 50 ? 'red' : 'green'))->render();

Always wrap the query in Cache::remember. A badge embedded in a GitHub README is fetched on every page view by every visitor, and GitHub's image proxy will hammer that endpoint.

4. CI integration. The most valuable use of this package is closing the loop: have your pipeline compute a result, then commit or publish the badge. A php artisan badge:coverage artisan command that reads coverage.xml, regenerates docs/badges/coverage.svg, and lets the CI bot commit it gives you a badge that never lies — unlike a live endpoint pointed at a database that may itself be down.

5. Composition with the README. Because the output is plain SVG, you can inline it into HTML for control over size and alignment:

<img src="/badges/coverage.svg" alt="coverage" height="20">

Set height explicitly. SVG badges inlined without a height attribute will render at whatever the intrinsic dimensions are and look mismatched next to neighbours generated by a different tool.

Gotchas and Tips

The package is archived — budget for that. No security patches, no PHP 8.x compatibility work, no Composer 2 fixes. Run the test suite (such as it is) against your target PHP version on day one. If it emits deprecation warnings on PHP 8.2+, either live with them behind a error_reporting scope or vendor the class into your own codebase — it's small enough that forking is genuinely reasonable.

MPL-2.0 is file-level copyleft. You can use it in a closed-source Laravel app freely, and you can combine it with proprietary files. But if you modify src/Badge.php, you must make that modified file's source available. The clean workaround: don't edit the package. Subclass it, or wrap it in your own service class — new files you write are yours.

Escape the label and message yourself. Badge text goes into SVG <text> nodes, which are XML. A label containing &, <, or " will either corrupt the SVG or, if the library doesn't escape it, inject markup. Since input here often comes from a database or a user-supplied project name, wrap dynamic values:

$safe = fn (string $s) => htmlspecialchars($s, ENT_XML1 | ENT_QUOTES, 'UTF-8');
new Badge($safe($label), $safe($message), $color);

Check whether the library already does this before double-escaping — read the class.

Text width is the usual cosmetic failure. Static SVG badge generators typically estimate character width rather than measuring fonts (there's no font engine in PHP). Long labels — continuous-integration — will either overflow the rounded rectangle or get clipped. Keep labels under ~15 characters, and eyeball every new badge in a browser rather than trusting the API call succeeded.

Colours: hex over names. Named colours (green, red) resolve differently across badge implementations and may not match the shields.io palette your other badges use. Pass hex (#4c1, #e05d44) so a mixed badge row looks uniform.

Cache headers are not optional. Without Cache-Control, every README view hits your endpoint. If the badge reflects a live metric, a 60–300 second max-age is the right trade; if it reflects a deploy artifact, generate it statically (pattern 2 above) and skip the endpoint entirely.

Extension points are thin, and that's fine. The realistic options are: (a) subclass the badge class and override the render method, (b) wrap it in a BadgeService that owns escaping, caching and the colour map, or (c) skip the dependency and write ~15 lines of SVG yourself. For anything beyond "label + message + colour" — logos, two-tone gradients, custom fonts — option (c) is usually less work than fighting an unmaintained library, and you keep control of the escaping.

Have an exit plan. For a public-facing README, a live shields.io URL is more reliable than a self-hosted badge endpoint, and it costs you nothing. Use this package where self-hosting is the point — internal dashboards, air-gapped CI, or generating badge files at build time — and keep the code path that produces the SVG isolated in one class so swapping it out is a one-file change.