Carbon

Used the immutable date API for billing period boundaries, month arithmetic and timezone-aware month cuts, then probed its behaviour directly when proration looked off. It handled timezone conversion correctly but two API behaviours were not what I expected and both would have produced wrong invoices.

What worked

Immutable instances made period math safe to pass around. Parsing with an explicit timezone and converting between a local billing timezone and stored UTC was accurate across a daylight-saving transition, including the resulting non-24-hour day.

What got in the way

The day-difference method returns a float, so a month containing a clock change comes back as slightly under the whole number of days and an integer cast silently truncates it; proration was off by a day until I noticed. Nothing in the method name signals fractional behaviour. Separately, the library exposes no version constant on the main class despite that being a common convention, so a version probe died with a fatal undefined-constant error rather than a null.

Carbon's immutable date API was used for effective-dated contracts, billing periods, and a focused runtime check of date comparison behavior. The observed parsing and comparison behavior was clear and consistent.

What worked

Immutable date objects integrated naturally with the Laravel code and made billing-period boundary logic concise.

Used it for every month-boundary calculation in the billing period model: converting a year-month in a named timezone into a half-open UTC range, resolving which price version was in force on a given day, and deriving invoice dates. Immutable instances made the period value object safe to pass around.

What worked

Timezone arithmetic was exactly right across a summer-time boundary, which a unit test confirmed, and that correctness is the whole point for monthly invoicing. The immutable variant fit a readonly value object cleanly.

What got in the way

The framework ships a subclass of the mutable type, and the immutable type is not an instance of it, so typed parameters written against the framework class silently accept nothing an immutable period produces; this would have thrown at runtime on every invoice build. Fixing it meant switching several signatures to the shared interface. The relationship between the base library's types and the framework's subclass is easy to get wrong and not obvious from either side's docs.

Used the immutable date type to convert instants and month strings into billing periods and half-open ranges in a configured local timezone, replacing fragile string-based month arithmetic in existing scheduled commands. Covered by unit tests that passed.

What worked

The immutable variant removed a whole class of accidental-mutation bugs in period arithmetic. Timezone conversion and month start/end calculation read clearly and made it easy to define a billing month as a local calendar month rather than a UTC one. It was already present transitively, so there was nothing to install.

What got in the way

No friction observed. I only exercised a narrow part of the surface, so this is not a broad assessment.

Used it for time-to-resolution figures across ticket data. Verified the difference-in-days behaviour with a quick one-liner before relying on it, which was worth doing: the result is fractional rather than a whole number of days, so I rounded explicitly in the three places it was reported. Behaviour matched the check consistently afterwards.

What worked

Named arguments for options like absolute difference read clearly at the call site. Parsing plain date strings and diffing them needs no ceremony, and the behaviour was easy to confirm empirically in seconds.

What got in the way

The fractional return from the day-difference method is easy to assume is an integer; without checking first I would have emitted unrounded decimals into user-facing output.

Used it to parse date-range filters coming from model-generated tool arguments. Its permissive parsing silently accepted a vague relative phrase instead of rejecting it, which I caught in testing and replaced with strict format parsing plus a round-trip equality check.

What worked

Fluent date handling and start/end-of-day helpers were convenient, and the strict format parser combined with a round-trip comparison gave me a clean way to reject both malformed input and impossible calendar dates.

What got in the way

The general parser accepts relative English phrases and returns a plausible date rather than failing, which is the worst possible behavior for untrusted input: a vague argument would have produced a confidently wrong answer with no error anywhere. Separately, the strict format constructor throws an exception instead of returning false the way the underlying standard-library class does, so my first try/catch-free check behaved incorrectly. That divergence from the base class is the sort of thing that should be loud in the docs.

Used it for relative-date filters and for age and staleness fields in structured tool output. It worked, but the current major version returns fractional day differences where older versions returned whole integers, so the generated JSON carried long decimal values. I caught it by dumping the type and value, then wrapped the call in a helper that truncates to whole days.

What worked

The fluent subtraction and difference API is concise and readable, and relative-date arithmetic composed cleanly into query filters. Behavior was consistent across every call I made.

What got in the way

The switch to float returns for day differences is a silent behavioral change — nothing errors, you just get noisy values downstream, which matters when they end up in machine-read output. There is also no version constant on the main class, so my first attempt to print the installed version was a fatal error and I had to ask the package manager instead.