digital-craftsman/datetime-parts
Value objects for precise date/time parts in PHP: Moment (UTC-based) plus Time, Date, Month, Year, Day/Weekday and collections. Avoid misleading DateTime comparisons, handle timezone-safe modifications across DST, with Symfony normalizers and Doctrine types.
DateTime ecosystem by introducing granular, immutable value objects (Moment, Time, Date, Month, Year, Day, etc.). This aligns perfectly with domain-driven design (DDD) and clean architecture principles, where domain-specific abstractions reduce ambiguity and improve maintainability.Moment objects (with timezone-aware modifications) mitigates DST and timezone-related bugs—a common pain point in distributed systems. This is particularly valuable for global applications or microservices where consistency is paramount.illuminate/container) and Doctrine support (via laravel-doctrine) allow for partial adoption. Key challenges:
Clock component (for testing) and normalizers may require wrappers or custom implementations in Laravel.FrozenClock for time-freezing tests aligns with Laravel’s Carbon testing utilities but may need adaptation.Moment, Date, etc., require database columns to match the package’s expectations (e.g., Moment needs a DATETIME(6) or TIMESTAMP(6) column). Migration tools like Laravel Migrations or Doctrine Migrations can handle this.DateTime with Moment/Time requires refactoring comparison logic (e.g., isBeforeInTimeZone instead of >, <). This is a breaking change but yields long-term clarity.0.14.* and monitor changelogs.Moment only for new features).DateTime. Benchmark critical paths (e.g., bulk operations) to ensure acceptable latency.where, orderBy) thoroughly.DateTime instances) or incrementally (only for new features)?FrozenClock for Laravel’s testing environment (e.g., Carbon mocking)?Clock interface?DATETIME/TIMESTAMP columns compatible with the package’s requirements (e.g., microsecond precision)?Moment vs. Carbon/DateTime in our most frequent operations (e.g., API requests, background jobs)?Time vs. Moment) to avoid misuse?Carbon/DateTime: The package can serve as a drop-in replacement for Laravel’s Carbon (which extends DateTime) in domains requiring precision. Use Moment for timestamps and Time/Date for granular comparisons.Clock) in Laravel’s container. Example:
$this->app->bind(\DigitalCraftsman\DateTimePrecision\Clock::class, \DigitalCraftsman\DateTimePrecision\SystemClock::class);
now() returning a Moment) to ease adoption.digital-craftsman/self-aware-normalizers. Install this separately and configure Laravel’s serializer (e.g., via symfony/serializer) to use the provided normalizers.laravel-doctrine/orm to integrate Doctrine types. Ensure the package’s types are auto-registered in Doctrine’s configuration.serializer package or manually normalize objects.DateTime/Carbon with Moment/Time.Carbon factories (e.g., now(), parse()) with Moment equivalents.isBeforeInTimeZone).DateTime usages with value objects.Moment as JSON in a text column).Moment serialization works in Laravel’s queue system (e.g., Redis, database). Test job persistence and deserialization.spatie/laravel-activitylog) rely on Carbon methods. Abstract these behind adapters or fork packages as needed.DateTime usage. Prioritize packages with clear interfaces (e.g., dependency injection) for easy adaptation.Carbon in spatie/laravel-permission by injecting a Clock interface.DATETIME(6) for Moment). Use Laravel Migrations or Doctrine Migrations.Appointment, Booking) to use Moment/Date types.Carbon test helpers with FrozenClock. Update snapshot tests for datetime formats.isBeforeInTimeZone) minimize timezone/DST issues.modifyInTimeZone make intent clearer than manual DateTime arithmetic.Clock interface and FrozenClock simplify time-freezing tests, reducing flakiness.0.14.* requires monitoring for breaking changes. Plan for periodic upgrades.Moment operations for observability.Day, Days). Document usage patterns.How can I help you explore Laravel packages today?