Search for a command to run...
I am a computer science and full stack enthusiast obsessed with building applications for the modern web. I'm here to write about the things I encounter as a full stack developer.
I've been building web apps since ~2001, but only decided recently in the beginning of 2023 that I want to start writing. So here it goes!
No comments yet. Be the first to comment.
In this article, I share a simple helper to improve the developer experience when working with time ranges in Laravel. You will be able to drop it into your applications as-is or modify it as needed.
Note: At the time of publishing, the code in this article was written for Laravel v9.50.2 and PHP v8.1.13.
We have a Delivery model with two fields start_time and end_time (MySQL time columns). How can we translate the raw values into a more human-readable time range (e.g., 8:15am - 12pm), in a way that is more intelligent than naively concatenating the two values?
Or in general: how do we translate a pair of raw time values into a human-readable time range?
The high-level algorithm:
Normalize times to 12-hour format without leading zeroes
Not concerned about seconds, only hours and minutes
Attach am or pm as needed, non-redundantly
Strip minutes if not needed (e.g., 1:00pm simplifies to 1pm)
Collapse to a single time (non-range) if start and end are equal
To illustrate further, here are more time ranges with their expected outputs:
| Start Time | End Time | Time Range |
| 10:00:00 | 12:00:00 | 10am - 12pm |
| 10:00:00 | 11:00:00 | 10 - 11am |
| 08:15:00 | 12:00:00 | 8:15am - 12pm |
| 13:30:00 | 18:15:00 | 1:30 - 6:15pm |
| 01:00:00 | 13:00:00 | 1am - 1pm |
| 01:25:00 | 13:00:00 | 1:25am - 1pm |
| 13:30:00 | 13:30:00 | 1:30pm |
This comes in handy wherever we need to express time ranges in a more natural human-readable format, such as:
On a Delivery index page, showing delivery time windows within a single column
Notifications and mail messages where short concise messaging is essential
Within a calendar grid or other frontend UI component where space is limited
For this article, I've chosen to implement a TimeRange helper class with a static method stringify that accepts three parameters:
$start - Start Time
$end - End Time
$glue - Optional time range delimiter (defaults to ' - ')
The optional glue parameter will allow, for example, expressing time ranges as "10 to 11am". Here's the code:
<?php
namespace App\Support;
use Illuminate\Support\Carbon;
class TimeRange
{
public static function stringify($start, $end, $glue = ' - ')
{
// Attempt to parse the start and end
$start = $start ? rescue(fn () => Carbon::parse($start)) : null;
$end = $end ? rescue(fn () => Carbon::parse($end)) : null;
$start24h = $start?->format('H:i');
$end24h = $end?->format('H:i');
// If times are identical, return early
if ($start24h === $end24h) {
return $start?->format('g:ia');
}
// Stringify the start and end
$startStr = str($start?->format('g:i'));
$endStr = str($end?->format('g:i'));
// Extract the periods (am/pm)
$startPeriod = $start?->format('a');
$endPeriod = $end?->format('a');
// Strip redundant :00 from the end of the strings
$startStr = $startStr->whenEndsWith(':00', fn ($s) => $s->beforeLast(':00'));
$endStr = $endStr->whenEndsWith(':00', fn ($s) => $s->beforeLast(':00'));
$suffix = '';
// Only attach individual periods if they differ
if ($startPeriod !== $endPeriod) {
$startStr = $startStr->append($startPeriod);
$endStr = $endStr->append($endPeriod);
} else {
$suffix = $endPeriod;
}
$combined = collect([$startStr->toString(), $endStr->toString()])
->reject(fn ($s) => blank($s))
->join($glue);
return $combined.$suffix;
}
}
I'm satisfied with the implementation for our needs, but should note few things:
It will attempt to parse the specified $start and $end times using Carbon::parse(), and quietly fall back to null if an unparseable value is given.
It will not validate whether the pair of start and end times are in the correct intended order. e.g., TimeRange::stringify('13:00', '10:00') would yield a time range that doesn't make sense ("1pm - 10am")
At the time of publishing, this was written for Laravel v9.50.2 and PHP v8.1.13.
Here are a few examples of hypothetical usage:
// With a model
TimeRange::stringify($delivery->start_time, $delivery->end_time);
// With Carbon values
TimeRange::stringify(now(), now()->addHours(3));
// With unix timestamps
TimeRange::stringify(time(), strtotime('+3 hours'));
// With PHP DateTime objects
TimeRange::stringify(new DateTime(), new DateTime('+3 hours'));
// With custom glue
TimeRange::stringify(now(), now()->addHours(3), ' to ');
Here's a supporting test covering the most practical cases plus a few edge cases where invalid times are used. It is written with Pest, but is easily adaptable for classic PHPUnit.
use App\Support\TimeRange;
it('can generate time range', function ($start, $end, $result) {
expect(TimeRange::stringify($start, $end))->toBe($result);
})->with([
// Start Time, End Time, Expected Result
['10:00:00', '12:00:00', '10am - 12pm'],
['10:00:00', '11:00:00', '10 - 11am'],
['08:15:00', '12:00:00', '8:15am - 12pm'],
['13:30:00', '18:15:00', '1:30 - 6:15pm'],
['01:00:00', '13:00:00', '1am - 1pm'],
['01:25:00', '13:00:00', '1:25am - 1pm'],
['01:25:00', '13:25:00', '1:25am - 1:25pm'],
['13:30:00', '13:30:00', '1:30pm'],
['10:01', '11:10', '10:01 - 11:10am'],
[null, '18:15:00', '6:15pm'],
['13:30:00', null, '1:30pm'],
['invalid-time', '13:30:00', '1:30pm'],
['13:30:00', 'invalid-time', '1:30pm'],
['invalid-time', 'invalid-time', null],
['9', '12', null],
]);
And the corresponding test results:
You're free to modify as needed, this is just a starting point. If you're not yet in the habit of writing tests for your applications, I hope this will nudge you in that direction to start.
If you reached this far, congratulations. If you found this snippet useful or have used it in your applications, I'd love to hear about it. Cheers!