Human-Readable Differences
Show relative times like '3 days ago' with diffForHumans().
Syntax
$carbon->diffForHumans();The diffForHumans() method produces friendly phrases such as "5 minutes ago" or "in 2 weeks". You can also compute precise differences with diffInDays(), diffInHours() and similar methods.
Example
Loading editor…
Press Run to execute the code.
When to use it
- A billing dashboard calls diffInDays() between today and a user's next invoice date to show a 'due in N days' badge next to each subscription.
- An HR tool uses diffInMinutes() between a shift's planned and actual start times to flag late arrivals automatically.
- A report generator uses diffInMonths() to verify that a date range entered by the user is no longer than six months before running a heavy aggregation query.
More examples
Difference in various time units
diffInDays(), diffInHours(), and diffInMonths() each return an integer difference between two Carbon instances.
use Carbon\Carbon;
$start = Carbon::parse('2025-01-01');
$end = Carbon::parse('2025-03-14');
$days = $start->diffInDays($end); // 72
$hours = $start->diffInHours($end); // 1728
$months = $start->diffInMonths($end); // 2Days until a deadline
Passing false as the second argument to diffInDays() allows negative values, making it easy to detect overdue items.
use Carbon\Carbon;
$deadline = Carbon::parse($project->due_at);
$daysLeft = now()->diffInDays($deadline, false);
// Negative means overdue
if ($daysLeft < 0) {
$label = 'Overdue by ' . abs($daysLeft) . ' days';
} else {
$label = 'Due in ' . $daysLeft . ' days';
}CarbonInterval for structured diffs
Carbon::diff() returns a DateInterval/CarbonInterval, which can be formatted with % placeholders to display all components of the difference.
use Carbon\Carbon;
$start = Carbon::parse('2025-01-01 08:00');
$end = Carbon::parse('2025-03-14 17:30');
$interval = $start->diff($end);
echo $interval->format('%m months, %d days, %H:%I');
// => '2 months, 13 days, 09:30'
Discussion