kachnitel/duration-bundle
A Laravel/PHP package for working with and formatting durations, helping you convert time values into readable strings and handle duration logic cleanly in your applications.
What this is. v0.0.1 of a small, focused duration-handling utility library. Surface area is narrow and well-bounded: a parsing/formatting service (DurationUtil), a Symfony form type (DurationType), a Twig extension (duration, toSeconds, hhmm filters), and DateInterval conversion helpers. This is a leaf dependency, not a platform component — it does not own persistence, transport, auth, or any cross-cutting concern.
Architecture fit. Low architectural weight. The core (DurationUtil + DateInterval conversion) appears framework-agnostic plain PHP, with Symfony Form and Twig as thin optional adapters. That is the right shape: the utility can be consumed by non-Symfony code, and the framework bindings are additive. For a Laravel codebase the fit is partial — the Twig extension and DurationType are dead weight, while the core service is usable directly. Expect to write a small Laravel-side wrapper (Blade directive / validation rule / cast) ourselves if we adopt.
Ecosystem mismatch — flag this first. The brief describes this as a "Laravel/PHP package," but the released contents are squarely Symfony-ecosystem (Symfony Form type, Twig filters). There is no Laravel service provider, facade, config publish, Blade directive, validation rule, or Eloquent cast in the release notes. Either (a) the package is Symfony-first and the "Laravel" framing is aspirational, or (b) Laravel bindings are planned but unshipped. This is the single most important thing to resolve before we plan around it.
Integration feasibility. Straightforward. Composer-installable, no infrastructure, no external services, no credentials, no schema. Integration effort is measured in hours, not sprints. The only real work is deciding where duration parsing/formatting belongs in our own domain and whether we allow the raw library types to leak across module boundaries.
Technical risk. Low-to-moderate, and almost entirely versioning risk rather than technical risk:
PT1H30M) if it is in scope, and ambiguous DateInterval month/year semantics (a "month" is not a fixed number of seconds). "Comprehensive unit tests" is claimed but we have not audited coverage of these edge cases.Key questions.
DurationUtil handle ISO 8601 durations, negative values, and durations exceeding 24h? What is the tested behavior?Stack fit. Partial. If our stack is Laravel, we consume the core service only and ignore the Symfony/Twig adapters. If we also run Symfony services (common in mixed PHP estates), the package covers both and the calculus improves considerably. Worth confirming which of our services would actually use it before standardizing.
Migration path. Greenfield adoption is trivial: composer require, instantiate the service, done. Replacing existing bespoke duration helpers is the more interesting case — we should inventory where we currently parse or format durations (API payloads, timesheet/reporting features, scheduled-job configs, UI inputs) and migrate call sites one at a time, keeping the old helper as a thin delegate to the new library during transition. Do not big-bang this for a utility of this size.
Compatibility. Two axes to verify rather than assume: PHP version floor (must be ≤ our oldest supported runtime) and framework version constraints (Symfony Form/Twig version ranges, if we use those adapters). Composer's constraint solver will surface conflicts fast, but confirm the PHP floor explicitly — pre-1.0 packages frequently target recent PHP only.
Sequencing.
Maintenance. Negligible runtime footprint — no daemon, no storage, no network calls, no config surface. The maintenance cost is dependency hygiene: tracking 0.x releases and reviewing changelogs for breaking changes, which is cheap for a library this small but non-zero because pre-1.0 packages break without ceremony.
Support. Depends entirely on provenance, which we do not yet know. Internal package: our problem, budget accordingly. Third-party single-maintainer: acceptable for a leaf utility, not acceptable for anything load-bearing. The presence of GitHub Actions CI and shipped docs/examples is a genuinely positive signal for a 0.0.1 — it suggests the maintainer intends this to be usable rather than a personal scratch library.
Scaling. No scaling concerns. Pure CPU, stateless, microsecond-scale operations. Parsing is the only non-trivial cost and it is not in any hot path we would plausibly put it in. If we ever parse durations per-request at high volume, memoize — but that is a hypothetical.
Failure modes. Worth enumerating because they are all silent data failures rather than crashes:
"1:30" could be 1h30m or 1m30s depending on convention; an ambiguous input coerced to the wrong unit propagates into billing, reporting, or scheduling with no error. Validate inputs at the boundary and assert against known-good fixtures in our own tests, not just theirs.HH:MM form has no unambiguous representation. Decide our convention (>24h stays as hours, or rolls to days) and enforce it in the wrapper.DateInterval month/year ambiguity. Converting to seconds requires an anchor date. Confirm the library's chosen semantics and make sure call sites that care supply an anchor.^0.0 resolution range can silently alter behavior. Pin exactly.Ramp-up. Very low. A developer reads the README and examples and is productive in under an hour; the API is small and idiomatic. Budget roughly half a day per engineer including the edge-case reading, plus the spike above. Documentation and examples shipping with 0.0.1 materially reduces this. No training, no runbooks, no on-call implications.
Bottom line for the TPM. Low-risk, low-cost, low-leverage. Approve a time-boxed spike and a single narrow adoption behind an internal wrapper; do not standardize on it or put it in a critical path until it reaches 1.0 with a stated BC policy and the Laravel-vs-Symfony positioning is clarified.
How can I help you explore Laravel packages today?