Skip to content

Commit 5ded6d1

Browse files
alganetalganet
committed
Introduce DateFormatter and NumberFormatter
Introduce formatters for the typical use cases of formatting numbers and dates. Internally, those formatters use `number_format` and `date_format` respectively. If a date cannot be parsed in runtime, the formatter will return the input unmodified. Similarly, if some input is not numeric, the numeric formatter will return it unchanged.
1 parent 99829b7 commit 5ded6d1

7 files changed

Lines changed: 807 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22
SPDX-FileCopyrightText: (c) Respect Project Contributors
33
SPDX-License-Identifier: ISC
44
SPDX-FileContributor: Henrique Moody <henriquemoody@gmail.com>
5+
SPDX-FileContributor: Alexandre Gomes Gaigalas <alganet@gmail.com>
56
-->
67

78
# Respect\StringFormatter
@@ -41,6 +42,8 @@ echo f::create()
4142
| [MaskFormatter](docs/MaskFormatter.md) | Range-based string masking with Unicode support |
4243
| [PatternFormatter](docs/PatternFormatter.md) | Pattern-based string filtering with placeholders |
4344
| [PlaceholderFormatter](docs/PlaceholderFormatter.md) | Template interpolation with placeholder replacement |
45+
| [NumberFormatter](docs/NumberFormatter.md) | Number formatting with thousands and decimal separators |
46+
| [DateFormatter](docs/DateFormatter.md) | Date and time formatting with flexible parsing |
4447

4548
## Contributing
4649

‎docs/DateFormatter.md‎

