Guide · Open source

How to use Carbon: PHP date and time tutorial

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Carbon is a PHP library that extends PHP's built-in DateTime class with shorter, more readable methods. This guide shows you how to install it with Composer, then work with the current time, add and subtract dates, compare them and format output. It is written for developers who already know a little PHP.

Carbonbriannesbitt/Carbon · ★ 16.6k · MIT Install options & downloads

Quick start

1Check prerequisites. Make sure PHP and Composer are installed on your machine.
2Install the package. Run composer require nesbot/carbon in your project folder.
3Load the autoloader. Add require 'vendor/autoload.php' to the top of your script.
4Import the class. Add use Carbon\Carbon; so you can call Carbon methods.
5Create and change dates. Use Carbon::now(), addDay() or subWeek() to work with dates.
6Format output. Use diffForHumans() or isoFormat() and locale() to display text for readers.

Install Carbon with Composer

Carbon is installed as a package through Composer, so you need PHP and Composer on your machine first. Run the install command from your project folder.

After installing, load Composer's autoloader in your script before using Carbon. The README also shows a version constraint you can place in composer.json.

Prerequisites: PHP and Composer
Add the package with the command shown in the code block

$ composer require nesbot/carbon

Get the current date and time

Carbon::now() returns the current moment as a Carbon object. You can pass a timezone name to get the time in that zone, and convert the result to a string when you need one.

use Carbon\Carbon;

echo Carbon::now()->toDateTimeString();
echo Carbon::now('America/Vancouver');

Add, subtract and create dates

Methods such as addDay() and subWeek() change a date in a short, readable way. Carbon::createFromDate() and Carbon::createFromTime() build dates from parts, and a timezone can be given as the last argument.

Use addDay() for tomorrow and subWeek() for a week ago
Use createFromDate(year, month, day) to build a specific date
Pass a timezone such as 'Europe/London' when creating a time

$tomorrow = Carbon::now()->addDay();
$lastWeek = Carbon::now()->subWeek();
$birthday = Carbon::createFromDate(1975, 5, 21);
$noon = Carbon::createFromTime(12, 0, 0, 'Europe/London');

Compare dates and measure differences

Carbon can compare two dates with methods such as gte(). The README notes that comparisons are always done in UTC. The diffInDays() method measures the gap in days. Called without a parameter, it counts from now; called with a date, it counts from the first date to the second.

Negative values mean the other date is in the future, as shown in the README example.

gte() checks whether one date is greater than or equal to another
diffInDays() without a parameter measures from now
diffInDays($other) measures from the object to $other

$epoch = Carbon::createFromTimestamp(0);
$days = $epoch->diffInDays();
$gap = $epoch->diffInDays(Carbon::create(2038, 1, 19, 3, 14, 7, 'GMT'));

Show human-readable times and local formats

diffForHumans() turns a time into text such as '2 minutes ago'. The README says Carbon supports over 200 languages and over 500 regional variants. Use locale() before the output method to switch language, and isoFormat() to format a date with a locale-aware pattern.

diffForHumans() gives text such as '2 minutes ago'
locale('zh_CN') or locale('fr_FR') changes the language of the output
isoFormat('LLLL') produces a long, localised date

echo Carbon::now()->subMinutes(2)->diffForHumans();
echo Carbon::now()->subMinutes(2)->locale('zh_CN')->diffForHumans();
echo Carbon::parse('2019-07-23 14:51')->locale('fr_FR')->isoFormat('LLLL');

Mock the current time in tests

To test code that depends on the current time, set a fixed moment with Carbon::setTestNow(). Calling it with no argument restores normal behaviour. The README uses this to check a date without waiting for real time to pass.

Call setTestNow() with a Carbon date to fix 'now'
Call setTestNow() with no arguments to reset it

Carbon::setTestNow(Carbon::createFromDate(2000, 1, 1));
// ... run your test code ...
Carbon::setTestNow();

What people use it for

Showing '2 minutes ago' style labels for comments or posts
Calculating the number of days between two dates
Displaying dates in several languages on a multilingual site
Freezing the current time in unit tests with setTestNow()

Frequently asked questions

How do I install Carbon?

Install Carbon with Composer by running composer require nesbot/carbon in your project folder. The README also shows a composer.json entry that requires nesbot/carbon. You then load vendor/autoload.php in your script.

Is Carbon free to use?

Carbon is open-source and released under the MIT licence. Check the LICENSE file in the repository for the full terms.

What are the requirements for Carbon?

Carbon needs PHP and Composer for the recommended install. It only works in PHP, so non-PHP projects cannot use it.

Can I use Carbon without Composer?

Yes. The README says you can download the latest release from GitHub, put the files in a directory in your project, and require the autoload.php file. Composer is recommended, but it is not mandatory.

What are the alternatives to Carbon?

Comparable options named in this analysis are PHP's built-in DateTime class, Chronos and Jenssegers Date. Built-in DateTime needs no extra dependency, which suits single simple calculations.

How do I show dates in another language with Carbon?

Call locale() with a language code such as 'fr_FR' before diffForHumans() or isoFormat(). The README says Carbon supports over 200 languages and over 500 regional variants.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Carbon suits PHP developers who handle dates often, need readable time differences or multilingual output, or want to mock the current time in tests. If you only need one simple date calculation or cannot use Composer or manual file loading, the built-in PHP DateTime class is the simpler choice, and non-PHP developers should look elsewhere.

Install options & downloads