API-First DX of "date" and "date range" fields: add 'datetime_iso8601' @DataType (de)normalizer using RFC3339 timestamps with timezones

Per #2824717-62: Add a format constraint to DateTimeItem to provide REST error message and -63, this is blocked on that issue.

isolates interface from implementation

+1!

The denormalizer will help future proof any changes to field storage internals.

+1! I'd like to add: it's okay to expose "default Entity/Field API internal behavior by default", but it's not ideal. Not every REST client has the ability to step through PHP code with Xdebug. So we should A) give error feedback appropriate for REST clients, B) try to meet expectations of "HTTP developers", not "PHP developers".

So, I wholeheartedly agree with #3, and especially with its conclusion, which explains it very well:

I also think it would be beneficial to add a normalize (with BC) the responses to the same \DateTime::RFC3339 format, again for consistency. Again, the outside world doesn't need to care about how we store stuff and all timestamps/dates in responses would be the same and we can mess with internals w/o breaking APIs.

So, to prevent cross-contamination and to allow people to not have to have HAL enabled, we need two Normalizer services in Drupal\datetime\Normalizer, with the appropriate priorities?

Correct, that'd be in line with what #2768651: Let TimestampItem (de)normalize to/from RFC3339 timestamps, not UNIX timestamps, for better DX did.

However… we realized in #2901429: JSON API Extras @ResourceFieldEnhancer plugins should also be applied to filter values and #2860350: Document why JSON API only supports @DataType-level normalizers that adding @FieldType-plugin-level normalizers is a bad idea, because they need to be written for not only serialization.module (default normalization) and hal.module (HAL normalization), but also jsonapi.module (JSON:API normalization) and any other alternative normalization. So that is unfortunate.

The solution lies in not adding more @FieldType-plugin-level normalizers, but instead working at the @DataType-plugin level. Because then it's automatically picked up by all normalizations.

So based on #8, we'd want this issue to add a \Drupal\Core\TypedData\Plugin\DataType\DateTimeIso8601 normalizer. Then it'll work everywhere automatically, in all 3 normalizations mentioned in #8 :)

We should also look at the normalization of fields configured to be "date-only". That would solve #2870609: [PP-1] Core Date field is serialized as String instead of timestamp/long.

Without this, and especially without test coverage, how to deal with DateTimeItem fields via core's REST API and contrib's JSON API is ill-defined, and may change without us knowing (== BC break).

Bumping to major for that reason.

If this would do what #8 + #9 say, then #2918554: [PP-1] Let DateRangeItem (de)normalize to/from RFC3339 becomes a duplicate.

Because:

\Drupal\datetime\Plugin\Field\FieldType\DateTimeItem

  public static function propertyDefinitions(FieldStorageDefinitionInterface $field_definition) {
    $properties['value'] = DataDefinition::create('datetime_iso8601')
      ->setLabel(t('Date value'))
      ->setRequired(TRUE);

    $properties['date'] = DataDefinition::create('any')
      ->setLabel(t('Computed date'))
      ->setDescription(t('The computed DateTime object.'))
      ->setComputed(TRUE)
      ->setClass('\Drupal\datetime\DateTimeComputed')
      ->setSetting('date source', 'value');

    return $properties;
  }

The only non-internal field here is value, which uses the datetime_iso8601 @DataType plugin.

\Drupal\datetime_range\Plugin\Field\FieldType\DateRangeItem

  public static function propertyDefinitions(FieldStorageDefinitionInterface $field_definition) {
    $properties['value'] = DataDefinition::create('datetime_iso8601')
      ->setLabel(t('Start date value'))
      ->setRequired(TRUE);

    $properties['start_date'] = DataDefinition::create('any')
      ->setLabel(t('Computed start date'))
      ->setDescription(t('The computed start DateTime object.'))
      ->setComputed(TRUE)
      ->setClass(DateTimeComputed::class)
      ->setSetting('date source', 'value');

    $properties['end_value'] = DataDefinition::create('datetime_iso8601')
      ->setLabel(t('End date value'))
      ->setRequired(TRUE);

    $properties['end_date'] = DataDefinition::create('any')
      ->setLabel(t('Computed end date'))
      ->setDescription(t('The computed end DateTime object.'))
      ->setComputed(TRUE)
      ->setClass(DateTimeComputed::class)
      ->setSetting('date source', 'end_value');

    return $properties;
  }

The only non-internal fields here are value and end_value, both of which also use the datetime_iso8601 @DataType plugin.

IOW: adding a \Drupal\Core\TypedData\Plugin\DataType\DateTimeIso8601 (de)normalizer would fix the DX of both field types!

Added to #2905563: REST: top priorities for Drupal 8.5.x.

Over at #2926508-18: Add DateTimeNormalizer+TimestampNormalizer, deprecate TimestampItemNormalizer: @DataType-level normalizers are reusable by JSON:API, I'm proposing to deal with several issues at the same time, because it turns out there's a single elegant solution that will fix it all! For now, just postponing this, and not marking it as a duplicate.

Great :)

Let's keep this open for now, until #2926508: Add DateTimeNormalizer+TimestampNormalizer, deprecate TimestampItemNormalizer: @DataType-level normalizers are reusable by JSON:API matures a bit more. Perhaps we'll want to reduce scope there, and move part of that patch to this issue.

I'm pretty sure #2926508-24: Add DateTimeNormalizer+TimestampNormalizer, deprecate TimestampItemNormalizer: @DataType-level normalizers are reusable by JSON:API means we can close this!

See #2913941 and specifically #2913941-6: [PP-1] Fields using the DateTimeIso8601 @DataType are missing an explicit time zone: missing a normalizer, which is the JSON API equivalent to this issue. If we'd solve this, then we'd also solve it for JSON API. Doing that over at #2926508-33: Add DateTimeNormalizer+TimestampNormalizer, deprecate TimestampItemNormalizer: @DataType-level normalizers are reusable by JSON:API.

#2926508: Add DateTimeNormalizer+TimestampNormalizer, deprecate TimestampItemNormalizer: @DataType-level normalizers are reusable by JSON:API fixed this, and added explicit tests! 🎉