class FormatDate in Drupal 8

Same name and namespace in other branches

9 core/modules/migrate/src/Plugin/migrate/process/FormatDate.php \Drupal\migrate\Plugin\migrate\process\FormatDate

Converts date/datetime from one format to another.

Available configuration keys

from_format: The source format string as accepted by \DateTime::createFromFormat.
to_format: The destination format.
timezone: (deprecated) String identifying the required time zone, see DateTimePlus::__construct(). The timezone configuration key is deprecated in Drupal 8.4.x and will be removed before Drupal 9.0.0, use from_timezone and to_timezone instead.
from_timezone: String identifying the required source time zone, see DateTimePlus::__construct().
to_timezone: String identifying the required destination time zone, see DateTimePlus::__construct().
settings: keyed array of settings, see DateTimePlus::__construct().

Configuration keys from_timezone and to_timezone are both optional. Possible input variants:

Both from_timezone and to_timezone are empty. Date will not be converted and be treated as date in default timezone.
Only from_timezone is set. Date will be converted from timezone specified in from_timezone key to the default timezone.
Only to_timezone is set. Date will be converted from the default timezone to the timezone specified in to_timezone key.
Both from_timezone and to_timezone are set. Date will be converted from timezone specified in from_timezone key to the timezone specified in to_timezone key.

Examples:

Example usage for date only fields (DateTimeItemInterface::DATE_STORAGE_FORMAT):


process:
  field_date:
    plugin: format_date
    from_format: 'm/d/Y'
    to_format: 'Y-m-d'
    source: event_date

If the source value was '01/05/1955' the transformed value would be 1955-01-05.

Example usage for datetime fields (DateTimeItemInterface::DATETIME_STORAGE_FORMAT):


process:
  field_time:
    plugin: format_date
    from_format: 'm/d/Y H:i:s'
    to_format: 'Y-m-d\TH:i:s'
    source: event_time

If the source value was '01/05/1955 10:43:22' the transformed value would be 1955-01-05T10:43:22.

Example usage for datetime fields with a timezone and settings:


process:
  field_time:
    plugin: format_date
    from_format: 'Y-m-d\TH:i:sO'
    to_format: 'Y-m-d\TH:i:s'
    from_timezone: 'America/Managua'
    to_timezone: 'UTC'
    settings:
      validate_format: false
    source: event_time

If the source value was '2004-12-19T10:19:42-0600' the transformed value would be 2004-12-19T10:19:42. Set validate_format to false if your source value is '0000-00-00 00:00:00'.

Plugin annotation


@MigrateProcessPlugin(
  id = "format_date"
)

Hierarchy

class \Drupal\Component\Plugin\PluginBase implements DerivativeInspectionInterface, PluginInspectionInterface
- class \Drupal\Core\Plugin\PluginBase uses DependencySerializationTrait, MessengerTrait, StringTranslationTrait
  - class \Drupal\migrate\ProcessPluginBase implements MigrateProcessInterface
    class \Drupal\migrate\Plugin\migrate\process\FormatDate

Expanded class hierarchy of FormatDate

File

core/modules/migrate/src/Plugin/migrate/process/FormatDate.php, line 97

Namespace

Drupal\migrate\Plugin\migrate\process

View source

class FormatDate extends ProcessPluginBase {

