Suggesting Carbon with Composer – Date and Time the Right Way
In this article, we’ll take a look at some basic usage examples, and then use it in a real project.
Carbon is just a class which is designed to be used instead of DateTime. Due to extending DateTime, all DateTime methods are available to users of Carbon. Additionally, it implements a
__toString method, allowing users to put it in place of string representations of date and time as well.
It can easily be installed with Composer:
composer require nesbot/carbon
Let’s see some example uses, as presented in their excellent documentation.
The easiest way to get started with Carbon is to just pass a human readable date string into its constructor, along with an optional timezone – if the timezone is omitted, the one set by the current PHP installation will be used.
$carbon = new Carbon('first day of next week');
It can also be instantiated from strings, timestamps, even other instances of DateTime or even Carbon. The instance can be copied with the
copy() method, for efficient cloning.
From there, we have access to a smorgasbord of helper checkers and getters:
$carbon->isWeekend(); $carbon->isFuture(); $carbon->isLeapYear(); $carbon->year; $carbon->month; $carbon->daysInMonth; $carbon->weekOfYear;
The package also exposes static methods for creating new instances quickly:
echo Carbon::now()->addYear()->diffForHumans(); // in 1 year
Even birthdays can be checked, as we can see by this example from the docs:
$born = Carbon::createFromDate(1987, 4, 23); $noCake = Carbon::createFromDate(2014, 9, 26); $yesCake = Carbon::createFromDate(2014, 4, 23); $overTheHill = Carbon::now()->subYears(50); var_dump($born->isBirthday($noCake)); // bool(false) var_dump($born->isBirthday($yesCake)); // bool(true) var_dump($overTheHill->isBirthday()); // bool(true) -> default compare it to today!
Localization is also supported, so that output can be given in any desired language installed on the machine powering the PHP app. Note that you do need to install the necessary locales for this to work – refer to your operating system’s documentation for details on how to do that.
To localize date and time strings, the standard PHP function
setlocale can be used:
setlocale(LC_TIME, 'German'); echo $dt->formatLocalized('%A %d %B %Y'); // Mittwoch 21 Mai 1975
To localize the
diffForHumans method which outputs a human-readable difference in time, the class offers its own
Carbon::setLocale('de'); echo Carbon::now()->addYear()->diffForHumans(); // in 1 Jahr
A CarbonInterval class is also provided, which is an extension of DateInterval. Self-descriptively, it holds interval values, just like the base class, but adds helper methods on top. As per examples:
echo CarbonInterval::year(); // 1 year echo CarbonInterval::months(3); // 3 months echo CarbonInterval::days(3)->seconds(32); // 3 days 32 seconds echo CarbonInterval::weeks(3); // 3 weeks echo CarbonInterval::days(23); // 3 weeks 2 days echo CarbonInterval::create(2, 0, 5, 1, 1, 2, 7); // 2 years 5 weeks 1 day 1 hour 2 minutes 7 seconds
Note that Carbon as a whole is exceptionally well documented – for a full reference of methods and usage examples, please see their docs.
In this section, we’ll upgrade the Diffbot PHP Client to optionally support Carbon. The plan is as follows: if the user has the library installed, then the Article entity and Post entity will return Carbon instances instead of date strings from their
getEstimatedDate methods. Otherwise, they’ll return strings as usual.
Continue reading %Suggesting Carbon with Composer – Date and Time the Right Way%