Lines changed: 225 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,225 @@
1+
<!--
2+
SPDX-FileCopyrightText: (c) Respect Project Contributors
3+
SPDX-License-Identifier: ISC
4+
SPDX-FileContributor: Alexandre Gomes Gaigalas <alganet@gmail.com>
5+
-->
6+
7+
# DateFormatter
8+
9+
The `DateFormatter` parses and reformats date and time strings using flexible input parsing and configurable output formats.
10+
11+
## Usage
12+
13+
### Basic Usage
14+
15+
```php
16+
use Respect\StringFormatter\DateFormatter;
17+
18+
$formatter = new DateFormatter();
19+
20+
echo $formatter->format('2024-01-15 10:30:45');
21+
// Outputs: 2024-01-15 10:30:45
22+
```
23+
24+
### Custom Format
25+
26+
```php
27+
use Respect\StringFormatter\DateFormatter;
28+
29+
$formatter = new DateFormatter('m/d/Y');
30+
31+
echo $formatter->format('2024-01-15');
32+
// Outputs: 01/15/2024
33+
```
34+
35+
### European Format
36+
37+
```php
38+
use Respect\StringFormatter\DateFormatter;
39+
40+
$formatter = new DateFormatter('d.m.Y');
41+
42+
echo $formatter->format('2024-01-15');
43+
// Outputs: 15.01.2024
44+
```
45+
46+
### With Month Names
47+
48+
```php
49+
use Respect\StringFormatter\DateFormatter;
50+
51+
$formatter = new DateFormatter('l, F j, Y');
52+
53+
echo $formatter->format('2024-01-15');
54+
// Outputs: Monday, January 15, 2024
55+
```
56+
57+
### ISO 8601 Format
58+
59+
```php
60+
use Respect\StringFormatter\DateFormatter;
61+
62+
$formatter = new DateFormatter('c');
63+
64+
echo $formatter->format('2024-01-15T10:30:45');
65+
// Outputs: 2024-01-15T10:30:45+00:00
66+
```
67+
68+
## API
69+
70+
### `DateFormatter::__construct`
71+
72+
- `__construct(string $format = 'Y-m-d H:i:s')`
73+
74+
Creates a new formatter instance with the specified date format.
75+
76+
**Parameters:**
77+
78+
- `$format`: PHP date format string (default: `'Y-m-d H:i:s'`)
79+
80+
### `format`
81+
82+
- `format(string $input): string`
83+
84+
Parses the input date string and formats it according to the formatter's configuration.
85+
86+
If the input cannot be parsed as a date, it is returned unchanged without modification.
87+
88+
**Parameters:**
89+
90+
- `$input`: A date string in any format parseable by `DateTime`
91+
92+
**Returns:** The formatted date string if the input can be parsed; the input unchanged otherwise
93+
94+
## Behavior
95+
96+
### Parseable Input
97+
98+
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.
99+
100+
### Unparsable Input
101+
102+
When input cannot be parsed as a date, the formatter returns it unchanged:
103+
104+
```php
105+
$formatter = new DateFormatter('Y-m-d');
106+
107+
// Valid date input
108+
echo $formatter->format('2024-01-15'); // Outputs: 2024-01-15
109+
110+
// Unparsable input is returned unchanged
111+
echo $formatter->format('invalid date'); // Outputs: invalid date
112+
echo $formatter->format('2024-13-45'); // Outputs: 2024-13-45 (invalid month/day)
113+
echo $formatter->format('N/A'); // Outputs: N/A
114+
```
115+
116+
## Input Formats
117+
118+
The formatter uses PHP's `DateTime` constructor which supports various input formats:
119+
120+
### Standard Date Formats
121+
122+
| Format | Example |
123+
|---------------|-----------------------|
124+
| ISO 8601 | `2024-01-15T10:30:45` |
125+
| MySQL | `2024-01-15 10:30:45` |
126+
| US Format | `01/15/2024` |
127+
| European | `15.01.2024` |
128+
| Unix Timestamp| `1705331445` |
129+
130+
### Relative Formats
131+
132+
| Input | Description |
133+
|-------------|---------------------|
134+
| `now` | Current date/time |
135+
| `today` | Current date |
136+
| `tomorrow` | Next day |
137+
| `yesterday` | Previous day |
138+
| `next week` | Date in next week |
139+
| `last month`| Date in last month |
140+
141+
## Output Format Strings
142+
143+
### Year
144+
145+
| Format | Description | Example |
146+
|--------|--------------------------|---------|
147+
| `Y` | 4-digit year | 2024 |
148+
| `y` | 2-digit year | 24 |
149+
150+
### Month
151+
152+
| Format | Description | Example |
153+
|--------|--------------------------|---------|
154+
| `m` | 2-digit month | 01 |
155+
| `n` | Month without leading 0 | 1 |
156+
| `F` | Full month name | January |
157+
| `M` | 3-letter month | Jan |
158+
159+
### Day
160+
161+
| Format | Description | Example |
162+
|--------|--------------------------|---------|
163+
| `d` | 2-digit day | 15 |
164+
| `j` | Day without leading 0 | 15 |
165+
| `D` | 3-letter weekday | Mon |
166+
| `l` | Full weekday name | Monday |
167+
168+
### Time
169+
170+
| Format | Description | Example |
171+
|--------|--------------------------|---------|
172+
| `H` | 24-hour format (00-23) | 10 |
173+
| `h` | 12-hour format (01-12) | 10 |
174+
| `i` | Minutes (00-59) | 30 |
175+
| `s` | Seconds (00-59) | 45 |
176+
| `A` | AM/PM uppercase | AM |
177+
| `a` | am/pm lowercase | am |
178+
179+
### Other
180+
181+
| Format | Description | Example |
182+
|--------|--------------------------|---------------------------------|
183+
| `c` | ISO 8601 | 2024-01-15T10:30:45+00:00 |
184+
| `r` | RFC 2822 | Mon, 15 Jan 2024 10:30:45 +0000 |
185+
| `U` | Unix timestamp | 1705331445 |
186+
| `z` | Day of year (0-365) | 014 |
187+
| `W` | Week number (ISO-8601) | 02 |
188+
189+
## Examples
190+
191+
### Common Formats
192+
193+
| Description | Format | Input | Output |
194+
|-------------------|------------------|-------------------------|-----------------------------------|
195+
| US Date | `m/d/Y` | `2024-01-15` | `01/15/2024` |
196+
| European Date | `d.m.Y` | `2024-01-15` | `15.01.2024` |
197+
| Time Only | `H:i:s` | `2024-01-15 10:30:45` | `10:30:45` |
198+
| Long Format | `l, F j, Y` | `2024-01-15` | `Monday, January 15, 2024` |
199+
| Short Format | `M d, Y` | `2024-01-15` | `Jan 15, 2024` |
200+
| ISO 8601 | `c` | `2024-01-15T10:30:45` | `2024-01-15T10:30:45+00:00` |
201+
| RFC 2822 | `r` | `2024-01-15 10:30:45` | `Mon, 15 Jan 2024 10:30:45 +0000` |
202+
203+
### Parsing Flexibility
204+
205+
The formatter intelligently parses various input formats:
206+
207+
```php
208+
$formatter = new DateFormatter('Y-m-d');
209+
210+
// All produce the same output: 2024-01-15
211+
echo $formatter->format('2024-01-15'); // ISO format
212+
echo $formatter->format('01/15/2024'); // US format
213+
echo $formatter->format('15.01.2024'); // European format
214+
echo $formatter->format('January 15, 2024'); // Long format
215+
```
216+
217+
### Relative Date Processing
218+
219+
```php
220+
$formatter = new DateFormatter('l, F j, Y');
221+
222+
echo $formatter->format('now'); // Today's date
223+
echo $formatter->format('tomorrow'); // Tomorrow's date
224+
echo $formatter->format('yesterday'); // Yesterday's date
225+
```

0 commit comments

Comments
 (0)