Skip to content

Latest commit

 

History

History
229 lines (155 loc) · 6.92 KB

DateFormatter.md

File metadata and controls

229 lines (155 loc) · 6.92 KB

DateFormatter

The DateFormatter parses and reformats date and time strings using flexible input parsing and configurable output formats.

Usage

Basic Usage

use Respect\StringFormatter\DateFormatter;

$formatter = new DateFormatter();

echo $formatter->format('2024-01-15 10:30:45');
// Outputs: 2024-01-15 10:30:45

Custom Format

use Respect\StringFormatter\DateFormatter;

$formatter = new DateFormatter('m/d/Y');

echo $formatter->format('2024-01-15');
// Outputs: 01/15/2024

European Format

use Respect\StringFormatter\DateFormatter;

$formatter = new DateFormatter('d.m.Y');

echo $formatter->format('2024-01-15');
// Outputs: 15.01.2024

With Month Names

use Respect\StringFormatter\DateFormatter;

$formatter = new DateFormatter('l, F j, Y');

echo $formatter->format('2024-01-15');
// Outputs: Monday, January 15, 2024

ISO 8601 Format

use Respect\StringFormatter\DateFormatter;

$formatter = new DateFormatter('c');

echo $formatter->format('2024-01-15T10:30:45+00:00');
// Outputs: 2024-01-15T10:30:45+00:00

API

DateFormatter::__construct

  • __construct(string $format = 'Y-m-d H:i:s')

Creates a new formatter instance with the specified date format.

Parameters:

  • $format: PHP date format string (default: 'Y-m-d H:i:s')

format

  • format(string $input): string

Parses the input date string and formats it according to the formatter's configuration.

If the input cannot be parsed as a date, it is returned unchanged without modification.

Parameters:

  • $input: A date string in any format parseable by DateTime

Returns: The formatted date string if the input can be parsed; the input unchanged otherwise

Behavior

Strict Date Validation

The formatter uses a two-level validation approach:

  1. Exception handling: Catches DateMalformedStringException thrown by invalid format strings
  2. Error checking: Uses DateTime::getLastErrors() to detect parsing errors and warnings

This ensures even dates that appear parseable but have parsing issues are rejected.

Valid Input

The formatter uses PHP's DateTime constructor which supports various date formats including ISO 8601, MySQL format, relative formats (like "now", "tomorrow"), and other flexible formats. Valid input must parse without errors or warnings.

$formatter = new DateFormatter('Y-m-d');

// Valid date input
echo $formatter->format('2024-01-15');          // Outputs: 2024-01-15
echo $formatter->format('2024-01-15 10:30:45'); // Outputs: 2024-01-15
echo $formatter->format('January 15, 2024');    // Outputs: 2024-01-15

Invalid Input

When input cannot be parsed as a date or has parsing errors/warnings, the formatter returns it unchanged:

$formatter = new DateFormatter('Y-m-d');

// Invalid input is returned unchanged
echo $formatter->format('invalid date');       // Outputs: invalid date
echo $formatter->format('this-is-not-a-date'); // Outputs: this-is-not-a-date
echo $formatter->format('N/A');                // Outputs: N/A

Input Formats

The formatter uses PHP's DateTime constructor which supports various input formats:

Standard Date Formats

Format Example
ISO 8601 2024-01-15T10:30:45
MySQL 2024-01-15 10:30:45
US Format 01/15/2024
European 15.01.2024
Unix Timestamp @1705331445

Output Format Strings

Year

Format Description Example
Y 4-digit year 2024
y 2-digit year 24

Month

Format Description Example
m 2-digit month 01
n Month without leading 0 1
F Full month name January
M 3-letter month Jan

Day

Format Description Example
d 2-digit day 15
j Day without leading 0 15
D 3-letter weekday Mon
l Full weekday name Monday

Time

Format Description Example
H 24-hour format (00-23) 10
h 12-hour format (01-12) 10
i Minutes (00-59) 30
s Seconds (00-59) 45
A AM/PM uppercase AM
a am/pm lowercase am

Other

Format Description Example
c ISO 8601 2024-01-15T10:30:45+00:00
r RFC 2822 Mon, 15 Jan 2024 10:30:45 +0000
U Unix timestamp 1705331445
z Day of year (0-365) 014
W Week number (ISO-8601) 02

Examples

Common Formats

Description Format Input Output
US Date m/d/Y 2024-01-15 01/15/2024
European Date d.m.Y 2024-01-15 15.01.2024
Time Only H:i:s 2024-01-15 10:30:45 10:30:45
Long Format l, F j, Y 2024-01-15 Monday, January 15, 2024
Short Format M d, Y 2024-01-15 Jan 15, 2024
ISO 8601 c 2024-01-15T10:30:45 2024-01-15T10:30:45+00:00
RFC 2822 r 2024-01-15 10:30:45 Mon, 15 Jan 2024 10:30:45 +0000

Parsing Flexibility

The formatter intelligently parses various input formats:

$formatter = new DateFormatter('Y-m-d');

// All produce the same output: 2024-01-15
echo $formatter->format('2024-01-15');           // ISO format
echo $formatter->format('01/15/2024');           // US format
echo $formatter->format('15.01.2024');           // European format
echo $formatter->format('January 15, 2024');     // Long format

Relative Date Processing

$formatter = new DateFormatter('l, F j, Y');

echo $formatter->format('now');       // Today's date
echo $formatter->format('tomorrow');  // Tomorrow's date
echo $formatter->format('yesterday'); // Yesterday's date