PHP: Practical ways to escape from the hell of Dates

Critical features for businesses often rely on dates, such as subscriptions, recurrent payments, or bookings.

As a PHP programmer, you will likely need to manipulate dates/times.

Getting Started with a Third-Party Library? Really?

While it's generally a good practice to stick with native APIs to master your craft and understand how the language works, let's be pragmatic.

Carbon is a powerful library that extends DateTimeInterface.

It provides useful helpers for manipulating both existing and new date objects:

// Tomorrow
CarbonImmutable::now()->add(1, 'day');

// Copy instance from another API
$dateTime = new \DateTime('first day of January 2025');
$carbon = Carbon::instance($dateTime);

// Parsing values
$date = Carbon::parse('2050-01-01 12:34:00', 'UTC');

Back to Basics

Carbon extends the native API, but the DateTime object already provides tools for calculating dates and times:

$date = new DateTime('2024-07-23');
$date->add(new DateInterval('P10D'));
echo $date->format('Y-m-d');

$date2 = new DateTime('2024-08-03');
$interval = $date->diff($date2);
echo $interval->format('%R%a days');

You can pass strings to obtain specific outputs or calculate intervals and periods.

So, Why Use Additional Layers Like Carbon?

Better readability

$yesterday = Carbon::yesterday();
$today = Carbon::today();
$now = Carbon::now();
$tomorrow = Carbon::tomorrow();
$futureDate = Carbon::today()->addDays(21)->format('Y-m-d');

if ($now->isEndOfDay()) {
    // Some code
}

The library is convenient and robust for date comparisons, which are prone to various errors.

Easy localization

Carbon handles locales conveniently:

$now = Carbon::now()->locale('fr_FR');
echo $now->monthName;

Handling Overflows

The default PHP DateTime behavior can be misleading when adding or subtracting months. It can overflow!

While you may need that behavior at times, Carbon provides better control:

Carbon::useMonthsOverflow(false);
Carbon::resetMonthsOverflow();

You can also configure overflows in each method when manipulating years or months (e.g, subMonthsNoOverflow, addMonthsWithOverflow).

Unit Testing Dates

Dates can be problematic in unit tests due to variability.

Carbon offers advanced capabilities for mocking, ensuring tests remain consistent and reliable.

This prevents random errors that can break your CI/CD pipelines.

How to Avoid Common Pitfalls with Dates/Times

Whether you use Carbon or not, there are practical ways to reduce potential bugs and inconsistencies:

Don't Silence Errors

Recent versions of PHP introduced better date/time exceptions, allowing you to catch unexpected inputs more consistently.

However, implementations can sometimes silence bad errors:

$dateInput = '2dsds';
$timestamp = strtotime($dateInput);
echo date('Y-m-d', $timestamp); // Defaults back to 1970-01-01

The following code is not an improvement, even if it uses a DateTime object:

$dateInput = '2024-02-30'; // Invalid date (February has 28 days, 29 at most)
$date = new DateTime($dateInput);
echo $date->format('l \t\h\e jS F'); // Outputs "Friday the 1st March"

So, always validate dates/times:

$dateInput = '2dsds';
$timestamp = strtotime($dateInput);

if (false === $timestamp) {
    throw new InvalidArgumentException();
}

echo date('Y-m-d', $timestamp);

And, check inputs deeply:

$format = 'Y-m-d';
$dateInput = '2024-02-30';
$dateInfo = date_parse($dateInput);
if (!checkdate($dateInfo['day'], $dateInfo['month'], $dateInfo['year'])) {
    throw new InvalidArgumentException();
}

$date = DateTimeImmutable::createFromFormat($format, $dateInput);
echo $date->format('l \t\h\e jS F');

Prevent Accidental Mutations

DateTimeImmutable or CarbonImmutable cannot be changed after creation. Most of the time, you don't need to mutate the initial date.

If other parts of the code rely on that instance, you might introduce nasty bugs.

Immutable formats prevent such side effects and are usually better for readability and testing.

Don't Neglect Timezones

Neglecting timezones is risky:

PHP: Understanding Time Zones

spO0q ・ Aug 4

#php #beginners #programming

If you don't specify the default timezone in your app, the server will determine it.

However, your application may be deployed on servers in different timezones.

You may also struggle with complexities like daylight saving time or storage formats (e.g., UTC vs. local time), which may be less painful with a library that encourages good practices.

Wrap Up

The native API allows advanced manipulations of dates and times, while Carbon extends it beautifully.

PHP developers can leverage this additional layer to simplify calculations and improve readability.

Regardless of whether you use it, ensure you understand the default behavior of the native PHP DateTime object.