- What is league/period used for in PHP applications?
- League Period is a framework-agnostic time range API for PHP. It provides immutable Interval and Bounds value objects plus named constructors for comparing, manipulating, and composing time ranges. Common uses include scheduling, booking engines, subscription or access windows, billing periods, reporting filters, and query scopes.
- How do I install league/period in a Laravel app?
- Install it with Composer using composer require league/period. The package uses PSR-4 autoloading and does not require a Laravel service provider or configuration file. You can use its classes directly in models, DTOs, actions, jobs, and query scopes.
- Does league/period work with Laravel?
- Yes. League Period is framework-agnostic, so it works in Laravel without coupling to the framework. It fits naturally in Laravel applications for DTOs, domain services, Eloquent query scopes, validation, scheduled jobs, and billing or entitlement logic. There is no Laravel-specific package wrapper required.
- What PHP version does league/period require?
- The README lists PHP 8.1 or higher, but the 5.4.0 release drops PHP 8.1 support and effectively moves the floor to PHP 8.2 or higher. Projects still on PHP 8.1 must stay on league/period 5.3.3 or earlier. Laravel 11 and newer already require PHP 8.2+, so they are unaffected by the 5.4.0 floor.
- What are Interval and Bounds in league/period?
- Interval and Bounds are immutable value objects used to represent time ranges and range boundaries. They expose named constructors that make common range creation and comparison tasks explicit and predictable. The immutable design helps avoid side effects in domain logic, DTOs, and Laravel service layers.
- What changed in league/period 5.4.0 with Duration support?
- Version 5.4.0 adds Time Duration support so periods can be composed with durations for models such as trial windows, SLA clocks, and retention cutoffs. It also fixes inconsistent Duration named-constructor behavior, meaning results can differ from 5.3.x. Treat the new Duration surface as opt-in until validated and re-test any code that depends on duration boundaries.
- Can league/period replace Carbon in Laravel?
- It is not a drop-in replacement for Carbon. Carbon is strong for date and time instances, formatting, and general date manipulation, while League Period focuses on immutable time ranges and range operations. Many Laravel applications use both together, keeping Carbon for date handling and Period for interval logic.
- How does league/period handle timezones and daylight saving time?
- League Period works with timezone-aware date and time boundaries. Complex cases such as daylight saving transitions, recurring intervals, and duration arithmetic across DST still require careful application-level logic and tests. You should validate boundary behavior for your specific scheduling, billing, or reporting rules.
- How should I test league/period in a Laravel application?
- Write unit tests around range boundaries, invalid intervals, timezone shifts, and Duration named constructors where used. The package itself ships with a PHPUnit test suite, PHPStan analysis, and PHP CS Fixer checks, runnable via composer test. In Laravel, add feature tests for any Eloquent scopes or job windows that depend on Period.
- Is league/period safe for production and how should I pin it?
- League Period is battle-tested, actively maintained, documented, and used in production by many PHP projects. Pin ^5.3.3 deliberately if you still need PHP 8.1, or move to ^5.4 and accept the PHP 8.2 requirement. Because Duration behavior changed in 5.4.0, diff-test duration-producing code paths before upgrading.