[6.x] Improved Timezone Handling

[duncanmcclean]

This pull request makes a number of improvements to how Statamic handles timezones.

To avoid updating content in existing sites unnecessarily, Statamic will continue to store dates using the application timezone, just like it does right now in v5.

Then, for new sites, we recommend keeping the app timezone as UTC and simply changing the display_timezone option in config/statamic/system.php instead.

Optional timezone migration

Initially we were going to force migration of content into UTC, but went back on that idea after we decided too much content would get touched. However the migrator tool worked pretty well so we'll leave it available for anyone who wants to change the app timezone. This command will update date fields throughout your content.

php please migrate-dates-to-utc America/New_York

You should replace America/New_York with whatever timezone you want to convert dates from (eg. your old app timezone). We highly recommend taking a backup of your site before running the command, especially if you're storing content in a database.

After the command has run, you can change your app timezone to UTC.

Control Panel

The Date fieldtype will convert the date/timestamp to UTC, which'll then get localized to the user's timezone using JavaScript.

Obviously, the opposite happens when the user updates the date/time. It gets converted back from the user's timezone to UTC. Then, when the entry is saved, it'll be converted back to the application's timezone.

Frontend

When the Date fieldtype is augmented, it will return a UTC Carbon instance. Only when you output a date in your template will it be converted using a new display_timezone option in config/statamic/system.php.

'display_timezone' => null,

When null, it'll fall back to the app timezone.

Note

The timezone conversion will only take place when the request passes through Statamic's Localize middleware.

You should ensure you're applying the Localize middleware (or preferably the entire statamic.web middleware group) to any custom routes in your application.

Modifiers

When using modifiers on Date fields (or any other Carbon instances), it's important to know that they'll be working with the UTC values, rather than "localized" value.

There are two ways you can workaround this:

• You can add the timezone modifier (or tz for short) to the start of your modifier "chain". It'll convert the Carbon instance to the "display timezone" you have configured:

  - {{ start_date | modify_date('+ day') | format('Y-m-d') }}
  + {{ start_date | tz | modify_date('+ day') | format('Y-m-d') }}

• Alternatively, you can enable the localize_dates_in_modifiers option in your config/statamic/system.php config file, which'll automatically convert dates to your display timezone before reaching any modifiers:

  'localize_dates_in_modifiers' => true,
  

  To ease the v6 upgrade process, this setting has been enabled by default for existing sites.

REST API & GraphQL API

Dates returned by the REST API & GraphQL API will always in UTC. This allows you to transform them, as needed, on your frontend (or wherever you're consuming the API).

---

Closes #4270.
Closes #5748.
Closes #8339.
Closes #10896.
Replaces #8636.
Replaces #10166
Replaces #11388.
Closes statamic/ideas#842.

Associated PRs

• SSG: [4.x] Improved Timezone Handling ssg#197
• Docs: [6.x] UTC Dates docs#1637
• Eloquent Driver: [5.x] Cast entry dates to UTC eloquent-driver#398

[sylvesterdamgaard]

🎉