Date Time Laravel Package

Technical Evaluation

Architecture Fit

• Immutability & Type Safety: The package’s immutable design aligns well with modern PHP/Laravel practices, reducing unintended side effects in stateful operations (e.g., date manipulations in business logic). The use of enums (DayOfWeek, Month) and strict typing (e.g., int ranges) improves code reliability and IDE support.

• ISO 8601 Compliance: The adherence to ISO 8601 standards ensures consistency with global systems (e.g., APIs, databases), reducing parsing/formatting edge cases. This is critical for Laravel applications handling internationalized date logic (e.g., e-commerce, scheduling).

• Clock Abstraction: The Clock interface (with SystemClock, FixedClock, etc.) enables time-travel testing and deterministic behavior in tests—a significant advantage over PHP’s native DateTime, which relies on system time. This is particularly valuable for:

  • Feature flags tied to dates.
  • Time-sensitive workflows (e.g., promotions, subscriptions).
  • CI/CD pipelines where environment clocks may vary.

• Complementary to Laravel: While Laravel’s Carbon dominates date handling, this library fills gaps:

  • Granular components: LocalDate, LocalTime, YearMonth simplify domain-specific logic (e.g., calendar systems, fiscal periods).
  • Intervals vs. Durations: Distinguishes between wall-clock time (Duration) and calendar-based periods (Period), useful for billing or scheduling.
  • Doctrine Integration: The brick/date-time-doctrine package bridges this library with Eloquent, enabling typed date fields (e.g., YearMonth for monthly subscriptions).

Integration Feasibility

• Low Friction: Composer installation and minimal boilerplate (e.g., use Brick\DateTime\LocalDate) make adoption straightforward. The library’s API mirrors Laravel conventions (e.g., now() methods).
• Carbon Interoperability: While not a drop-in replacement, the library can coexist with Carbon. For example:

  use Brick\DateTime\LocalDateTime;
  use Carbon\Carbon;
  
  $carbon = Carbon::parse('2023-01-01');
  $brickDateTime = LocalDateTime::ofEpochSecond($carbon->getTimestamp());
  

  This enables gradual migration of critical date logic.
• Database Layer: The Doctrine integration allows replacing raw DateTime fields with typed alternatives (e.g., YearMonth for recurring events). However, this requires schema migrations and ORM updates.

Technical Risk

• Breaking Changes: The package’s 0.x versioning indicates instability. Key risks:
  • API Shifts: Methods like DayOfWeek::of() → DayOfWeek::from() or Duration string formatting changes may require refactoring. Mitigation: Lock to a patch version (e.g., 0.9.*) and monitor changelogs.
  • PHP 8.2 Dependency: If the Laravel app targets PHP 8.1, this becomes a blocker. Mitigation: Evaluate PHP 8.2 upgrades or use a polyfill (though none exists for this library).
• Performance Overhead: Immutable objects and enums may introduce slight memory/CPU overhead compared to Carbon. Mitigation: Benchmark critical paths (e.g., bulk date operations).
• Testing Complexity: Time-travel features (FixedClock, travelTo()) require disciplined test teardown (e.g., DefaultClock::reset()). Mitigation: Use PHPUnit’s tearDown() or a testing library like Laravel’s travel() as a wrapper.

Key Questions

1. Domain Alignment:
   • Does the application have domain-specific date logic (e.g., fiscal years, custom calendars) that this library can simplify?
   • Example: A SaaS with monthly billing cycles could use YearMonth instead of Carbon for subscription logic.
2. Testing Strategy:
   • How will time-travel testing scale? Will the team adopt FixedClock for all date-dependent tests, or use a hybrid approach (e.g., Carbon for some, Brick for others)?
3. Migration Path:
   • Which parts of the codebase are most critical for date handling? Prioritize migrating those first (e.g., business logic over views).
4. Database Impact:
   • Are there existing DateTime fields in the database that could benefit from stricter typing (e.g., YearMonth for recurring events)?
5. Team Adoption:
   • Does the team have experience with immutable objects and enums? If not, budget for training or incremental adoption.

Integration Approach

Stack Fit

• Laravel Ecosystem:
  • Carbon Compatibility: The library can replace Carbon in business logic while Carbon remains in views/templates (where its fluent API is preferred).
  • Eloquent: The Doctrine integration enables typed date fields in models. Example:

    use Brick\DateTime\YearMonth;
    use Brick\DateTimeDoctrine\Types\YearMonthType;
    
    class Subscription extends Model {
        protected $casts = [
            'billingCycle' => YearMonthType::class,
        ];
    }
    

  • Queues/Jobs: Use FixedClock to test time-sensitive jobs (e.g., delayed notifications).
  • APIs: Standardize on ISO 8601 formats for request/response payloads (e.g., LocalDateTime instead of Carbon).
• Testing:
  • Replace Carbon::setTestNow() with DefaultClock::freeze() for deterministic tests.
  • Use travelTo()/travelBy() for scenario testing (e.g., "what happens 30 days after subscription?").

Migration Path

1. Phase 1: New Features
   • Introduce the library for new date logic (e.g., a new calendar system). Avoid touching existing Carbon-based code.
   • Example: Use LocalDateRange for a new "event series" feature.
2. Phase 2: Critical Paths
   • Replace Carbon in high-risk areas:
     • Business logic (e.g., subscription renewals, promotions).
     • Time-sensitive workflows (e.g., order deadlines).
   • Use adapter classes to bridge Carbon and Brick temporarily:

     class CarbonAdapter {
         public static function toBrickLocalDateTime(Carbon $carbon): LocalDateTime {
             return LocalDateTime::ofEpochSecond($carbon->getTimestamp());
         }
     }
     

3. Phase 3: Full Replacement
   • Migrate remaining Carbon usage to Brick, leveraging the Doctrine types for database fields.
   • Deprecate Carbon in favor of Brick in the codebase.

Compatibility

• Laravel Services:
  • Carbon: No direct conflict; treat as a peer dependency.
  • Carbon Extensions: Some packages (e.g., spatie/laravel-activitylog) may rely on Carbon’s internals. Mitigation: Test thoroughly or fork the package.
  • Laravel Framework: No known conflicts, as the library operates at the application layer.
• Third-Party Libraries:
  • Libraries using DateTime (e.g., nesbot/carbon) may need wrappers. Example:

    function toCarbon(LocalDateTime $dateTime): Carbon {
        return Carbon::instance($dateTime->toDateTime());
    }
    

Sequencing

1. Add Dependency:

   composer require brick/date-time
   

   Lock to a patch version (e.g., 0.9.*) to avoid breaking changes.
2. Infrastructure Setup:
   • Configure Doctrine types (if using Eloquent).
   • Set up test utilities for DefaultClock (e.g., a TestCase trait).
3. Incremental Adoption:
   • Start with utility classes (e.g., DateHelper) to encapsulate Brick usage.
   • Gradually replace Carbon in new PRs or feature branches.
4. Deprecation:
   • Once Brick is stable, deprecate Carbon usage via static analysis (e.g., PHPStan rules).

Operational Impact

Maintenance

• Pros:
  • Reduced Bug Surface: Immutable objects and strict typing catch errors at compile time (e.g., invalid date arithmetic).
  • Easier Debugging: Exceptions like DateTimeException provide clear error messages (e.g., "Invalid day of month: 32").
  • Testing: Time-travel features simplify edge-case testing (e.g., DST transitions, leap seconds).
• Cons:
  • Version Locking: The 0.x versioning requires careful dependency management. Mitigation: Use composer require brick/date-time:0.9.* and monitor GitHub releases.
  • **Tool