The DateTime object is defined in PHP versions 5.2 and greater. Full documentation can be found at php.net/datetime.

PHP's print_r(), Devel module's dpm(), and similar functions and most debuggers are not able to show the properties of DateTime objects. The date_format() function provides a good alternate method to debug DateTime objects. An example of its usage follows, including some common DateTime manipulation functions;

<?php
// Create a DateTime object for 11 November 2008, 5pm, Chicago time.
$date = date_create('2008-11-11 17:00:00', timezone_open('America/Chicago'));

// Find out what time it is in New York.
date_timezone_set($date, timezone_open('America/New_York'));

// Now move it ahead to the following Tuesday.
date_modify($date, '+1 Tuesday');

// Print out the result.
print date_format($date, 'l r');
// "Tuesday Tue, 18 Nov 2008 18:00:00 -0500"
?>

The Date API provides a helper function, date_make_date($string, $timezone, $type), where $string is a unixtimestamp, an ISO date, or a string like YYYY-MM-DD HH:MM:SS, $timezone is the name of the timezone this date is in, and $type is the type of date it is (DATE_UNIX, DATE_ISO, or DATE_DATETIME). It creates and return a date object set to the right date and timezone.