Laravel

Datetime

Carbonapi

Format Dates with Carbon in Laravel

Format Dates with Carbon in Laravel

Introduction

Carbon is a PHP library that provides a simple API extension for DateTime. It provides a fluent, easy-to-use API for creating and manipulating dates and times.

Installation

It comes out of the box with Laravel; but you can easily install it with composer also:

composer require nesbot/carbon

Global Helpers

use Carbon\Carbon;
// ...

Carbon::now(); // current date and time
now(); // equivalent to Carbon::now() in Laravel

Carbon::today(); // today's date
today(); // equivalent to Carbon::today() in Laravel 

Carbon Parse

use Carbon\Carbon;
// ...

Carbon::parse('2023-01-01'); // Carbon instance for 2023-01-01 00:00:00

Carbon::parse('Monday of this week'); // Monday of this week

Carbon::parse('first day of January 2023'); // first day of January 2023

Carbon::parse('first day of this month'); // first day of this month

Carbon::parse('first day of next month'); // first day of next month

Carbon::parse('first day of last month'); // first day of last month

Carbon::parse('last day of last month'); // last day of last month

Getters

use Carbon\Carbon;
// ...

$now = Carbon::now(); // Assume $now is 2023-01-01 00:00:00

$now->year; // 2023
$now->month; // 1
$now->dayOfWeek; // 1
$now->englishDayOfWeek; // Sunday
$now->englishMonth; // January
$now->tzName; // UTC
$now->dst; // daylight saving time: false

For more getters, check out the Carbon documentation HERE

String Formatting

use Carbon\Carbon;
// ...

$now = Carbon::now(); // Assume $now is 2023-01-01 00:00:00

$now->toDateString(); // 2023-01-01
$now->toFormattedDateString(); // Jan 1, 2023
$now->toTimeString(); // 00:00:00
$now->toDateTimeString(); // 2023-01-01 00:00:00
$now->toDayDateTimeString(); // Mon, Jan 1, 2023 12:00 AM
$now->toCookieString(); // Monday, 01-Jan-2023 00:00:00 UTC
$now->toIso8601String(); // 2023-01-01T00:00:00+00:00
$now->format('Y-m-d'); // 2023-01-01: format('<FORMAT>') accepts a custom format compatible with PHP date()

For more string formatting, check out the Carbon documentation HERE

Comparisons

use Carbon\Carbon;
// ...

$now = Carbon::now();
$yesterday = Carbon::yesterday();
$tomorrow = Carbon::tomorrow();

$now > $yesterday; // true
$now > $tomorrow; // false
$now->greaterThan($yesterday); // true
$now->gt($yesterday); // true
$now->between($yesterday,$tomorrow); // true
$now->isWeekend(); // true/false depending $now
$now->isWeekday(); // true/false depending $now

For more comparison, check out the Carbon documentation HERE

Modifiers

use Carbon\Carbon;
// ...

$now = Carbon::now(); // Assume $now is 2023-01-01 00:00:00
$yesterday = Carbon::yesterday();
$tomorrow = Carbon::tomorrow();

$now->addDay(); // 2023-01-02 00:00:00
$now->addDays(2); // 2023-01-03 00:00:00
$now->subDay(); // 2022-12-31 00:00:00
$yesterday->addWeek(); // 2023-01-08 00:00:00
$yesterday->subWeek(); // 2022-12-25 00:00:00
$now->addMonth(); // 2023-02-01 00:00:00
$now->subMonth(); // 2022-12-01 00:00:00
$now->firstOfMonth(Carbon::MONDAY); // 2023-01-02 00:00:00
$now->nthOfMonth(2,Carbon::MONDAY); // 2023-01-09 00:00:00

For more modifiers, check out the Carbon documentation HERE

Diff For Humans

use Carbon\Carbon;
// ...

$now = Carbon::now(); // Assume $now is 2023-01-01 00:00:00
$yesterday = Carbon::yesterday();
$tomorrow = Carbon::tomorrow();

$now->diffForHumans(); // 
$yesterday->diffForHumans(); // 1 day ago
$tomorrow->diffForHumans(); // 1 day from now
$yesterday->shortAbsoluteDiffForHumans(); // 1d ago
$yesterday->longAbsoluteDiffForHumans(); // 1 day
$yesterday->diffForHumans(['options' => Carbon::ONE_DAY_WORDS]); // yesterday

For more diff for humans, check out the Carbon documentation HERE

Testing

In Laravel testing sometimes you want to modify the time returned by now(); in such scenarios you can use the Laravel's testing helpers for time that are build on top of Carbon. Let's see this in action:

use Illuminate\Support\Carbon;
// ...

public function testTimeCanBeManipulated(){}
    // Travel into the future...
    $this->travel(5)->milliseconds();
    $this->travel(5)->seconds();
    $this->travel(5)->minutes();
    $this->travel(5)->hours();
    $this->travel(5)->days();
    $this->travel(5)->weeks();
    $this->travel(5)->years();

    // Freeze time and resume normal time after executing closure...
    $this->freezeTime(function (Carbon $time) {
        // ...
    });

    // Travel into the past...
    $this->travel(-5)->hours();

    // Travel to an explicit time...
    $this->travelTo(now()->subHours(6));

    // Return back to the present time...
    $this->travelBack();
}
// ...

If you like the article, please share it with your friends and colleagues. You can follow me on Twitter @brainlet_ali for ideas and questions.

Happy coding!