Carbon is a small library for date and time manipulation in PHP. It relies on and extends the core DateTime class, adding helpful methods for a significantly saner experience.

In this article, we’ll take a look at some basic usage examples, and then use it in a real project.

Introduction

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.

Example Uses

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

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 setLocale method:

Carbon::setLocale('de');
echo Carbon::now()->addYear()->diffForHumans();    // in 1 Jahr

Interval

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.

Implementation

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 getDate and getEstimatedDate methods. Otherwise, they’ll return strings as usual.

Continue reading %Suggesting Carbon with Composer – Date and Time the Right Way%

Source: SitePoint