Date Value Objects Laravel Package

Product Decisions This Supports

• Domain-Driven Design (DDD) Adoption: Enables precise modeling of date/time entities (e.g., LocalDate, HourAndMinutes) to align with business logic, reducing ambiguity in domain models and improving code maintainability. Ideal for projects where date/time logic is core to the domain (e.g., healthcare, finance, or scheduling platforms).
• Validation and Data Integrity: Mitigates risks of invalid date/time inputs (e.g., "February 30") by enforcing type safety via immutable value objects. Critical for APIs, forms, or systems where data consistency is non-negotiable (e.g., compliance deadlines, audit logs).
• API/Backend Roadmap Acceleration: Accelerates development of time-sensitive features (e.g., subscriptions, event scheduling, or compliance workflows) by providing reusable, immutable date/time primitives. Reduces boilerplate code for common operations like timezone handling or recurring intervals.
• Build vs. Buy Decision: Justifies internal investment in custom date logic for niche use cases where generic libraries like Carbon or DateTime are overkill or insufficient. For example:
  • Financial Systems: Precise modeling of business days (excluding weekends/holidays) without bloated dependencies.
  • Healthcare: Strict validation of medical appointment times (HourAndMinutes) or patient admission dates (LocalDate).
  • Legal/Compliance: Immutable timestamps (UnixTimestamp) for audit trails or regulatory reporting.
• Use Cases:
  • Event Scheduling: Use DateWithTimezone to enforce timezone-aware bookings, reducing bugs from implicit timezone assumptions.
  • Recurring Payments: Leverage WorksWithMonths/WorksWithYears to model subscription billing cycles (e.g., "charge on the 1st of every month").
  • Audit Logs: Replace mutable timestamps with UnixTimestamp to ensure immutability in event logs.
  • Localization: Use LocalDate for user-facing dates to avoid timezone conversion pitfalls in UI layers.
  • Microservices: Define clear contracts between services using value objects (e.g., HourAndMinutes for appointment APIs).

When to Consider This Package

• Adopt If:

  • Your application requires strict date/time granularity (e.g., "only dates," "only hours/minutes") that PHP’s DateTimeImmutable or Carbon cannot enforce without additional validation.
  • You are building a domain-rich application (e.g., DDD, CQRS) where date/time logic is central to the business model (e.g., scheduling, finance, healthcare).
  • You need immutable, type-safe date objects to prevent bugs from invalid inputs (e.g., "April 31") or unintended mutations.
  • Your team is comfortable with value objects and DDD patterns, as this package introduces a paradigm shift from mutable DateTime/Carbon instances.
  • You want to avoid bloated dependencies like Carbon for lightweight date logic, especially in performance-sensitive applications.

• Avoid If:

  • Your use case requires complex date arithmetic (e.g., business calendars with holidays, fiscal year calculations) → Consider Carbon or PHP-Intl for advanced features.
  • You need high-performance parsing/formatting (e.g., parsing 10,000+ dates per second) → Use native DateTime or Carbon with optimized formats.
  • The project is small-scale or prototyping with minimal date logic → The overhead of value objects may not justify the benefits.
  • Your team lacks DDD experience → The package may introduce unnecessary complexity or require significant training.
  • You rely heavily on Laravel’s built-in date utilities (e.g., Carbon macros, Eloquent casting) and lack the bandwidth to build custom integrations.

• Look Elsewhere If:

  • You need timezone conversion utilities (e.g., converting between UTC and user timezones) → Use Carbon or Moment.js (for JavaScript interop).
  • Your stack is not PHP/Laravel → Evaluate language-specific alternatives:
    • Python: datetime or dateutil.
    • JavaScript: date-fns or luxon.
  • You require database-specific features (e.g., PostgreSQL intervals, MySQL date functions) → Pair with Laravel’s Carbon or Spatie’s Date.
  • You need graphical date pickers or UI components → Use frontend libraries like react-datepicker alongside this package for backend validation.

How to Pitch It (Stakeholders)

For Executives

"This package lets us model dates as precise, business-aligned objects—like LocalDate for user-facing dates or HourAndMinutes for appointments—reducing bugs from invalid inputs (e.g., 'February 30') while keeping our stack lightweight. It’s a MIT-licensed, Laravel-friendly alternative to bloated libraries like Carbon, cutting development time for time-sensitive features like subscriptions or scheduling. The low-risk adoption starts with pilot features, and the long-term payoff is fewer data integrity issues and cleaner domain models. Think of it as 'type safety for dates'—just like we enforce types for user IDs or currencies."

Key Talking Points:

• Reduces bugs: Immutable objects prevent invalid dates (e.g., "April 31") at the code level.
• Aligns with business logic: Models like WorksWithMonths mirror real-world rules (e.g., "charge on the 1st of every month").
• Lightweight: ~10KB vs. Carbon’s ~500KB, with no Laravel bloat.
• Future-proof: MIT license, minimal dependencies, and DDD-friendly design.
• Low risk: Start with non-critical features (e.g., audit logs, scheduling) before full adoption.

For Engineering Teams

*"Apie’s date value objects solve the ‘DateTime bloat’ problem: instead of carrying hours/minutes/timezones when you only need a date, we use immutable, type-safe primitives like LocalDate or UnixTimestamp. Here’s how it helps us:

Problems It Solves:

• Validation: Methods like nextMonth() handle edge cases (e.g., Jan 31 → Feb 28) automatically, reducing null checks.
• Clarity: Domain models (e.g., EventDate = DateWithTimezone) mirror business logic, making code self-documenting.
• Safety: Immutable objects prevent accidental mutations (e.g., Carbon::modify() side effects).
• Performance: Lightweight (~10KB) vs. Carbon (~500KB), with no Laravel-specific overhead.

Tradeoffs:

• Adoption Curve: Requires shifting from mutable Carbon/DateTime to value objects (e.g., LocalDate instead of Carbon::now()->format('Y-m-d')).
• Initial Overhead: Need to write adapters for Laravel integrations (e.g., Eloquent casting, Form Request validation).
• Testing: Edge cases (e.g., leap seconds, timezone DST transitions) must be validated manually.

How to Start:

1. Pilot: Replace Carbon in new features (e.g., a scheduling module) with DateWithTimezone and HourAndMinutes.
2. Validation: Use LocalDate in Form Requests to validate user inputs (e.g., date fields).
3. Domain Layer: Inject value objects into services (e.g., SubscriptionService uses WorksWithMonths for billing cycles).
4. Gradual Refactor: Replace Carbon in legacy code only where date logic is complex or bug-prone.

Example Migration:

// Before (mutable, ambiguous)
$date = Carbon::parse($request->input('event_date'));

// After (immutable, explicit)
$date = LocalDate::fromString($request->input('event_date'));
$event = new Event($date, $request->input('title'));

Tools to Leverage:

• Laravel: Use Carbon::instance($dateWithTimezone) for interop with existing code.
• Testing: Validate edge cases (e.g., LocalDate::nextMonth() on Jan 31 → Feb 28).
• Documentation: Add PHPDoc types (e.g., #[Assert\Type(type: LocalDate::class)]) for IDE support.

When to Avoid:

• Simple CRUD apps with minimal date logic.
• Projects where Carbon’s flexibility is critical (e.g., complex timezone conversions).
• Teams resistant to DDD patterns or immutable objects.

Next Steps:

• Spike: Test the package in a non-critical feature (e.g., a new API endpoint).
• POC: Build a prototype for a high-priority