Statamic Ai Labels Laravel Package

Getting Started

This package composites a badge onto an image (product thumbnails, avatars, status overlays). The whole public surface is small: one renderer, one config file, one new knob (padding).

1. composer require <vendor>/<package> — pin the minor ("^0.1.2") while the package is pre-1.0; config keys are still moving.
2. Publish the config: php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" and confirm config/<package>.php appears. Check the service provider's mergeConfigFrom too — if a key is missing from your published file, the package default wins silently.
3. Look first at: the config file (only 1–2 keys matter), then the class that does the compositing (usually src/BadgeRenderer.php or similar) to see whether it uses GD, Imagick, or Intervention Image. That determines what formats and alpha behaviour you actually get.
4. First use case — a sale badge on a 400px-wide product image:

// config/badge.php
'padding' => 0.25, // fraction of badge width, not pixels

$path = Badge::make(storage_path('app/products/1.jpg'))
    ->badge(resource_path('img/sale.png'))
    ->save(storage_path('app/products/1-badged.jpg'));

With a badge sized at 25% of the image width (100px on a 400px image), 0.25 gives a 25px gap from the edge. That is the 0.1.0 spacing, so existing visual baselines should match — if you are coming from 0.1.1, expect a shift and re-check your snapshots.

Implementation Patterns

• Design tokens over magic numbers. Keep the value in config/badge.php and drive it from an env var (BADGE_PADDING=0.25) so a designer can tune the gap via config cache rebuild rather than a code change. Because it is a ratio, the same value works for every image size — that is the point of the change.
• Per-context override. Small thumbnails want flush or near-flush badges; hero images want breathing room. Resolve the value at call time rather than hardcoding in config:

$padding = $context === 'thumbnail' ? 0.1 : config('badge.padding');

• Derive from your layout grid. If your design system says "badges sit 8px from the edge at 32px badge size", express that as 8 / 32 = 0.25 in a comment next to the config line. Future-you will not remember it is a fraction.
• Cache on the full input fingerprint. Image path + badge path + mtime + config('badge.padding'). Adding a config value that affects pixels but not the cache key is the classic cause of "it didn't change" bug reports.
• Move rendering off the request path. Badge compositing is CPU-bound; do it in a queued job on upload or on a BadgeRequested event, then serve the derived file from storage/CDN. Never render on a hot listing page.
• Test with visual diffs, not assertions. Assert output dimensions and mime type in PHPUnit, and keep a small golden-image snapshot in the repo so padding regressions across releases are caught.

Gotchas and Tips

• It's a fraction of badge width, not pixels. Raising badge size silently raises the gap. If a designer says "the gap is too big on the large variant", the fix may be the badge size, not padding.
• 0 is genuinely flush. Flush means badge pixels touch the image edge; with rounded badge corners or anti-aliased edges you may see a sliver of background or a clipped stroke. 0.02–0.05 is usually the real "flush" you want.
• No upper bound documented. Values above ~0.5 push the badge inward toward the centre, and with corner placement plus a large badge you can overflow or negative-offset. Clamp it: max(0, min(0.5, $padding)).
• Config cache. In production with config:cache, changing .env alone does nothing until you php artisan config:clear. Combined with the cache-key issue above, this produces phantom "padding ignored" reports.
• Upgrade from 0.1.1 → 0.1.2 is not visually neutral. The notes say 0.25 restores 0.1.0 spacing, which implies 0.1.1 used something else. Re-generate derived images after upgrading; nothing in the package will invalidate your stored outputs.
• Debugging tip. Log the computed pixel gap (badgeWidth * padding) once per render at debug level. It converts a float config into a number you can eyeball against the mockup in seconds.
• Pre-1.0 churn. A newly introduced config key in a 0.1.x release is a signal the config schema is still in flux. Keep the config wrapped behind one of your own classes (BadgeSettings::padding()) so a future rename or default change is a one-file edit.
• Extension point. If padding turns out to be per-corner (top-left vs bottom-right badges), the renderer's config resolution is the place to add it — not a fork. Watch for that in 0.1.3+.