Carbon 3 createFromTimestamp undocumented timezone change

[tomsommer]

In Carbon 3, createFromTimestamp() no-longer applies the default timezone.

createFromTimestamp(time()) returns without timezone, while in Carbon 2 the default timezone is applied. If this is an intended change then it's not very well documented.

Basically createFromTimestampUTC in Carbon 2 is now createFromTimestamp in Carbon 3.

[kylekatarnls]

Hello, they are not identical because createFromTimestampUTC has only 1 parameter, while createFromTimestamp has a second $timezone parameter so you can explicitly use:

Carbon::createFromTimestamp(time(), date_default_timezone_get());

The change is that we no longer assume that null means date_default_timezone_get(). And there are multiple reasons for that.

While you're switching from Carbon 2 to 3, I suggest you carefully consider them as it's possibly a good occasion to also change some settings that might help on the long run:

• timestamp is by definition: "Number of seconds since January 1st 1970 00:00 UTC" so for the sake of explicitness it makes sense to get an UTC date-time out of a timestamp value, then to change explictly the timezone with ->setTimezone()
• Having a default timezone other than UTC on server side does not make sense 99% of the cases, most of the application built using Carbon server requests that can potentially come from users if different timezone that whatever is configured on the server, if it does not, there is still chances that it would in the future, or that code would be reused later in another application that would. So there is a huge advantage to assume that server-side application should be timezone-agnostic and almost no advantage to assume the opposite. So when assuming server will serve request for devices/users that won't have all the same timezone, then the good value for default timezone is UTC (I.E. date_default_timezone_set('UTC')) as it's a neutral value, it has no DST, it has a fixed offset, while if you pick any arbitrary city timezone, it's dependent on government to change the offset if needed, and because it's arbitrary over standard, you have to bridge it when communicating with other systems.
• timezone is not a server thing, it's a client/user thing, application should not then apply them globally, they should read it from user config/request header, use it only for processes that need to be user-contextualized and use UTC for the rest. When exchanging JSON data with front-end app, server typically don't even need to care about user timezone, because front app can format date-time as UTC before sending and build local time objects from UTC date-time string they would receive.
• date_default_timezone_get() is driven by php.ini config if date_default_timezone_set is not (or not yet) called, which make it less reliable because it prevents you PHP code to be standalone, instead your application depends on how PHP is configured in order to behave as expected. If date_default_timezone_get() is never called you don't risk to break the app if you migrate it to another server that would be located somewhere else and so timezone config potentially different.

It's a though topic I tried to explain more in details here:

Always Use UTC Dates And Times

[tomsommer]

Appreciate the explanation, I still think this requires a substantial highlight in the upgrade docs

[kylekatarnls]

Documentation updated.

[ywisax]

It will break the createFromTimestamp's behavior. I think it will be better to change the sign of createFromTimestamp, like mark the second parameter as required.

[kylekatarnls]

Carbon 3 is already live for ~1 year. Making the timezone required in 4.x is a possibility but I'm not sure it's worth yet another breaking change.

[ywisax]

Carbon 3 is already live for ~1 year. Making the timezone required in 4.x is a possibility but I'm not sure it's worth yet another breaking change.

In the current PHP ecosystem, nesbot/carbon is de facto the best date management library. Therefore, a large number of community libraries rely on it and trust its API design.

I've seen in quite a few popular community libraries that their dependency settings for nesbot/carbon are: "nesbot/carbon": "^2.0|^3.0".
When the behavior of the createFromTimestamp function changes, developers, based on their trust in the API design of nesbot/carbon, will hardly realize that the same code will produce inconsistent results.

I can find a large number of libraries and code with such compatibility issues by searching on GitHub at https://github.com/search?q=%22Carbon%3A%3AcreateFromTimestamp%22+language%3APHP&type=code&p=1. For example:
https://github.com/corcel/woocommerce
https://github.com/spatie/laravel-directory-cleanup
https://github.com/spatie/laravel-mail-preview

So, it's really a troublesome thing indeed...