Poser Laravel Package

Getting Started

The package is a PHP badge renderer — it turns a subject/status/color triple into an SVG you can embed in a README, an admin panel, or serve from a route. It has no publicly listed repository, so the installed source is your source of truth. The names below follow the package's likely conventions; confirm each against vendor/badges/poser/src before committing to them.

Install and inspect

composer require badges/poser

Then, in order:

1. vendor/badges/poser/README.md — the canonical usage snippet and any config/env vars.
2. vendor/badges/poser/src/ — find the entry point (typically a Badge class, a factory, or a Badges service) and the renderer that emits SVG.
3. vendor/badges/poser/tests/ — the tests are the most reliable API documentation you'll get; they show exact constructor arguments, defaults, and edge cases.
4. composer.json inside the package — check the PHP constraint and whether it pulls a templating or HTTP dependency. With a 2026-05-28 release, verify it supports your PHP version before you plan around it.

First use case: render one badge to a string

use Badges\Poser\Badge;

$svg = Badge::make('build', 'passing', 'brightgreen')->render();

return response($svg, 200, ['Content-Type' => 'image/svg+xml']);

If the package exposes a facade or a container binding (check for a service provider in src/), resolve it from the container instead of static calls — that makes it swappable in tests. If there is no provider, register the renderer yourself in a small service provider so you're not newing it up in controllers.

The fastest way to validate the install is to dump $svg to a .svg file, open it in a browser, and confirm the text width and colors look right. Do this before wiring it into anything else — badge libraries frequently look correct as a string and wrong as an image because of text measurement.

Implementation Patterns

Treat badges as value objects, not views. Build the badge data in a service or action, then render at the edge. This keeps the badge logic testable without asserting on SVG strings:

final class BuildBadge
{
    public function __construct(private BadgeRenderer $renderer) {}

    public function svg(): string
    {
        $status = cache()->remember('badge.build', now()->addMinutes(10), function () {
            return $this->latestPipelineStatus(); // 'passing' | 'failing'
        });

        return $this->renderer->render(
            subject: 'build',
            status: $status,
            color: $status === 'passing' ? 'brightgreen' : 'red',
        );
    }
}

Serve badges from a dedicated route with real cache headers. Badges are read far more often than they change, and READMEs are fetched by crawlers and CI constantly.

Route::get('/badges/{badge}.svg', BadgeController::class)
    ->where('badge', '[a-z0-9\-]+')
    ->middleware('cache.headers:public;max_age=300;etag');

Set Content-Type: image/svg+xml explicitly (Laravel will otherwise guess text/plain or text/html for a string response) and add Cache-Control. Pair that with a short server-side cache on the underlying data, not on the SVG itself — you want the ETag to reflect data changes.

Inline in Blade when the badge is static or derived from page data. For a fixed badge (license, PHP version), render once at build time or cache the string in a view composer rather than calling the renderer per request. For a Blade component, keep it dumb:

{{-- resources/views/components/badge.blade.php --}}
{!! $svg !!}

Only use {!! !!} when the SVG is generated by the library from trusted inputs. See the gotchas — this is the single most common way badge code becomes an XSS vector.

Generate-at-build for repo badges. The most robust pattern for README badges is to render during CI and commit or upload the artifact, rather than depending on your app being up:

// artisan command run in the pipeline
$svg = $renderer->render('coverage', $coverage.'%', $coverage > 80 ? 'green' : 'orange');
File::put(base_path('artifacts/coverage.svg'), $svg);

This sidesteps uptime, auth, and rate-limit problems entirely and makes the badge reproducible from the commit that produced it.

Wrap the renderer behind your own interface. Even if the package's API is pleasant, the lack of a public repository is a bus-factor risk. A one-method interface (render(string $subject, string $status, string $color): string) means swapping renderers later is a container binding, not a find-and-replace across the codebase.

Gotchas and Tips

Escape everything that reaches the SVG. SVG is XML, and it is served as a document. Any user-controlled string interpolated into the badge text is an injection point — an &, <, or a crafted <script> will either corrupt the image or, if served from your origin, execute. If the library does not escape for you, verify it with a status of a<b&c before you ship. Never pass request input directly into a badge; whitelist statuses and colors.

Text width is the classic failure. SVG has no reliable server-side font metrics, so badge libraries either hardcode a character width or use a monospace assumption. Long statuses get clipped or leave a gap. Keep subject and status short (single words, v1.2.3, 87%), and check a long value visually before release.

Always send the right Content-Type. A badge served as text/html renders as nothing in <img> on GitHub, and some browsers will sniff and refuse it. Also strip any BOM or trailing whitespace — a single stray newline before <?xml breaks strict SVG parsers.

Cache invalidation is manual unless you build it. If you cache the SVG keyed by badge name, a data change won't show until expiry. Key the cache on the underlying value ("badge.build.{$status}") so a status change is a cache miss, or emit an ETag derived from the data.

Version pin tightly. With a recent release and no public repo, a minor bump can change rendering. Pin to a patch range in composer.json and add a snapshot test that asserts the SVG output for a known input, so an upgrade that changes geometry fails loudly in CI rather than silently altering your README.

Check for a config publish step. If the package ships a config file, publish it (php artisan vendor:publish) and commit it — otherwise defaults can shift between releases and your badges subtly change color or template.

Look for the extension points before forking. Most badge libraries expose a template or renderer you can override — a custom template path, a setTemplate() call, or a swappable renderer class. Check src/ for these first. Overriding a template is far cheaper than patching vendor code, and it's the right place to add logos, adjust padding, or match your brand colors.

Debug by dumping the raw string, not the rendered page. When a badge looks wrong in the browser, dd($svg) first. Nine times out of ten the issue is in the generated markup (unclosed tag, missing xmlns, wrong viewBox) rather than CSS or the response layer.

Set expectations on maintenance. MIT licensed and 148 stars, with no discoverable repository, means you should assume you may be the maintainer of last resort. Budget for reading the source, keep the renderer behind your own interface, and don't build critical-path features (auth-gated dashboards, live metrics) on top of it.