Statamic Ai Labels Laravel Package

Product Decisions This Supports

• Branded image output at scale. The package governs how a badge is composited onto an image, including its inset from the edge. That makes it a candidate for any product surface where user- or machine-generated imagery must carry a consistent brand mark: marketplace listings, profile avatars, certificates, share cards, receipts, and exported reports.
• Build vs. buy for image compositing. The decision is rarely "can we draw a rectangle on an image" — it is whether to own a small server-side compositing dependency or push the work to a rendering service/CDN. This package is the low-infrastructure end of that spectrum: no external service, no per-image vendor cost, work happens in the existing PHP request or queue worker.
• Design-token consistency. The padding value is expressed as a fraction of badge width rather than absolute pixels, which means a single spacing rule survives badge resizing across the four or five image aspect ratios a catalog typically has. That lets design specify one number instead of a matrix of per-format offsets, and reduces the class of "badge looks cramped on square thumbnails" bug reports.
• Roadmap sequencing for the media pipeline. v0.1.2 is evidence the package is being iterated on layout control rather than core correctness. If visual polish is on the roadmap but image correctness (format, color profile, alpha handling) is not yet validated, this is a supporting dependency, not a load-bearing one.
• Configuration surface as a product contract. The 0.25 default explicitly restores 0.1.0 spacing, so existing output is unchanged on upgrade. That is a deliberate compatibility choice and a signal the maintainer treats rendered output as something downstream products depend on — relevant when deciding whether to wrap this package behind an internal service boundary.

When to Consider This Package

Consider it when:

• You are on Laravel/PHP and the badge requirement is genuinely bounded: one overlay, positioned at an edge, sized relative to the image or badge, with configurable inset. The padding option covers the edge-gap dimension; that is the whole of what this release says about layout.
• You want the compositing to happen in-process, with no new network hop, vendor account, or asset-hosting contract.
• You need the badge to remain visually stable across image sizes, and a width-relative fraction (0.25 default, 0 for flush) is a better fit than fixed pixels.
• You are early enough in the feature that a pre-1.0 dependency is tolerable, and you can pin the version and absorb occasional minor-version changes.

Look elsewhere when:

• Rich composition is required. Multiple overlapping overlays, rotation, drop shadows, text wrapping, or vector layers are outside what a single padding knob implies. At that point you want Intervention Image or a full rendering service, not a badge helper.
• Stability guarantees matter more than convenience. At 0.x, minor versions can change behavior. If the output is a contractual artifact (regulatory labeling, immutable receipts), either pin hard and test pixel output, or build the composite in a pipeline you control.
• Rendering must happen at the edge. If image variants are generated by a CDN or transform service, doing this in PHP duplicates a capability you already pay for, and the two will drift.
• You need accessibility or contrast guarantees. A spacing config says nothing about badge legibility over arbitrary source imagery; that still needs contrast sampling or a scrim, which this release does not address.

How to Pitch It (Stakeholders)

To executives: This is a small, low-cost dependency that standardizes how our brand mark appears on generated images, server-side, using infrastructure we already run. The new release adds one configurable spacing value and explicitly preserves existing visual output — no change to what customers see today, no migration, no vendor commitment. The strategic value is consistency at scale: one number in config instead of per-format design specs, which reduces back-and-forth between design and engineering and removes a recurring class of visual defects. It is not a platform bet; it is a cheap, reversible way to keep branded output uniform while we decide whether image generation deserves real investment.

To engineering: v0.1.2 adds a padding config — the gap between badge and image edge, as a fraction of badge width. Default 0.25 reproduces 0.1.0 behavior exactly; 0 gives a flush badge. It is additive and backward-compatible, so upgrading should be a no-op visually; verify with a snapshot test on a handful of representative aspect ratios before trusting that. Because we are pre-1.0, pin the constraint and treat the rendered output as the contract we test against, not the config API. If badge layout starts needing more than an inset — multiple layers, text, contrast handling — that is the signal to stop extending this and move to Intervention or a service, rather than accumulating configuration here.