====== Request for Comments: DateTime::__toString ======
  * Version: 1.0
  * Date: 2012-09-01
  * Author: Will Fitch <willfitch@php.net>
  * Status: Inactive

===== Introduction =====

The purpose behind this RFC is to introduce converting the DateTime object to a string representation. This is a commonly requested feature in bug reports (the most recent #62911).  The issue has been coming to decisions based on the default pattern to use. In the initial patch, the ISO-8601 format has been used. 

==== Syntactical Implementation ====
The syntactical implementation takes both procedural and OOP approaches into account.  The following changes have been made:

=== Methods Added ===

string DateTime::__toString(void)
void DateTime::setDefaultPattern(string $pattern)
string DateTime::getDefaultPattern(void)

=== Functions Added ===

void date_default_pattern_set(DateTime $date, string $pattern)
string date_default_pattern_get(DateTime $date)

=== Examples ===

**OO Style**
<code php>
<?php

$date = new DateTime('2012-09-01 02:43:00');
echo $date; // Outputs 2012-09-01T02:43:00-0500

$date->setDefaultPattern('Y-m-d');
echo $date; // Outputs 2012-09-01

echo $date->getDefaultPattern(); // Outputs "Y-m-d"
?>
</code>

**Procedural Style**
<code php>
<?php

$date = date_create('2012-09-01 02:43:00');
echo $date; // Outputs 2012-09-01T02:43:00-0500

date_default_pattern_set($date, 'Y-m-d');
echo $date; // Outputs 2012-09-01

echo date_default_pattern_get($date); // Outputs "Y-m-d"
?>
</code>

**Debug Output**
<code php>
<?php
$date = new DateTime('2012-09-01 02:43:00');
print_r($date);

$date->setDefaultPattern('Y-m-d');
print_r($date);
?>
</code>

This will output the following:
<code>
DateTime Object
(
    [date] => 2012-09-01 02:43:00
    [timezone_type] => 3
    [timezone] => America/Chicago
)
DateTime Object
(
    [date] => 2012-09-01 02:43:00
    [timezone_type] => 3
    [timezone] => America/Chicago
    [default_pattern] => Y-m-d
)
</code>

As you can see, the default pattern is managed via a class property called "default_pattern".
===== Patch =====

The patch for this can be found at https://github.com/downloads/willfitch/php-src/date-tostring.diff. 

===== Changelog =====

  - 2012-09-01 Initial RFC written and published