Weave Code
Date Time Laravel Package
php-standard-library/date-time
Immutable, timezone-aware DateTime types for PHP. Provides Duration, Period, and Interval helpers for safer date/time arithmetic and ranges, designed as a standard-library style package with clear docs and contribution links.
Immutable, timezone-aware date and time types with Duration, Period, and Interval
Frequently asked questions about Date Time
- How does this package differ from Carbon in Laravel?
- Unlike Carbon, this package enforces immutability, preventing accidental state changes in critical paths like financial transactions or audit logs. It also handles timezones consistently by design, avoiding Carbon’s mutable defaults. For example, `Period::years(7)` ensures GDPR-compliance deadlines without risking modification.
- Can I use this alongside Carbon in Laravel without conflicts?
- Yes, but intentionally. The package avoids Carbon’s quirks (e.g., `Carbon::parse()`) and works as a low-coupling alternative. Use wrapper adapters like `CarbonAdapter::toDateTime($carbon)` to bridge legacy code gradually. Start with new features (e.g., API responses) before full migration.
- What Laravel versions and PHP requirements does it support?
- The package targets **PHP 8.1+** (leveraging named arguments, union types) and aligns with **Laravel 9+**, which embraces immutable data structures. It won’t work on older Laravel versions without polyfills, but the immutable design fits Laravel’s modern typing trends.
- How do I handle database timestamps with this package?
- Explicit casting is required—e.g., `DateTime::fromTimestamp($record->created_at)`. This forces consistency but may need Eloquent model adjustments. For migrations, use `DateTime::fromDateString($timestamp)` or custom accessors to avoid mixing Carbon and the new types.
- Will this impact performance in high-traffic Laravel apps?
- Immutable objects introduce memory overhead, especially for bulk operations (e.g., queue workers). Benchmark against Carbon for your workload, but the package optimizes for clarity over micro-optimizations. For high-frequency systems, consider caching `Duration`/`Period` objects or using adapters for legacy code.
- How do I test time-sensitive logic with this package?
- Use custom factories (e.g., `DateTime::factory()->create()`) in PestPHP or Laravel’s testing tools. Mock timezones with `DateTime::setTimezone('America/New_York')` and validate arithmetic via `assertEquals($expectedDuration, $actual->diff($other))`. Avoid `Carbon::setTestNow()`—this package requires explicit time control.
- Are there Laravel-specific integrations (e.g., Eloquent, Horizon)?
- No official integrations exist yet, but the package is designed for low-coupling. For Eloquent, create a `DateTimeAttribute` or use accessors. For Horizon, wrap `DateTime` in a custom job trait. The package prioritizes core functionality; community-driven add-ons may emerge over time.
- How do I migrate from Carbon to this package in a large codebase?
- Start with opt-in adoption: Use the package for new features (e.g., API responses) and mark Carbon usage with `@deprecated` annotations. Gradually refactor high-risk areas (e.g., billing logic) using wrapper classes. Tools like PHPStan or Rector can automate type checks during migration.
- Does this package handle Daylight Saving Time (DST) transitions correctly?
- Yes, the package uses PHP’s `DateTime` under the hood, which accounts for DST transitions via the IANA timezone database. Test edge cases like `America/New_York` transitions with `DateTime::createFromFormat()` and validate against known DST boundaries (e.g., March 12, 2023, at 2 AM).
- What alternatives exist for immutable DateTime in Laravel?
- Alternatives include **Spatie’s Carbon Immutable** (Carbon fork) or **Ramsey’s UUID/DateTime** (for strict typing). However, this package stands out by combining **Duration/Period/Interval** helpers with Laravel synergy (e.g., queue delays, timezone-aware events). Choose it if you need domain-specific types like `Period::months(1)` for subscriptions.
Weaver
How can I help you explore Laravel packages today?