Legacy Date Functions

Also Known As

TL;DR

Explanation

PHP's procedural date functions (date(), mktime(), strtotime()) operate on Unix timestamps and use the default timezone set by date_default_timezone_set(). They are mutable, cannot be mocked in tests, and lead to timezone bugs. DateTimeImmutable (PHP 5.5+) provides an immutable, object-oriented API: timezone-aware, chainable, testable (Carbon extends it), and compatible with DateTimeInterface. date() and strtotime() are acceptable for quick scripts but not for application date logic.

Common Misconception

Why It Matters

Common Mistakes

• date('Y-m-d') in tests — untestable; use DateTimeImmutable and mock the clock.
• strtotime('+1 month') — silently fails on some date strings; use modify('+1 month').
• Not checking strtotime() for false — invalid input silently becomes timestamp 0 (1970).
• DateTime (mutable) instead of DateTimeImmutable — shared DateTime references can be modified unexpectedly.

Code Examples

// Procedural, untestable, timezone-fragile:
$expiry = date('Y-m-d', strtotime('+30 days'));
$timestamp = mktime(0, 0, 0, 12, 25, 2026);
$age = (time() - strtotime($user->birthdate)) / (365.25 * 86400);

// Mutable DateTime — shared reference bug:
$start = new DateTime('2026-01-01');
$end = $start->modify('+1 month'); // $start also modified!

// DateTimeImmutable — immutable, testable, timezone-aware:
$expiry = (new DateTimeImmutable())->modify('+30 days')->format('Y-m-d');
$xmas   = new DateTimeImmutable('2026-12-25', new DateTimeZone('UTC'));

$birth = new DateTimeImmutable($user->birthdate);
$age   = (new DateTimeImmutable())->diff($birth)->y;

// Immutable — original unchanged:
$start = new DateTimeImmutable('2026-01-01');
$end   = $start->modify('+1 month'); // $start unchanged

References

• ↗ https://www.php.net/manual/en/class.datetimeimmutable.php

Tags

Related Terms