[11.x] Upgrade to Carbon v3

[kylekatarnls]

• Update Carbon to ^3@dev, if needed 1 Laravel version could allow ^2.72.2 || ^3@dev to transition but would also implies some complexity to support both
• Removed setTestNow override, in Carbon 3 it's synchronized already to the PSR clock
• Noticing createFromId PHPDoc says it accepts Uuid and Ulid but code fails if not string so I changed it to respect its PHPDoc

[driesvints]

Hey @kylekatarnls. When were you planning on releasing v3? It'd be best that's done before Laravel v11 is released.

[kylekatarnls]

I planned to check with you if Laravel would need any adjustment in this version so to try to detect as much as possible before releasing to stable.

On my side it's packed and if you don't have any major concern, I will release a beta tag this week.

Here are the main changes for 3.0

• Drop PHP < 8.1
  • Drop PHP 8.0 briannesbitt/Carbon#2810
  • Drop PHP < 8.0 briannesbitt/Carbon#2385
  • ⬆️ Drop Symfony < 4.4 and PHP < 7.2.5 support briannesbitt/Carbon#2070
  • Drop fixes for old PHP versions briannesbitt/Carbon#2346
• Add generic unitOfUnit and unitsInUnit getters briannesbitt/Carbon#2885
• ⬆️ Make CarbonPeriod extend DatePeriod briannesbitt/Carbon#1752
• Return null instead of false briannesbitt/Carbon#2340
• ⭐ Instantiating CarbonInterval with 0 makes forHumans() report "1s" briannesbitt/Carbon#2035
• ⭐ Create empty interval by default briannesbitt/Carbon#2079
• ♻️ Cleanup diffIn* diffInReal* floatDiffIn* floatDiffInReal* briannesbitt/Carbon#2119
  • diffIn* will use the floatDiffInReal* behavior, all other variants will be removed
• Week methods only work with local translator, not default locale briannesbitt/Carbon#1967
• Support decimal numbers in addRealUnit briannesbitt/Carbon#2347
• Allow to add and subtract decimal numbers of any unit briannesbitt/Carbon#2519
• ⭐ Enums for week days, months and units briannesbitt/Carbon#2701
• ⭐ Isolate settings in factories briannesbitt/Carbon#2345

[driesvints]

@kylekatarnls Right. I'll let @taylorotwell review the code changes here.

Just want to say that we'll need a stable Carbon v3 tag before we release Laravel v11 otherwise we can't get this in. We can't release with a dev stability package.

[kylekatarnls]

Fair enough 👍 I'll have a first round of beta release hoping for some people to try it.

[taylorotwell]

@kylekatarnls can you summarize any significant breaking changes for us?

[kylekatarnls]

diffIn*

Yes, the most impactful change is in diffIn* methods. They were returning positive integer by default, they will now return float:

$after = Carbon::now()->addSeconds(2);
$before = Carbon::now();

var_dump($after->diffInSeconds($before));

This was: int(1) in Carbon 2
This is: double(-1.999508) in Carbon 3

In Carbon 3, using (int) $after->diffInSeconds($before, true) or (int) abs($after->diffInSeconds($before)) allows to get explicitly an absolute and truncated value, so the same result as in v2.

Strong typing

Strong typing added in many method parameters will disallow so usages that was never meant to be supported such as bool or null in comparison methods:
In Carbon v2 the following return arbitrary results (despite it emits E_USER_DEPRECATED notices):

var_dump($date->eq(false)); // false
var_dump($date->gte(false)); // true
var_dump($date->gt(false)); // true
var_dump($date->eq(null)); // false
var_dump($date->gte(null)); // true
var_dump($date->gt(null)); // true

In Carbon v3, PHPDoc is moving to real types so any of this will throw a TypeError, it expects DateTimeInterface or string to be passed.

falsable => nullable

create, createFromFormat , createFromIsoFormat, createFromLocaleFormat and createFromLocaleIsoFormat returned Carbon|false, it's now Carbon|null (unlocking ?-> chaining and ?? throw error handling).

Removal of some deprecated methods

setUtf8 are formatLocalized removed. formatLocalized depends on OS language package and relies on setlocale() + strftime() (the last will be removed from PHP itself). ->isoFormat() should be used instead which is embedded translation files (so one can rely to get the same translation everywhere) and is linked to Carbon locale (The current object locale that can be set with $date->locale('de') or if not set, the global one that Laravel is already setting using Carbon::setLocale('de')). And setUtf8 is no longer needed since formatLocalized is the only method that possibly had non-UTF-8 output. This might be a BC for some users, but I doubt that any Laravel package is using that internally.

No other point should be relevant for Laravel.

[crynobone]

@kylekatarnls can you merge/rebase master from upstream to this PR.

[driesvints]

@taylorotwell let's merge this one and then we can see if any of the nightly builds of our packages will fail.

[kylekatarnls]

I'm looking at the tests, I think it's on Carbon-side and needs a new beta tag

[driesvints]

Thanks @kylekatarnls. Converted this to draft until we figured that one out.

[GrahamCampbell]

Giving the CI a kick to pick up the new carbon tag.

[kylekatarnls]

@driesvints Is it fine to merge with beta version so some people having Laravel on dev-master will start to test Carbon 3 in Laravel context and may raise points not covered by tests? Of course I would release a stable tag before Laravel tags its own stable version 11

[driesvints]

@kylekatarnls yep, perfect 👍