Datetime and Datelist elements now obey #date_timezone attribute

Summary

• The Datetime and Datelist element have a #date_timezone property which affects the timezone used to display and interpret dates.
• Previously the basic idea was that if you already had a date when creating an element, you should set the timezone on the date object and that would be used, while if there was no existing date then what you specified for #date_timezone would be used.
• The timezone logic did not always work as the docs said it should. For details, see #2799987: Datetime and Datelist element's timezone handling is fragile, buggy and wrongly documented.
• The logic has now been changed so that #date_timezone is always obeyed. It defaults to drupal_get_user_timezone().

Before

Developers needed to set a timezone on the date object passed by the #default_value attribute:

$element = [
  '#type' => 'datetime',
  '#default_value => $some_date->setTimezone(new DateTimeZone('Europe/London')),
  '#date_timezone => 'Europe/London',
];

After

The #date_timezone attribute is sufficient:

$element = [
  '#type' => 'datetime',
  '#default_value' => $some_date,
  '#date_timezone => 'Europe/London',
];

Any timezone set on the date object in the #default_value attribute is ignored.

Backwards compatibility

In almost all cases of robustly working code, this does not lead to a change of behavior, because the element previously only worked properly in a limited range of circumstances, in all of which the behavior is unchanged.

However, there is a possible break of backwards-compatibility for those extending the elements. If an element extends the Datetime or Datelist elements then it's timezone handling may change, particularly if it either

1. depends on the default value of #date_timezone being an empty string (it is now drupal_get_user_timezone(), or
2. modifies the timezone handling logic in one but not both of the valueCallback() and processDatetime() methods (and therefore will interact unpredictably with the now-changed logic in the other non-overridden method).