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 applications?
- This package enforces immutability and stricter typing, reducing side effects in stateful operations like caching or event dispatching. Carbon remains mutable, while this library’s `DateTimeImmutable` alternatives prevent accidental modifications. Use it for critical paths like billing cycles or job scheduling where precision matters.
- Can I use this alongside Carbon in the same Laravel project?
- Yes, but avoid mixing them to prevent inconsistencies. Start by replacing Carbon in new features (e.g., API responses, validation) and use wrapper classes (e.g., `CarbonAdapter`) to bridge legacy code. Static analysis tools like PHPStan can help audit mixed usage.
- What Laravel versions and PHP requirements does this package support?
- The package targets PHP 8.1+ and aligns with Laravel 9+’s stricter typing and immutable data trends. It won’t conflict with Laravel core but requires explicit casting for database interactions (e.g., `DateTime::fromTimestamp($record->created_at)`).
- How do I migrate from Carbon to this package in an existing Laravel app?
- Phase 1: Replace Carbon in new features using type hints (e.g., `function handle(Duration $duration)`). Phase 2: Gradually refactor existing code with wrapper classes or static analysis (PHPStan/Rector) to flag Carbon usages. Use feature flags for opt-in adoption.
- Does this package handle timezone-aware operations for global Laravel apps?
- Yes, it’s designed for timezone awareness, critical for multi-region APIs or scheduled jobs. It mitigates silent bugs common in Carbon/DateTime misuse by enforcing explicit timezone handling. Works seamlessly with Laravel Echo/Pusher for timezone-aware event timestamps.
- Are there performance concerns with immutable DateTime objects in high-traffic Laravel apps?
- Immutable objects may increase memory usage in high-throughput systems (e.g., queue workers). Benchmark critical paths (e.g., bulk date calculations) against Carbon. For most use cases, the tradeoff is worth the safety, but consider caching or pooling strategies for extreme scale.
- How do I test Laravel applications using this DateTime package?
- Use custom factories (e.g., `DateTime::factory()->create()`) to mock DateTime objects. Laravel’s `refreshDatabase()` works with seeded DateTime objects, and PestPHP supports assertions for Duration/Period/Interval. Static analysis (PHPStan) can enforce correct usage in tests.
- What are the key use cases for Duration, Period, and Interval in Laravel?
- Duration: Safer arithmetic (e.g., `Duration::days(5)` for promotions). Period: Billing cycles (e.g., `Period::months(1)` for subscriptions). Interval: Job scheduling (e.g., `Interval::daily()` for cron-like logic). Replace ad-hoc Carbon calculations with explicit, type-safe alternatives.
- Will this package work with Laravel Eloquent models and database timestamps?
- Yes, but requires explicit casting (e.g., `DateTime::fromTimestamp($model->created_at)`). For Eloquent attributes, use accessors/mutators to convert between database timestamps and this library’s types. No official Eloquent integrations exist yet, so manual handling is needed.
- Are there alternatives to this package for immutable DateTime handling in Laravel?
- Alternatives include `spatie/laravel-date` (Laravel-specific) or `ramsey/uuid` (for UUID-time combinations). However, this package stands out for its standard-library style, clear docs, and built-in Duration/Period/Interval helpers tailored for Laravel’s needs like billing and scheduling.
Weaver
How can I help you explore Laravel packages today?