Datetime Parts Laravel Package

Product Decisions This Supports

• Precision in Date/Time Handling: Enables granular control over date/time components (e.g., Time, Date, Month, Year) without ambiguity, reducing bugs tied to timezone/offset mismatches or redundant data (e.g., storing a Date as a DateTime at midnight).
• Immutable Architecture: Aligns with modern PHP/Laravel practices by enforcing immutability for Moment and its parts, simplifying state management and thread safety.
• Timezone Isolation: Centralizes timezone logic (e.g., UTC for Moment, explicit zones for Time/Date), eliminating "off-by-one" errors (e.g., daylight saving time) and improving consistency across microservices.
• Database Integration: Reduces ORM complexity by storing precise types (e.g., Moment as Moment type in Doctrine) instead of bloated DateTime fields, with built-in normalizers for APIs.
• Testing & Observability:
  • Clock Abstraction: FrozenClock enables deterministic testing (e.g., time-freezing for unit tests).
  • Validation: Guard methods (e.g., mustBeEqualTo()) catch edge cases early (e.g., invalid bookings).
• Roadmap Priorities:
  • Phase 1: Replace legacy DateTime usage in core workflows (e.g., scheduling, bookings) with Moment/Time/Date.
  • Phase 2: Extend to third-party integrations (e.g., payment deadlines, recurring events) using Year/Month for precision.
  • Phase 3: Leverage Day/Weekday for calendar features (e.g., "business days only" logic).
• Build vs. Buy:
  • Buy: Avoids reinventing wheel for timezone-aware comparisons/modifications (e.g., isBeforeInTimeZone()).
  • Customize: Extend via Clock interface for domain-specific time logic (e.g., "holiday-aware" clocks).

When to Consider This Package

• Adopt When:
  • Your app handles time-sensitive logic (e.g., appointments, subscriptions, deadlines) where DateTime ambiguity (e.g., timezone offsets, midnight assumptions) causes bugs.
  • You need precise comparisons (e.g., "Is this time before the facility’s open hours?" vs. "Is this date before the booking cutoff?").
  • Your team uses Symfony/Laravel and Doctrine, and wants seamless integration with normalizers/Doctrine types.
  • You prioritize testability and want to mock time (e.g., FrozenClock) without refactoring.
  • Your database schema is bloated with DateTime fields storing only dates/times (e.g., created_at as DateTime when a Date suffices).
• Look Elsewhere If:
  • You’re not using PHP 8.4+ or Symfony 7+/Laravel (requires custom adapters).
  • Your app is simple (e.g., blogs) with no timezone/precision needs.
  • You need high-performance (this adds minor overhead for wrappers; benchmark if critical).
  • Your team lacks immutability discipline (enforced here, but requires buy-in).
  • You rely on legacy codebases where replacing DateTime is prohibitively risky (start with new features).

How to Pitch It (Stakeholders)

For Executives:

*"This package solves a hidden technical debt problem: timezone and date precision errors cost us X hours/year in debugging and outages. For example, our booking system’s ‘open hours’ logic fails during daylight saving transitions because we’re comparing DateTime objects incorrectly. This library:

• Eliminates ambiguity: Replace DateTime with precise types like Time (for hours) or Date (for days), so ‘Is the facility open?’ is a single, clear comparison.
• Reduces bugs: All modifications (e.g., ‘+7 days’) happen in the correct timezone automatically, no more ‘missing hour’ errors.
• Saves dev time: Built-in Doctrine types and normalizers mean we can store dates/times cleanly in the database and APIs without manual conversions.
• Future-proofs testing: We can freeze time for tests without hacky workarounds, speeding up QA. Investment: Minimal (composer install + refactoring). ROI: Fewer production fires, cleaner code, and scalability for time-sensitive features like subscriptions or global scheduling."*

For Engineers:

*"This is a drop-in replacement for DateTime that fixes three key pain points:

1. Precision: Compare Time objects directly (e.g., isBeforeInTimeZone($facilityOpenTime)) without normalizing to midnight.
2. Timezones: Internally uses UTC for Moment but lets you modify in any timezone (e.g., modifyInTimeZone('+1 week', $userTimezone)).
3. Immutability: All operations return new instances, making state management safer. Why now:

• Our current DateTime usage is a leaky abstraction (e.g., created_at as DateTime when we only care about the date).
• Doctrine integration means zero schema changes—just swap types in entities. Migration path:

1. Start with Moment for all DateTime fields in new features.
2. Use Time/Date for granular logic (e.g., business hours, deadlines).
3. Replace new DateTime() calls with SystemClock::now() for consistency. Tradeoffs:

• Minor performance overhead (negligible for most apps).
• Requires discipline for immutability (but enforces it). Example win:

// Before (bug-prone):
if ($now->getTimestamp() < $facilityOpenTime->getTimestamp()) { ... }

// After (clear and timezone-safe):
if ($now->isBeforeInTimeZone($facility->openFrom, $facilityTimeZone)) { ... }
```*
*Let’s pilot this in the booking system first—it’s the highest-risk area for timezone bugs."*