  /**
   * {@inheritdoc}
   */
  public function transform($value, MigrateExecutableInterface $migrate_executable, Row $row, $destination_property) {
    if (empty($value) && $value !== '0' && $value !== 0) {
      return '';
    }

    // Validate the configuration.
    if (empty($this->configuration['from_format'])) {
      throw new MigrateException('Format date plugin is missing from_format configuration.');
    }
    if (empty($this->configuration['to_format'])) {
      throw new MigrateException('Format date plugin is missing to_format configuration.');
    }
    $fromFormat = $this->configuration['from_format'];
    $toFormat = $this->configuration['to_format'];
    if (isset($this->configuration['timezone'])) {
      @trigger_error('Configuration key "timezone" is deprecated in 8.4.x and will be removed before Drupal 9.0.0, use "from_timezone" and "to_timezone" instead. See https://www.drupal.org/node/2885746', E_USER_DEPRECATED);
      $from_timezone = $this->configuration['timezone'];
      $to_timezone = isset($this->configuration['to_timezone']) ? $this->configuration['to_timezone'] : NULL;
    }
    else {
      $system_timezone = date_default_timezone_get();
      $default_timezone = !empty($system_timezone) ? $system_timezone : 'UTC';
      $from_timezone = isset($this->configuration['from_timezone']) ? $this->configuration['from_timezone'] : $default_timezone;
      $to_timezone = isset($this->configuration['to_timezone']) ? $this->configuration['to_timezone'] : $default_timezone;
    }
    $settings = isset($this->configuration['settings']) ? $this->configuration['settings'] : [];

    // Older versions of Drupal where omitting certain granularities (also known
    // as "collected date attributes") resulted in invalid timestamps getting
    // stored.
    if ($fromFormat === 'Y-m-d\\TH:i:s') {
      $value = str_replace([
        '-00-00T',
        '-00T',
      ], [
        '-01-01T',
        '-01T',
      ], $value);
    }

    // Attempts to transform the supplied date using the defined input format.
    // DateTimePlus::createFromFormat can throw exceptions, so we need to
    // explicitly check for problems.
    try {
      $transformed = DateTimePlus::createFromFormat($fromFormat, $value, $from_timezone, $settings)
        ->format($toFormat, [
        'timezone' => $to_timezone,
      ]);
    } catch (\InvalidArgumentException $e) {
      throw new MigrateException(sprintf("Format date plugin could not transform '%s' using the format '%s' for destination '%s'. Error: %s", $value, $fromFormat, $destination_property, $e
        ->getMessage()), $e
        ->getCode(), $e);
    } catch (\UnexpectedValueException $e) {
      throw new MigrateException(sprintf("Format date plugin could not transform '%s' using the format '%s' for destination '%s'. Error: %s", $value, $fromFormat, $destination_property, $e
        ->getMessage()), $e
        ->getCode(), $e);
    }
    return $transformed;
  }

}

Members

Name	Modifiers	Type	Description	Overrides
DependencySerializationTrait::$_entityStorages	protected	property	An array of entity type IDs keyed by the property name of their storages.
DependencySerializationTrait::$_serviceIds	protected	property	An array of service IDs keyed by property name used for serialization.
DependencySerializationTrait::__sleep	public	function		1
DependencySerializationTrait::__wakeup	public	function		2
FormatDate::transform	public	function	Performs the associated process. Overrides ProcessPluginBase::transform
MessengerTrait::$messenger	protected	property	The messenger.	29
MessengerTrait::messenger	public	function	Gets the messenger.	29
MessengerTrait::setMessenger	public	function	Sets the messenger.
PluginBase::$configuration	protected	property	Configuration information passed into the plugin.	1
PluginBase::$pluginDefinition	protected	property	The plugin implementation definition.	1
PluginBase::$pluginId	protected	property	The plugin_id.
PluginBase::DERIVATIVE_SEPARATOR		constant	A string which is used to separate base plugin IDs from the derivative ID.
PluginBase::getBaseId	public	function	Gets the base_plugin_id of the plugin instance. Overrides DerivativeInspectionInterface::getBaseId
PluginBase::getDerivativeId	public	function	Gets the derivative_id of the plugin instance. Overrides DerivativeInspectionInterface::getDerivativeId
PluginBase::getPluginDefinition	public	function	Gets the definition of the plugin implementation. Overrides PluginInspectionInterface::getPluginDefinition	3
PluginBase::getPluginId	public	function	Gets the plugin_id of the plugin instance. Overrides PluginInspectionInterface::getPluginId
PluginBase::isConfigurable	public	function	Determines if the plugin is configurable.
PluginBase::__construct	public	function	Constructs a \Drupal\Component\Plugin\PluginBase object.	92
ProcessPluginBase::multiple	public	function	Indicates whether the returned value requires multiple handling. Overrides MigrateProcessInterface::multiple	3
StringTranslationTrait::$stringTranslation	protected	property	The string translation service.	1
StringTranslationTrait::formatPlural	protected	function	Formats a string containing a count of items.
StringTranslationTrait::getNumberOfPlurals	protected	function	Returns the number of plurals supported by a given language.
StringTranslationTrait::getStringTranslation	protected	function	Gets the string translation service.
StringTranslationTrait::setStringTranslation	public	function	Sets the string translation service to use.	2
StringTranslationTrait::t	protected	function	Translates a string to the current language or to a given language.

You are here