Duration Bundle Laravel Package

Product Decisions This Supports

• Build vs. buy for duration handling. Duration parsing/formatting is a deceptively fiddly domain (ambiguous HH:MM vs MM:SS, mixed human-readable input, negative/zero edge cases, seconds overflow at 60, DateInterval interop). This package is a credible "buy" — or rather "adopt" — answer to a recurring ticket class, letting you redirect engineering time toward differentiators.
• Feature scoping for time-tracking, scheduling, media, or billing modules. Any roadmap item that surfaces elapsed time to users (timer displays, log entries, invoice line items, podcast/video runtime, SLA countdowns) can lean on this instead of bespoke formatters per feature.
• UI consistency as a product decision. A single canonical duration representation (hhmm, seconds, human-readable) plus Twig filters lets design settle on one display convention rather than each squad inventing its own. That is a product-quality lever, not just a code-quality one.
• Input flexibility as a UX decision. Support for multiple input formats means the product can accept what users naturally type ("1h 30m", "01:30", "5400") without a custom validation layer per surface.
• Roadmap timing signal. v0.0.1 with CI and docs is a healthy foundation but signals pre-stability; treat this as a candidate for low-risk, internal, non-critical-path surfaces now, and a re-evaluation candidate once it reaches 1.0.

When to Consider This Package

Adopt when:

• The stack is genuinely Symfony-oriented — the Twig extension and DurationType form type are Symfony form/Twig ecosystem artifacts, not Laravel-native. If this is truly a Laravel application, expect integration work: Blade directives instead of Twig filters, and adapters around the form type. Confirm the framework fit before committing; the framing as a "Laravel/PHP package" does not match the shipped surface.
• Duration handling already appears in two or more places in your codebase, or is on the near-term roadmap.
• The need is formatting/parsing only — you want a small, focused utility, not a scheduling or calendar engine.
• You can tolerate a 0.0.x API surface: pin the version, wrap the calls behind your own thin service or facade, and avoid letting DurationUtil leak into domain code.

Look elsewhere when:

• The consuming team is Laravel-first and unwilling to absorb Twig/Symfony-forms friction — a Blade-native helper plus Carbon's diffForHumans/interval formatting may cover 80% of the need with zero new dependency.
• You need timezone semantics, business-calendar logic, working-hours arithmetic, or locale-aware duration localization. This package does not claim those, and bolting them on defeats the purpose.
• The surface is revenue-critical (e.g. billing calculations) and you require a stable, versioned contract with a maintenance guarantee. A single-maintainer 0.0.1 is a supply-chain and longevity risk for that class of code.
• Requirements are so narrow (one format, one screen) that a 20-line helper is cheaper than a dependency plus its review overhead.

How to Pitch It (Stakeholders)

To executives: This is a small, low-cost dependency that removes a recurring category of defects — durations displayed or parsed inconsistently across screens. It is not a platform bet. Value is modest but real: faster delivery on time-related features and fewer user-facing inconsistencies. Risk is contained if we pin the version and isolate it behind our own interface, so we can swap it out cheaply.

To engineering: Scope it honestly — despite the "Laravel/PHP" framing, this ships Symfony forms and Twig, so Laravel teams are looking at adapter work, not drop-in use. What it does give us is a tested DurationUtil covering multi-format parsing, toSeconds, hhmm output, and DateInterval conversion, with CI and real docs — better than rolling our own for the third time. Recommendation: adopt behind a thin internal wrapper, limit to non-critical paths, and revisit at 1.0 or at the first sign of maintenance stall.