[6.x] Store dates as UTC

[duncanmcclean]

This pull request ensures that dates in Statamic are always stored as UTC, then converted to the relevant timezone when they're being displayed.

Storage

For the most part, we aren't changing the format dates are saved in, just the timezone. Previously, dates and times were stored in whatever timezone you entered them in, but now they're always stored in UTC:

title: Flat Camp 2024
location: Rome, Italy
- start_date: 2024-06-11 16:00
- end_date: 2024-06-14 11:00
+ start_date: 2024-06-11 15:00
+ end_date: 2024-06-14 10:00

^ In this example: Italy is 1 hour ahead of UTC. 🇮🇹

One thing worth noting is that time will now always be saved alonside dates, even when the time_enabled option is disabled. This helps to ensure that "midnight" is relative to whatever timezone your users are in.

Control Panel

The Date fieldtype now converts the UTC date/time value to your operating system's timezone, and vice versa. It'll always send the UTC value back to the server.

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 to the display_timezone configured in config/statamic/system.php.

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).

Update Script

During the update process, an update script will be run to convert dates in your content to UTC.

The update script will also add two config options to your config/statamic/system.php config file:

• display_timezone
• localize_dates_in_modifiers

You can read more about these config options under the "Frontend" heading above.

Once the update script has completed, we strongly recommend changing your app's timezone to UTC. You can configure the timezone in your config/app.php config file:

/*
 |--------------------------------------------------------------------------
 | Application Timezone
 |--------------------------------------------------------------------------
 |
 | Here you may specify the default timezone for your application, which
 | will be used by the PHP date and date-time functions. The timezone
 | is set to "UTC" by default as it is suitable for most use cases.
 |
 */

- 'timezone' => 'America/New_York',
+ 'timezone' => 'UTC',

---

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

Goes alongside statamic/eloquent-driver#398.

[sylvesterdamgaard]

🎉