CarbonImmutable Class: Why You Would Need It

All of you probably use the Carbon class in Laravel for date/time operations. But have you heard about CarbonImmutable? It may rescue you from one potential bug. Let me explain its use case in this short tutorial.

Let's say we have a variable, which is a carbon instance. It shows 9 am.

$now = now()
= Illuminate\Support\Carbon @1701769227 {#8589
date: 2023-12-05 09:40:27.931975 UTC (+00:00),

The now() function is a Carbon\Carbon::now() shorter version.

For example, let's introduce a variable $threeHoursLater.

$threeHoursLater = $now->addHours(3);
= Illuminate\Support\Carbon @1701780027 {#8589
date: 2023-12-05 12:40:27.931975 UTC (+00:00),

We can see the result three hours later, at 12 pm.

But now, what if from the original $now you want to create a four hours later. We expect the result to be 13 because 9+4, but we get 16.

$threeHoursLater = $now->addHours(4);
= Illuminate\Support\Carbon @1701794427 {#8589
date: 2023-12-05 16:40:27.931975 UTC (+00:00),

It is because of how Carbon works. It not only assigns the value to the new variable but also changes the original object. This means whatever new operation you launch on the same object, it will be from the last change of that object.

That's why there is a separate class called CarbonImmutable. Assigning the now value, you won't see any difference.

$now = Carbon\CarbonImmutable::now();
= Carbon\CarbonImmutable @1701770010 {#8596
date: 2023-12-05 09:53:30.203054 UTC (+00:00),

After adding three hours later, we see the same 12 pm result.

$threeHoursLater = $now->addHours(3);
= Carbon\CarbonImmutable @1701780810 {#8590
date: 2023-12-05 12:53:30.203054 UTC (+00:00),

But the main difference is setting the third variable after four hours.

$threeHoursLater = $now->addHours(4);
= Carbon\CarbonImmutable @1701784410 {#8586
date: 2023-12-05 13:53:30.203054 UTC (+00:00),

Now, we get the expected result. Now, the operation is done from the original $now variable value.

If you want to watch this lesson as a video, there is a YouTube video Carbon VS CarbonImmutable in Laravel: Avoid Potential Errors.


Or remember always use a ->copy() method.


That is impossible. Humans do make mistakes and they can be costly :) That's why immutable exists!


Damn i have to say that is annoying behaviour on laravels side. Why is the immutable class not default? i think i have to change some code in my app.. :/


because of tradeoff... Immutable will have some extra performance cost..

Like our articles?

Become a Premium Member for $129/year or $29/month
What else you will get:
  • 56 courses (1011 lessons, total 46 h 42 min)
  • 77 long-form tutorials (one new every week)
  • access to project repositories
  • access to private Discord

Recent Premium Tutorials