Date Time Laravel Package

Getting Started

Minimal Steps

1. Installation

   composer require php-standard-library/date-time
   

   Add to composer.json under require or require-dev if needed.

2. First Use Case: Immutable DateTime Creation

   use PhpStandardLibrary\DateTime\DateTime;
   
   $date = DateTime::fromIsoString('2026-05-23T12:00:00+00:00');
   echo $date->format('Y-m-d H:i:s'); // Outputs: 2026-05-23 12:00:00
   

3. Key Classes to Explore

   • DateTime (immutable, timezone-aware)
   • Duration (e.g., Duration::days(5))
   • Period (e.g., Period::months(3))
   • Interval (e.g., Interval::fromStartEnd($start, $end))

4. Where to Look First

   • Documentation: PHP Standard Library Docs
   • Source Code: GitHub Repository
   • Tests: tests/ directory for usage examples and edge cases

Implementation Patterns

Core Workflows

1. Timezone-Aware DateTime Handling

use PhpStandardLibrary\DateTime\DateTime;

// Create a timezone-aware DateTime
$now = DateTime::now('America/Chicago');

// Convert to another timezone
$utcTime = $now->inTimezone('UTC');

// Format with timezone
echo $now->format('Y-m-d H:i:sP'); // e.g., 2026-05-23 12:00:00-05:00

2. Immutable Date Manipulation

use PhpStandardLibrary\DateTime\Duration;
use PhpStandardLibrary\DateTime\Period;

$date = DateTime::fromIsoString('2026-05-23T12:00:00+00:00');

// Add a duration (immutable)
$futureDate = $date->add(Duration::days(7));

// Subtract a period (immutable)
$pastDate = $date->subtract(Period::months(2));

3. Interval Calculations for Ranges

use PhpStandardLibrary\DateTime\Interval;

$start = DateTime::fromIsoString('2026-01-01T00:00:00+00:00');
$end = DateTime::fromIsoString('2026-01-31T23:59:59+00:00');

$interval = Interval::fromStartEnd($start, $end);
echo $interval->days(); // Outputs: 31

4. Duration for Time Differences

use PhpStandardLibrary\DateTime\Duration;

$start = DateTime::fromIsoString('2026-05-23T10:00:00+00:00');
$end = DateTime::fromIsoString('2026-05-23T12:30:00+00:00');

$duration = $start->diff($end);
echo $duration->hours(); // Outputs: 2.5

5. Period for Recurring Events

use PhpStandardLibrary\DateTime\Period;

$period = Period::months(3); // 3 months
$nextDate = $date->add($period);

6. Laravel Integration: Eloquent Casting

use Illuminate\Database\Eloquent\Model;
use PhpStandardLibrary\DateTime\DateTime;

class Event extends Model
{
    protected $casts = [
        'starts_at' => DateTime::class,
        'ends_at' => DateTime::class,
    ];
}

7. Validation with Custom Rules

use Illuminate\Validation\Rule;
use PhpStandardLibrary\DateTime\Duration;

$validator = Validator::make($request->all(), [
    'due_date' => [
        'required',
        Rule::function('due_date', function ($attribute, $value, $fail) {
            $dueDate = DateTime::fromIsoString($value);
            $minDuration = Duration::days(7);
            if ($dueDate->subtract($minDuration)->isBefore(DateTime::now())) {
                $fail('Due date must be at least 7 days from now.');
            }
        }),
    ],
]);

Gotchas and Tips

Pitfalls and Debugging Tips

1. Immutability Gotchas

• Issue: Forgetting that operations return new objects, not modifying the original.

  $date = DateTime::now();
  $date->add(Duration::days(1)); // Doesn't modify $date!
  $date = $date->add(Duration::days(1)); // Correct
  

• Fix: Always assign the result of manipulation methods.

2. Timezone Defaults

• Issue: DateTime::now() defaults to UTC, unlike Carbon which uses the system timezone.

  $date = DateTime::now(); // UTC by default
  $date = DateTime::now('America/New_York'); // Explicit timezone
  

• Fix: Always specify the timezone explicitly.

3. Serialization Issues

• Issue: DateTime objects may not serialize/deserialize correctly in JSON APIs.

  $date = DateTime::now();
  json_encode($date); // May throw an error
  

• Fix: Use toIsoString() or implement JsonSerializable.

  $date->toIsoString(); // "2026-05-23T12:00:00+00:00"
  

4. Method Naming Differences

• Issue: Methods like add() and subtract() take Duration/Period objects, not raw values.

  $date->add(7); // Error!
  $date->add(Duration::days(7)); // Correct
  

• Fix: Always pass Duration or Period objects.

5. Database Interactions

• Issue: Eloquent may not handle DateTime objects out of the box.

  $model->date = DateTime::now(); // May not save correctly
  

• Fix: Use accessors/mutators or cast attributes.

  protected $casts = [
      'date' => DateTime::class,
  ];
  

6. Leap Seconds and Edge Cases

• Issue: The library may not handle leap seconds or complex DST transitions perfectly.
• Fix: Test thoroughly with edge-case timestamps.

Configuration Quirks

1. Default Timezone

• The library does not use PHP’s default timezone setting. Always specify timezones explicitly.

DateTime::now('UTC'); // Explicit timezone

2. No Carbon Compatibility Layer

• Unlike Carbon, this library does not provide backward compatibility. Avoid mixing Carbon and DateTime objects in the same logic.

3. No Built-in Parsing

• Unlike Carbon, this library does not have a parse() method. Use fromFormat() or fromIsoString() instead.

DateTime::fromFormat('Y-m-d', '2026-05-23');
DateTime::fromIsoString('2026-05-23T12:00:00+00:00');

Extension Points

1. Custom Formatters

• Extend the library by creating custom formatters for specific use cases.

class CustomDateFormatter
{
    public static function formatForAPI(DateTime $date): string
    {
        return $date->format('Y-m-d\TH:i:s.vP');
    }
}

2. Adapters for Third-Party Libraries

• Create adapters to bridge this library with others (e.g., Carbon).

class DateTimeToCarbonAdapter
{
    public static function adapt(DateTime $date): Carbon\Carbon
    {
        return Carbon\Carbon::instance($date);
    }
}

3. Custom Validation Rules

• Build reusable validation rules for business logic.

use Illuminate\Validation\