DateTime::createFromFormat

date_create_from_format

Returns new DateTime object formatted according to the specified format

&reftitle.description;

&style.oop;

public static `DateTime` `DateTime::createFromFormat` `string` `format` `string` `time` `DateTimeZone` `timezone`

&style.procedural;

`DateTime` `date_create_from_format` `string` `format` `string` `time` `DateTimeZone` `timezone`

Returns new DateTime object formatted according to the specified format.

&reftitle.parameters;

`format`

- The format that the passed in `string` should be in. See the formatting options below. In most cases, the same letters as for the `date` can be used.

  ## The following characters are recognized in the `format` parameter string

  `format` character | Description | Example parsable values
  Day | --- | ---
  `d` and `j` | Day of the month, 2 digits with or without leading zeros | `01` to `31` or `1` to `31`
  `D` and `l` | A textual representation of a day | `Mon` through `Sun` or `Sunday` through `Saturday`
  `S` | English ordinal suffix for the day of the month, 2 characters. It's ignored while processing. | `st`, `nd`, `rd` or `th`.
  `z` | The day of the year (starting from 0) | `0` through `365`
  Month | --- | ---
  `F` and `M` | A textual representation of a month, such as January or Sept | `January` through `December` or `Jan` through `Dec`
  `m` and `n` | Numeric representation of a month, with or without leading zeros | `01` through `12` or `1` through `12`
  Year | --- | ---
  `Y` | A full numeric representation of a year, 4 digits | Examples: `1999` or `2003`
  `y` | A two digit representation of a year | Examples: `99` or `03`
  Time | --- | ---
  `a` and `A` | Ante meridiem and Post meridiem | `am` or `pm`
  `g` and `h` | 12-hour format of an hour with or without leading zero | `1` through `12` or `01` through `12`
  `G` and `H` | 24-hour format of an hour with or without leading zeros | `0` through `23` or `00` through `23`
  `i` | Minutes with leading zeros | `00` to `59`
  `s` | Seconds, with leading zeros | `00` through `59`
  `u` | Microseconds (up to six digits) | Example: `45`, `654321`
  Timezone | --- | ---
  `e`, `O`, `P` and `T` | Timezone identifier, or difference to UTC in hours, or difference to UTC with colon between hours and minutes, or timezone abbreviation | Examples: `UTC`, `GMT`, `Atlantic/Azores` or `+0200` or `+02:00` or `EST`, `MDT`
  Full Date/Time | --- | ---
  `U` | Seconds since the Unix Epoch (January 1 1970 00:00:00 GMT) | Example: `1292177455`
  Whitespace and Separators | --- | ---
  `` (space) | One space or one tab | Example: ``
  `#` | One of the following separation symbol: `;`, `:`, `/`, `.`, `,`, `-`, `(` or `)` | Example: `/`
  `;`, `:`, `/`, `.`, `,`, `-`, `(` or `)` | The specified character. | Example: `-`
  `?` | A random byte | Example: `^` (Be aware that for UTF-8 characracters you might need more than one `?`. In this case, using `*` is probably what you want instead)
  `*` | Random bytes until the next separator or digit | Example: `*` in `Y-*-d` with the string `2009-aWord-08` will match `aWord`
  `!` | Resets all fields (year, month, day, hour, minute, second, fraction and timzone information) to the Unix Epoch | Without `!,` all fields will be set to the current date and time.
  `|` | Resets all fields (year, month, day, hour, minute, second, fraction and timzone information) to the Unix Epoch if they have not been parsed yet | `Y-m-d|` will set the year, month and day to the information found in the string to parse, and sets the hour, minute and second to 0.
  `+` | If this format specifier is present, trailing data in the string will not cause an error, but a warning instead | Use `DateTime::getLastErrors` to find out whether trailing data was present.

  Unrecognized characters in the format string will cause the parsing to fail and an error message is appended to the returned structure. You can query error messages with `DateTime::getLastErrors`.

  If `format` does not contain the character `!` then portions of the generated time which are not specified in `format` will be set to the current system time.

  If `format` contains the character `!`, then portions of the generated time not provided in `format`, as well as values to the left-hand side of the `!`, will be set to corresponding values from the Unix epoch.

  The Unix epoch is 1970-01-01 00:00:00 UTC.

`time`

- String representing the time.

`timezone`

- A `DateTimeZone` object representing the desired time zone.

  If `timezone` is omitted and `time` contains no timezone, the current timezone will be used.

  The `timezone` parameter and the current timezone are ignored when the `time` parameter either contains a UNIX timestamp (e.g. `946684800`) or specifies a timezone (e.g. `2010-01-28T15:00:00+02:00`).

&reftitle.returnvalues;

Returns a new DateTime instance&return.falseforfailure;.

&reftitle.examples;

### `DateTime::createFromFormat` example

&style.oop;

    <?php
    $date = DateTime::createFromFormat('j-M-Y', '15-Feb-2009');
    echo $date->format('Y-m-d');
    ?>

&style.procedural;

    <?php
    $date = date_create_from_format('j-M-Y', '15-Feb-2009');
    echo date_format($date, 'Y-m-d');
    ?>

&examples.outputs;

    2009-02-15

### Intricacies of `DateTime::createFromFormat`

    <?php
    echo 'Current time: ' . date('Y-m-d H:i:s') . "\n";

    $format = 'Y-m-d';
    $date = DateTime::createFromFormat($format, '2009-02-15');
    echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";

    $format = 'Y-m-d H:i:s';
    $date = DateTime::createFromFormat($format, '2009-02-15 15:16:17');
    echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";

    $format = 'Y-m-!d H:i:s';
    $date = DateTime::createFromFormat($format, '2009-02-15 15:16:17');
    echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";

    $format = '!d';
    $date = DateTime::createFromFormat($format, '15');
    echo "Format: $format; " . $date->format('Y-m-d H:i:s') . "\n";
    ?>

&example.outputs.similar;

    Current time: 2010-04-23 10:29:35
    Format: Y-m-d; 2009-02-15 10:29:35
    Format: Y-m-d H:i:s; 2009-02-15 15:16:17
    Format: Y-m-!d H:i:s; 1970-01-15 15:16:17
    Format: !d; 1970-01-15 00:00:00

&reftitle.seealso;

- `DateTime::__construct`
- `DateTime::getLastErrors`
- `checkdate`
- `strptime`