Period Laravel Package

Product Decisions This Supports

• Feature scoping for time-window products: subscriptions and trials, billing cycles and proration, promotion validity, SLA/on-call windows, booking availability, retention policies, reporting/analytics date buckets, and scheduled feature flags.
• Build vs. buy: buy the interval algebra instead of maintaining custom date math. league/period provides immutable Period, Duration, and Datepoint value objects, named constructors, explicit boundary types (include/exclude start and end), intersection, merge, split, diff, contains, sequence operations, and ISO serialization.
• Roadmap de-risking: enables reliable half-open interval semantics ([start, end)) and DST-aware splitting—the changelog explicitly fixes DST-related split behavior—reducing edge-case defects in billing, reporting, and scheduling features.
• Use cases to prioritize: calculate the current billing period; test whether an event falls inside a promotion window; split a reporting range into days/weeks/months; compute overlapping availability; total durations across sequences; compare durations; serialize periods to ISO 8601/ISO 80000 for APIs.
• Shared product vocabulary: gives PM and engineering precise terms—period, duration, boundary, sequence—so acceptance criteria can state whether the end date is inclusive and how zero-duration periods behave. This reduces ambiguity in specs and QA cases.
• Framework fit: it is framework-agnostic, so Laravel can supply DateTimeInterface/Carbon inputs at the edges while domain services use explicit range logic. It does not couple domain code to Eloquent, Carbon, or the framework.

When to Consider This Package

• Consider it when the product has non-trivial time-range logic across multiple features, especially billing, subscriptions, scheduling, reporting, promotions, or availability.
• Consider it when boundary correctness and DST behavior matter and the team wants a small, documented, MIT-licensed library rather than bespoke date helpers scattered across services.
• Consider it when engineering already works with DateTimeInterface/DateTimeImmutable and wants immutable value objects, named constructors, and explicit boundary semantics without adopting a large calendar or recurrence framework.
• Consider it when you need set-like operations over periods: intersect, merge, split, diff, contains, sequence mapping, total duration, and ISO serialization.
• Look elsewhere if the core need is RRULE/iCalendar recurrence, complex civil-time scheduling, business calendars, or calendar UI rendering. This is interval algebra, not a scheduler.
• Look elsewhere if the team is standardized on Carbon/CarbonPeriod for simple ranges, or if range filtering can be pushed entirely to the database (for example PostgreSQL range types).
• Adoption watch-outs: PHP >= 8.1 is required; there is no Laravel-specific integration; and zero dependents means less ecosystem validation. Pin versions, wrap the package behind an internal interface, and spike real edge cases—DST, month-end, leap year, open/closed boundaries—before broad rollout.
• Skip it if the need is only one trivial “is this date between A and B” comparison; native comparison is clearer.

How to Pitch It (Stakeholders)

• Executives: This is a low-cost, MIT-licensed utility that de-risks time-based features. It replaces custom date math with a documented, tested API, reducing billing, reporting, and scheduling defects while speeding delivery. It is not a platform or vendor commitment—no license fees and no infrastructure change—and it can be isolated behind our own service boundary.
• Engineering: Adopt league/period as the domain primitive for interval logic in Laravel services and actions. Use immutable Period, Duration, and Datepoint objects; pass DateTimeInterface from Eloquent/Carbon at the edges; keep persistence and presentation out of the domain. Standardize on half-open [start, end) boundaries and document them in specs. Wrap the package in a thin internal adapter so it can be swapped later. Validate DST, month-end, leap-year, and boundary cases in a spike, pin the version, and add contract tests. Use it for intersections, merges, splits, contains, sequences, and ISO serialization instead of duplicating logic across teams.
• Product/engineering partnership: Use the package’s vocabulary in acceptance criteria—boundary inclusion, duration versus date interval, sequence totals—so requirements are unambiguous. Start with one high-value workflow, such as billing-period calculation or reporting buckets, measure defect reduction, then expand.