New method DrupalDateTime::getPhpDateTime() exposes PHP's native \DateTime object

Summary

A new method, \Drupal\Core\Datetime\DrupalDateTime::getPhpDateTime(), allows developers to retrieve the a clone of the wrapped native \DateTime object from a DrupalDateTime object. The method is also on the parent class, DateTimePlus.

Before

As per the New Datetime API:

Drupal core and contributed modules should use the DrupalDateTime class in preference to the PHP DateTime class or to functions like date(), gmdate(), strtotime(), etc.

However, sometimes you need to work directly with the \DateTime object when dealing with libraries that expect \DateTimeInterface. The required object is only available as protected property, and therefore not accessible.

After

When working with a stand-alone DrupalDateTime object:

// Initialize a new DrupalDateTime object.
$utc = new \DateTimeZone('UTC');
$date = DrupalDateTime::createFromFormat('Y-m-d H:i:s', '2017-05-23 22:58:00', $utc, ['langcode' => 'en']);
// Retrieve a clone of PHP's native \DateTime object.
/** @var \DateTime $native_date */
$native_date = $date->getPhpDateTime();

When working with a date field:

// Retrieve the field's date value as cloned native \DateTime object.
/** @var \DateTime $field_date */
$field_date = $entity->get('field_some_date')->date->getPhpDateTime();