Php Date Laravel Package

Technical Evaluation

Release Delta (v2.15.1)

• What changed: v2.15.1 is a pure revert of a behavior change shipped in v2.15.0. TimeTraveler::addMonthWithReference() now matches v2.14.1 arithmetic again: after $from is advanced by one month, the result is realigned onto the reference day-of-month.
• Why it matters to a TPM: this is not a cosmetic patch. It is a correctness-level semantic change to a public API inside a patch/minor version line, shipped and then reversed within days (#46 → #47). The net effect for consumers is favorable — v2.15.1 is behaviorally equivalent to v2.14.1 for this method — but it materially changes the risk profile of the package and the upgrade procedure.
• New information about the package: we now have concrete evidence of (a) a GitHub repository with an active, fast-turnaround maintainer, (b) a first-class TimeTraveler domain class performing reference-anchored calendar arithmetic, and (c) a test suite using PHPUnit #[DataProvider] attributes — i.e., PHP 8 attribute syntax and PHPUnit 10+, which implies a modern PHP floor and a real (not nominal) test suite. This upgrades the earlier "no visible repository / unknown coverage" concern.
• New information about the risk: the maintainer is willing to alter observable date arithmetic outside a major version. Treat semver as feature-scoped, not behavior-scoped for this package.

Architecture Fit

• Use Case Alignment (revised): the package is best understood not as a formatting/parsing helper but as a calendar-arithmetic library. addMonthWithReference() solves the classic bounded-month problem: advancing a date by n months while pinning to a reference day-of-month, with clamping at month end (Jan 31 → Feb 28/29). That is precisely the logic behind:
  • Subscription renewal and billing-cycle anchoring (signup on the 31st).
  • Payroll and fiscal-period rollovers.
  • Trial/notice-period expiration ("one month after the reference date").
  • Contract milestone scheduling.
• Laravel Synergy: Carbon's addMonth()/addMonthsNoOverflow() cover adjacent but not identical ground — Carbon has no first-class notion of a persisted reference day that must be re-applied after every advance. If our domain needs that anchor to remain stable across a chain of additions, this is genuine, non-trivial differentiation. If we only need single-step month addition, Carbon remains sufficient and this package is unwarranted coupling.
• Architectural Risk (raised): the value proposition is concentrated in behavioral semantics of a narrow set of methods. Behavioral semantics are exactly what this release just proved can move without a major bump. Coupling to it is only safe behind an internal adapter.

Integration Feasibility

• Dependency Graph: #[DataProvider] attributes indicate PHPUnit 10+ in dev requirements and PHP 8.1+ in practice. Re-confirm in composer.json: actual PHP floor, Carbon major constraint, and whether ext-intl or ext-calendar is a hard requirement. Verify it does not co-require a second date library we already depend on.
• Testing Overhead (now scoped, not open-ended): the burden is not "cover an unknown package" but "characterize addMonthWithReference() and its siblings across month-end, leap-year, and DST boundaries." Because upstream has already changed this behavior once, our tests must be golden/characterization tests, not merely coverage: assert exact output dates, not properties, for a matrix of (from-date, months, reference day) tuples. Port the upstream #[DataProvider] cases into our own suite so a future upstream revert or re-revert fails our build, not production.
• Configuration: no indication of new config files, service provider bindings, or env vars in this release. Assume library-style, container-agnostic usage until proven otherwise; wrap in a container binding ourselves anyway.

Technical Risk

• Behavioral drift across patch versions (elevated): v2.15.0 → v2.15.1 changed observable output for a public method with no major-version signal. Any future composer update is a potential silent recalculation of billing dates, renewal dates, or period boundaries. Mitigation: exact version pinning (2.15.1, not ^2.15) for anything on a money or compliance path, plus a mandatory changelog read before bumps.
• Orphaned-behavior risk for early adopters: teams that pulled v2.15.0 and adapted to or compensated for the new arithmetic now have code aligned to a semantic that no longer exists. This is the highest-severity item in this release, and it is invisible to composer update — it requires a code and knowledge audit.
• Ambiguity/clamping correctness (unresolved): the release note describes the realignment rule but not the clamp. Confirm and test: 31 Jan + 1 month; 31 Mar + 1 month; 29 Feb + 12 months; reference day 31 against a 30-day month; negative $months; $months = 0. These are the cases that produce wrong invoices.
• Performance: unchanged assessment — benchmark only if used in bulk (bulk renewal sweeps, queue workers). Calendar arithmetic is cheap; the risk is per-row object creation over large result sets.
• Security: low. Date arithmetic on trusted values; input-validation risk is upstream of this call.
• Maintenance responsiveness (improved): revert landed promptly with PR references, and tests were retained through the revert. That is a positive signal on engagement, but it cuts both ways: fast releases also mean fast semantic churn.

Key Questions

1. What is the maintainer's semver policy for behavioral changes? Specifically: can observable date arithmetic change in a patch release again, or will future changes to addMonthWithinReference-family methods require a major bump? Get this in writing (issue/PR) before committing to the dependency.
2. What is the exact clamping rule for reference days that exceed the target month's length, and does it match our finance/legal definition of "one month"?
3. Does our codebase contain any workaround for v2.15.0 semantics? Audit all call sites and any local date helpers written in the last release window.
4. What problem does this solve that Carbon::addMonthsNoOverflow() does not, given we must persist our own reference day either way?
5. Is v2.15.1 byte-for-byte behaviorally identical to v2.14.1 for all public methods, or only for addMonthWithReference()? Diff the two tags to be certain the revert was complete.
6. What is the transitive dependency and PHP floor, and is the package's Laravel/Laravel-adjacent support matrix stated anywhere?

Integration Approach

Stack Fit

• Positioning: treat the package as a narrow domain service ("reference-anchored month arithmetic"), not a general date layer. Keep Carbon as the default for parsing, formatting, storage, and transport; reserve this package for the anchor-preserving advance operation it uniquely provides.
• Adapter boundary (now mandatory, not optional): do not call TimeTraveler directly from models, jobs, or controllers. Introduce one internal class — e.g. App\Support\Billing\PeriodAdvancer — that exposes advance(DateTimeImmutable $from, int $months, int $referenceDay): DateTimeImmutable. This is the single seam where a revert, a future semantic change, or a full replacement by hand-rolled logic can be absorbed without a codebase-wide sweep.
• PHP/Laravel alignment: PHP 8.1+ and PHPUnit 10+ are implied by the attribute-based data providers. Confirm the package's supported Laravel range before adding it to a Laravel 11/12 application.
• Tooling: no evidence of Artisan commands or Eloquent hooks in this release; assume none and plan accordingly.

Migration Path

1. Freeze and inventory: pin every environment to an exact version. Search the codebase for addMonthWithReference, TimeTraveler, and any locally written month-arithmetic helpers introduced since v2.15.0.
2. Characterize first, adopt second: build the golden-case suite (month-end, leap year, negative months, zero months, DST-adjacent) against v2.14.1/v2.15.1 before wiring it into any feature. If the suite contradicts our business definition of "one month," stop — the decision is a business decision, not a library decision.
3. Single feature pilot: one renewal-date calculation in a non-customer-facing module, behind a feature flag comparing package output against Carbon output and logging divergences.
4. Expand by surface area, not by convenience: only after a full billing cycle's worth of divergence logs show zero unexplained deltas.
5. Retire the fallback: remove the comparison path and document the pinned version + rationale in an ADR.

Compatibility

• Version pinning: use "assoconnect/php-date": "2.15.1" for money/compliance paths. ^2.15 is not acceptable for this dependency given the observed patch-level behavior change. ~2.14.1 || 2.15.1 only if you have verified 2.14.1 and 2.15.1 are behaviorally identical on your cases.
• Laravel/PHP matrix: test on the current LTS and the next major; verify the package's own declared support range rather than assuming it.
• Database drivers: month arithmetic is typically computed in PHP, but if any helper feeds into query building or date columns, verify MySQL/PostgreSQL/SQLite parity for the clamped results.
• Testing toolchain: our test suite must be PHPUnit 10+ (or Pest on top of it) if we intend to reuse upstream #[DataProvider] cases verbatim.

Sequencing

1. Immediately (this release): audit for v2.15.0 dependency — anywhere we pinned 2.15.0 or wrote compensating logic, revert it now and regression-test.
2. This sprint: pin exact versions, read the full v2.14.1↔v2.15.0↔v2.15.1 diff, open the semver-policy question upstream.
3. Next: land the adapter class and the golden-case suite; no production call sites yet.
4. Then: feature-flagged pilot with divergence logging through one full cycle.
5. Ongoing: per-release changelog review as a standing gate in the dependency-update runbook — this package specifically.

Operational Impact

Maintenance

• Release-watch requirement (new): this package graduates to "read the changelog before every bump" status. Add its GitHub release feed to the on-call/TechOps review queue and require an explicit diff review for any release touching TimeTraveler.
• Semver posture: assume patch releases may carry behavioral change until the maintainer states otherwise. Encode that assumption in the dependency policy doc so future engineers don't apply default ^ constraints out of habit.
• Internal documentation: the ADR must capture why the package is used, the exact pinned version, the reference-day/clamping semantics we depend on, and the golden test file that encodes them. This is the artifact that makes the next revert a 30-minute change instead of a billing incident.
• Backward compatibility: our adapter, not the package, is our API. Nothing outside App\Support should know TimeTraveler exists.

Support

• Debugging: upstream is reachable (PRs #46/#47 give a working escalation path) — a meaningful improvement over the prior "no visible repo" assumption. Keep issue templates ready for date-arithmetic defects with (from-date, months, reference day, expected, actual).
• Onboarding: developers must learn the distinction between "advance a date" (Carbon) and "advance a date while preserving a reference day-of-month" (this package). The most common failure will be using the package where plain Carbon is correct, or vice versa, silently producing off-by-a-day period boundaries.
• Escalation path: define up front — behavioral discrepancy on a billing path is a P1, owned by the team that owns the adapter, not deferred upstream. Assume we may need to replace the calculation with in-house logic under time pressure.

Scaling

• Performance: unchanged and low risk, but profile bulk renewal sweeps and queue workers where the helper is called per-row. Prefer computing once and reusing rather than constructing objects in tight loops over large Eloquent result sets.
• Horizontal scaling: no evidence of static caches or mutable state in this release. Verify by inspecting TimeTraveler for class-level properties before running it in long-lived queue workers.
• Determinism under load: date arithmetic must not depend on the process timezone or on now(). Confirm the methods are pure functions of their arguments; non-determinism here would produce divergent renewal dates across servers — a hard-to-diagnose, high-cost failure.

Failure Modes

• Silent semantic reversal (primary): upgrading or downgrading produces valid-looking dates that are one day off at month boundaries. No exception, no log. Detection depends entirely on our golden tests; monitoring cannot see it. This is the dominant risk for this package and it is not a hypothetical — it just happened.
• Month-end clamping surprises: results differing from business expectations for the 29th–31st. Mitigation: business sign-off on a written table of example outputs, not a code review.
• Orphaned v2.15.0 workarounds: code written to compensate for a behavior that no longer exists, now double-compensating. Detection requires the audit in Key Question 3.
• Data corruption / rollback: if period boundaries were written to the database while on v2.15.0, a rollback of the dependency does not roll back the persisted dates. Enumerate affected rows and plan a recompute/idempotent backfill keyed on (source date, months, reference day) before reverting anything in production.

Ramp-Up

• Developer adoption: pair the adapter's introduction with a short written brief — "we use this for one thing, here is the one thing, here is the test file that defines it." Enforce via code review that direct TimeTraveler usage outside App\Support is rejected.
• Testing strategy: golden-case tests with #[DataProvider] covering month-end clamping, leap years, negative and zero month deltas, and chain-of-additions behavior. Add one test that asserts the pinned version's arithmetic explicitly, so a composer update breaking it fails CI with an obvious message pointing at the ADR.
• Release readiness: canary the pilot feature, keep the Carbon-based fallback path alive until a full cycle of divergence logs is clean, and add a one-line pre-bump checklist item: "Read the changelog for any release touching TimeTraveler."