- How do I install apie/date-value-objects in a Laravel project?
- Run `composer require apie/date-value-objects` in your project root. The package has no Laravel-specific dependencies, so it integrates seamlessly with existing Carbon or DateTime code. Test compatibility with your PHP version (8.1+) and Laravel version (8.x+).
- Can I replace Carbon with these value objects in Eloquent models?
- Yes, but strategically. Use `DateWithTimezone` for timezone-aware fields (e.g., `getScheduledAtAttribute()`) and `LocalDate` for date-only fields. Store data as native SQL types (DATE/DATETIME) and convert to value objects in accessors/mutators. Avoid storing immutable objects directly in the database.
- What Laravel versions are officially supported?
- The package targets PHP 8.1+, but Laravel-specific documentation is minimal. Test thoroughly with your Laravel version (8.x or 9.x). For Laravel 10+, check the Apie monorepo for updates, as breaking changes may occur without explicit versioning. Use feature flags if stability is critical.
- How do I validate incoming API requests with these value objects?
- Extend Laravel’s `FormRequest` with custom validation rules. For example, use `LocalDate::fromString($request->date)` in a rule to reject invalid dates like February 30. The package’s strict parsing ensures domain-specific constraints (e.g., `HourAndMinutes` for time slots) are enforced early in the request lifecycle.
- Are there performance concerns with immutable value objects vs. Carbon?
- Immutable objects introduce slight memory overhead due to cloning and validation. Benchmark in high-throughput scenarios (e.g., batch jobs). For performance-critical paths, use `UnixTimestamp` for logs or `LocalDate` for storage, and convert to Carbon only when needed (e.g., for Carbon-specific libraries).
- How do I convert between Carbon instances and these value objects?
- Use static factory methods like `DateWithTimezone::fromCarbon($carbon)` or `Carbon::fromDateWithTimezone($dwo)`. For one-off conversions, implement helper traits in your models/services. Example: `Carbon::parse($dwo->format(DateWithTimezone::ATOM_FORMAT))` for interoperability with third-party packages.
- What if I need to work with days/months in Laravel queues or events?
- Use interfaces like `WorksWithDays` or `WorksWithMonths` for date arithmetic (e.g., `LocalDate::nextMonth()`). Serialize value objects to strings or timestamps for queue jobs, then reconstruct them on dispatch. Pair with Laravel’s `ShouldQueue` and `Dispatchable` for seamless integration.
- Are there alternatives to apie/date-value-objects for Laravel?
- Yes: `spatie/laravel-date` for database integration, `carbon/carbon` for mutable datetime handling, or `ramsey/uuid` for UUID-based time tracking. However, apie/date-value-objects uniquely enforces domain-specific types (e.g., `HourAndMinutes` vs. `Time`) and integrates with DDD patterns. Evaluate based on your need for strict validation vs. flexibility.
- How do I handle timezone differences in DateWithTimezone?
- `DateWithTimezone` enforces explicit timezone handling via the ATOM format (e.g., `2023-10-05T14:30:00+00:00`). Convert from Carbon by specifying the timezone: `DateWithTimezone::fromCarbon($carbon->setTimezone('UTC'))`. Avoid mixing timezones by standardizing on UTC for storage and converting to local timezones only in presentation layers.
- Can I use these value objects in Laravel API resources or DTOs?
- Absolutely. Return value objects from API resources (e.g., `return new EventResource($event->scheduledAt)` where `$event->scheduledAt` is a `DateWithTimezone`). Use OpenAPI/Swagger annotations to document expected formats (e.g., `type: string` with `format: date-time`). The package’s strict types improve API contract clarity and client-side validation.