Skip to content

Commit 21effcc

Browse files
bjoern-hempelbjoern-hempel
committed
Refactoring and README.md updates
1 parent 644b6f4 commit 21effcc

File tree

5 files changed

+184
-63
lines changed

5 files changed

+184
-63
lines changed

‎README.md‎

Lines changed: 74 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -5,42 +5,65 @@ DateTime or DateTimeImmutable classes which return the time
55
range. Can be used e.g. excellently for command line
66
arguments and options to make database queries with.
77

8-
## Usage
8+
## Examples / Usage
99

1010
```php
1111
use Ixnode\PhpDateParser\DateParser;
1212
```
1313

14-
### Date parser
14+
### Date parser (`UTC`)
1515

1616
```php
17-
$dateParser = (new DateParser('2023-07-01'))->formatFrom('Y-m-d H:i:s');
17+
print (new DateParser('2023-07-01'))->formatFrom('Y-m-d H:i:s');
1818
// 2023-07-01 00:00:00
1919

20-
$dateParser = (new DateParser('2023-07-01'))->formatTo('Y-m-d H:i:s');
20+
print (new DateParser('2023-07-01'))->formatTo('Y-m-d H:i:s');
2121
// 2023-07-01 23:59:59
2222
```
2323

24-
### Word parser
24+
### Word parser (`UTC`)
25+
26+
* Imagine that now is the time: `2023-07-07 12:34:56`
2527

2628
```php
27-
$dateParser = (new DateParser('today'))->formatFrom('Y-m-d H:i:s');
29+
print (new DateParser('today'))->formatFrom('Y-m-d H:i:s');
2830
// 2023-07-07 00:00:00
2931

30-
$dateParser = (new DateParser('today'))->formatTo('Y-m-d H:i:s');
32+
print (new DateParser('today'))->formatTo('Y-m-d H:i:s');
3133
// 2023-07-07 23:59:59
3234
```
3335

3436
### Date parser with timezones
3537

38+
* Input: `America/New_York`
39+
* Output: `Europe/Berlin`
40+
3641
```php
37-
$dateParser = (new DateParser('<2023-07-01', 'America/New_York'))->formatFrom('Y-m-d H:i:s', 'Europe/Berlin');
42+
/* Parses given date time from timezone America/New_York; Output to timezone Europe/Berlin */
43+
print (new DateParser('<2023-07-01', 'America/New_York'))->formatFrom('Y-m-d H:i:s', 'Europe/Berlin');
3844
// null
3945
40-
$dateParser = (new DateParser('<2023-07-01', 'America/New_York'))->formatTo('Y-m-d H:i:s', 'Europe/Berlin');
46+
/* Parses given date time from timezone America/New_York; Output to timezone Europe/Berlin */
47+
print (new DateParser('<2023-07-01', 'America/New_York'))->formatTo('Y-m-d H:i:s', 'Europe/Berlin');
4148
// 2023-07-01 05:59:59
4249
```
4350
51+
### Working with `DateRange` class
52+
53+
```php
54+
/* Parses given date time from timezone America/New_York */
55+
$dateParser = (new DateParser('2023-07-01', 'America/New_York'));
56+
57+
/* Sets default output to timezone Asia/Tokyo */
58+
$dateRange = $dateParser->getDateRange('Asia/Tokyo');
59+
60+
print $dateRange->getFrom()?->format('Y-m-d H:i:s (e)');
61+
// 2023-07-01 13:00:00 (Asia/Tokyo)
62+
63+
print $dateRange->getTo()?->format('Y-m-d H:i:s (e)');
64+
// 2023-07-02 12:59:59 (Asia/Tokyo)
65+
```
66+
4467
## Parsing formats
4568
4669
### Supported words
@@ -68,7 +91,9 @@ $dateParser = (new DateParser('<2023-07-01', 'America/New_York'))->formatTo('Y-m
6891
6992
### Overview
7093
71-
* Imagine today would be the: `2023-07-07`
94+
#### Exact time parser (`=datetime`)
95+
96+
* Imagine that now is the time: `2023-07-07 12:34:56`
7297
7398
| Given format | Description | From `('Y-m-d H:i:s')` | To `('Y-m-d H:i:s')` |
7499
|-----------------------------------------|---------------------------------------------------------|--------------------------------------|--------------------------------------|
@@ -82,7 +107,14 @@ $dateParser = (new DateParser('<2023-07-01', 'America/New_York'))->formatTo('Y-m
82107
| <nobr>`"=this-month"`</nobr> | Alias of `"this-month"` | <nobr>`"2023-07-01 00:00:00"`</nobr> | <nobr>`"2023-07-31 23:59:59"`</nobr> |
83108
| <nobr>`"2023-07-01"`</nobr> | Exactly the given date. | <nobr>`"2023-07-01 00:00:00"`</nobr> | <nobr>`"2023-07-01 23:59:59"`</nobr> |
84109
| <nobr>`"=2023-07-01"`</nobr> | Alias of `"2023-07-01"` | <nobr>`"2023-07-01 00:00:00"`</nobr> | <nobr>`"2023-07-01 23:59:59"`</nobr> |
85-
| - | - | - | - |
110+
111+
#### Time is greater than parser (`>from`)
112+
113+
* Imagine that now is the time: `2023-07-07 12:34:56`
114+
* "To" values are `NULL`
115+
116+
| Given format | Description | From `('Y-m-d H:i:s')` | To `('Y-m-d H:i:s')` |
117+
|-----------------------------------------|---------------------------------------------------------|--------------------------------------|--------------------------------------|
86118
| <nobr>`">tomorrow"`</nobr> | Later than tomorrow<sup>1)</sup> | <nobr>`"2023-07-09 00:00:00"`</nobr> | <nobr>`NULL`</nobr> |
87119
| <nobr>`">=tomorrow"`</nobr> | Later than tomorrow<sup>2)</sup> | <nobr>`"2023-07-08 00:00:00"`</nobr> | <nobr>`NULL`</nobr> |
88120
| <nobr>`">+tomorrow"`</nobr> | Alias of `">=tomorrow"` | <nobr>`"2023-07-08 00:00:00"`</nobr> | <nobr>`NULL`</nobr> |
@@ -99,7 +131,14 @@ $dateParser = (new DateParser('<2023-07-01', 'America/New_York'))->formatTo('Y-m
99131
| <nobr>`">=2023-07-01"`</nobr> | Later than the given date<sup>2)</sup> | <nobr>`"2023-07-01 00:00:00"`</nobr> | <nobr>`NULL`</nobr> |
100132
| <nobr>`">+2023-07-01"`</nobr> | Alias of `">=2023-07-01"` | <nobr>`"2023-07-01 00:00:00"`</nobr> | <nobr>`NULL`</nobr> |
101133
| <nobr>`"+2023-07-01"`</nobr> | Alias of `">=2023-07-01"` | <nobr>`"2023-07-01 00:00:00"`</nobr> | <nobr>`NULL`</nobr> |
102-
| - | - | - | - |
134+
135+
#### Time is less than parser (`<to`)
136+
137+
* Imagine that now is the time: `2023-07-07 12:34:56`
138+
* "From" values are `NULL`
139+
140+
| Given format | Description | From `('Y-m-d H:i:s')` | To `('Y-m-d H:i:s')` |
141+
|-----------------------------------------|---------------------------------------------------------|--------------------------------------|--------------------------------------|
103142
| <nobr>`"<tomorrow"`</nobr> | Before tomorrow<sup>1)</sup> | <nobr>`NULL`</nobr> | <nobr>`"2023-07-07 23:59:59"`</nobr> |
104143
| <nobr>`"<=tomorrow"`</nobr> | Before tomorrow<sup>2)</sup> | <nobr>`NULL`</nobr> | <nobr>`"2023-07-08 23:59:59"`</nobr> |
105144
| <nobr>`"<+tomorrow"`</nobr> | Alias of `"<=tomorrow"` | <nobr>`NULL`</nobr> | <nobr>`"2023-07-08 23:59:59"`</nobr> |
@@ -116,15 +155,25 @@ $dateParser = (new DateParser('<2023-07-01', 'America/New_York'))->formatTo('Y-m
116155
| <nobr>`"<=2023-07-01"`</nobr> | Before the given date<sup>2)</sup> | <nobr>`NULL`</nobr> | <nobr>`"2023-07-01 23:59:59"`</nobr> |
117156
| <nobr>`"<+2023-07-01"`</nobr> | Alias of `"<=2023-07-01"` | <nobr>`NULL`</nobr> | <nobr>`"2023-07-01 23:59:59"`</nobr> |
118157
| <nobr>`"-2023-07-01"`</nobr> | Alias of `"<=2023-07-01"` | <nobr>`NULL`</nobr> | <nobr>`"2023-07-01 23:59:59"`</nobr> |
119-
| - | - | - | - |
158+
159+
#### Range parser (`from|to`)
160+
161+
* Imagine that now is the time: `2023-07-07 12:34:56`
162+
163+
| Given format | Description | From `('Y-m-d H:i:s')` | To `('Y-m-d H:i:s')` |
164+
|-----------------------------------------|---------------------------------------------------------|--------------------------------------|--------------------------------------|
120165
| <nobr>`"2023-07-01\|2023-07-03"`</nobr> | Date range from `"2023-07-01"` to `"2023-07-03"` | <nobr>`"2023-07-01 00:00:00"`</nobr> | <nobr>`"2023-07-03 23:59:59"`</nobr> |
121166
| <nobr>`"2023-07-01\|tomorrow"`</nobr> | Date range from `"2023-07-01"` to `"tomorrow"` | <nobr>`"2023-07-01 00:00:00"`</nobr> | <nobr>`"2023-07-08 23:59:59"`</nobr> |
122167
| <nobr>`"2023-07-01\|today"`</nobr> | Date range from `"2023-07-01"` to `"today"` | <nobr>`"2023-07-01 00:00:00"`</nobr> | <nobr>`"2023-07-07 23:59:59"`</nobr> |
123168
| <nobr>`"2023-07-01\|yesterday"`</nobr> | Date range from `"2023-07-01"` to `"yesterday"` | <nobr>`"2023-07-01 00:00:00"`</nobr> | <nobr>`"2023-07-06 23:59:59"`</nobr> |
124169
| <nobr>`"yesterday\|today"`</nobr> | Date range from `"yesterday"` to `"today"` | <nobr>`"2023-07-06 00:00:00"`</nobr> | <nobr>`"2023-07-07 23:59:59"`</nobr> |
125170
| <nobr>`"yesterday\|this-month"`</nobr> | Date range from `"yesterday"` to last day of this month | <nobr>`"2023-07-06 00:00:00"`</nobr> | <nobr>`"2023-07-31 23:59:59"`</nobr> |
126171
| <nobr>`"this-month\|today"`</nobr> | Date range from first day this month to `"today"` | <nobr>`"2023-07-01 00:00:00"`</nobr> | <nobr>`"2023-07-07 23:59:59"`</nobr> |
127-
| - | - | - | - |
172+
173+
#### Infinitive range parser (`NULL`)
174+
175+
| Given format | Description | From `('Y-m-d H:i:s')` | To `('Y-m-d H:i:s')` |
176+
|-----------------------------------------|---------------------------------------------------------|--------------------------------------|--------------------------------------|
128177
| <nobr>`NULL`</nobr> | No range given (infinitive range). | <nobr>`NULL`</nobr> | <nobr>`NULL`</nobr> |
129178
130179
* <sup>1)</sup> - excluding the given one
@@ -155,32 +204,28 @@ vendor/bin/php-date-parser --version
155204
```
156205
157206
```bash
158-
0.1.8 (2023-07-18 21:24:05) - Björn Hempel <bjoern@hempel.li>
207+
0.1.10 (2023-07-21 21:39:44) - Björn Hempel <bjoern@hempel.li>
159208
```
160209
161-
## Command line
162-
163-
```bash
164-
bin/console pdt --timezone-input=America/New_York --timezone-output=Europe/Berlin "<2023-07-01"
165-
```
210+
## Command line tool
166211
167-
or within your composer project
212+
Used to quickly check a given date time directly in the command line.
168213
169214
```bash
170215
vendor/bin/php-date-parser pdt --timezone-input=America/New_York --timezone-output=Europe/Berlin "<2023-07-01"
171216
```
172217
173218
```text
174219
175-
Given date time range: "<2023-07-01" (America/New_York)
220+
Given date time range: "<2023-07-01" (America/New_York > Europe/Berlin)
176221
177-
+------------------------------------------+------------------+
178-
| Value | Given |
179-
+------------------------------------------+------------------+
180-
| Given date time range (America/New_York) | <2023-07-01 |
181-
| Timezone (input) | America/New_York |
182-
| Timezone (output) | Europe/Berlin |
183-
+------------------------------------------+------------------+
222+
+----------------------------------------------------------+------------------+
223+
| Value | Given |
224+
+----------------------------------------------------------+------------------+
225+
| Given date time range (America/New_York > Europe/Berlin) | <2023-07-01 |
226+
| Timezone (input) | America/New_York |
227+
| Timezone (output) | Europe/Berlin |
228+
+----------------------------------------------------------+------------------+
184229
185230
Parsed from given string (input):
186231

‎src/Base/BaseDateParser.php‎

Lines changed: 26 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -139,6 +139,7 @@ class BaseDateParser
139139
* @throws ParserException
140140
* @throws TypeInvalidException
141141
* @throws CaseUnsupportedException
142+
* @throws Exception
142143
*/
143144
public function __construct(string|null $range, protected DateTimeZone $dateTimeZoneInput = new DateTimeZone('UTC'))
144145
{
@@ -150,7 +151,31 @@ public function __construct(string|null $range, protected DateTimeZone $dateTime
150151
$dateRange->getFrom(),
151152
$dateRange->getTo(),
152153
$dateTimeZoneInput
153-
);
154+
)->setDefaultDateTimeZone(new DateTimeZone(Timezones::UTC));
155+
}
156+
157+
/**
158+
* Returns the default date time zone.
159+
*
160+
* @return DateTimeZone
161+
*/
162+
public function getDefaultDateTimeZone(): DateTimeZone
163+
{
164+
return $this->dateRange->getDefaultDateTimeZone();
165+
}
166+
167+
/**
168+
* Sets the default date time zone.
169+
*
170+
* @param DateTimeZone|string $defaultDateTimeZone
171+
* @return self
172+
* @throws Exception
173+
*/
174+
public function setDefaultDateTimeZone(DateTimeZone|string $defaultDateTimeZone): self
175+
{
176+
$this->dateRange->setDefaultDateTimeZone($defaultDateTimeZone);
177+
178+
return $this;
154179
}
155180

156181
/**

‎src/Command/ParserCommand.php‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -90,15 +90,20 @@ private function printGivenDateTimeRange(string $dateTimeRange, DateTimeZone $ti
9090

9191
$writer->write(PHP_EOL);
9292
$writer->write(sprintf(
93-
'Given date time range: %s (%s)%s',
93+
'Given date time range: %s (%s > %s)%s',
9494
$color->ok(sprintf('"%s"', $dateTimeRange)),
9595
$timezoneInput->getName(),
96+
$timezoneOutput->getName(),
9697
PHP_EOL
9798
));
9899
$writer->write(PHP_EOL);
99100
$writer->table([
100101
[
101-
self::KEY_VALUE => sprintf('Given date time range (%s)', $timezoneInput->getName()),
102+
self::KEY_VALUE => sprintf(
103+
'Given date time range (%s > %s)',
104+
$timezoneInput->getName(),
105+
$timezoneOutput->getName()
106+
),
102107
self::KEY_GIVEN => $dateTimeRange,
103108
],
104109
[

‎src/DateParser.php‎

Lines changed: 24 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -34,84 +34,89 @@ class DateParser extends BaseDateParser
3434
/**
3535
* Returns the date range.
3636
*
37+
* @param DateTimeZone|string|null $dateTimeZone
3738
* @return DateRange
3839
*/
39-
public function getDateRange(): DateRange
40+
public function getDateRange(DateTimeZone|string $dateTimeZone = null): DateRange
4041
{
42+
if (!is_null($dateTimeZone)) {
43+
$this->setDefaultDateTimeZone($dateTimeZone);
44+
}
45+
4146
return $this->dateRange;
4247
}
4348

4449
/**
4550
* Returns the "from" date as string.
4651
*
4752
* @param string $format
48-
* @param DateTimeZone $dateTimeZoneOutput
53+
* @param DateTimeZone|null $dateTimeZone
4954
* @return string|null
5055
* @throws CaseUnsupportedException
5156
*/
52-
public function formatFrom(string $format, DateTimeZone $dateTimeZoneOutput = new DateTimeZone(Timezones::UTC)): string|null
57+
public function formatFrom(string $format, DateTimeZone $dateTimeZone = null): string|null
5358
{
54-
return $this->dateRange->getFrom($dateTimeZoneOutput)?->format($format);
59+
return $this->dateRange->getFrom($dateTimeZone)?->format($format);
5560
}
5661

5762
/**
5863
* Returns the "to" date as string.
5964
*
6065
* @param string $format
61-
* @param DateTimeZone $dateTimeZoneOutput
66+
* @param DateTimeZone $dateTimeZone
6267
* @return string|null
6368
* @throws CaseUnsupportedException
6469
*/
65-
public function formatTo(string $format, DateTimeZone $dateTimeZoneOutput = new DateTimeZone(Timezones::UTC)): string|null
70+
public function formatTo(string $format, DateTimeZone $dateTimeZone = new DateTimeZone(Timezones::UTC)): string|null
6671
{
67-
return $this->dateRange->getTo($dateTimeZoneOutput)?->format($format);
72+
return $this->dateRange->getTo($dateTimeZone)?->format($format);
6873
}
6974

7075
/**
7176
* Returns the "from" date as DateTime object.
7277
*
73-
* @param DateTimeZone $dateTimeZoneOutput
78+
* @param DateTimeZone $dateTimeZone
7479
* @return DateTime|null
7580
* @throws CaseUnsupportedException
7681
*/
77-
public function getFrom(DateTimeZone $dateTimeZoneOutput = new DateTimeZone(Timezones::UTC)): DateTime|null
82+
public function getFrom(DateTimeZone $dateTimeZone = new DateTimeZone(Timezones::UTC)): DateTime|null
7883
{
79-
return $this->dateRange->getFrom($dateTimeZoneOutput);
84+
return $this->dateRange->getFrom($dateTimeZone);
8085
}
8186

8287
/**
8388
* Returns the "to" date as DateTime object.
8489
*
85-
* @param DateTimeZone $dateTimeZoneOutput
90+
* @param DateTimeZone $dateTimeZone
8691
* @return DateTime|null
8792
* @throws CaseUnsupportedException
8893
*/
89-
public function getTo(DateTimeZone $dateTimeZoneOutput = new DateTimeZone(Timezones::UTC)): DateTime|null
94+
public function getTo(DateTimeZone $dateTimeZone = new DateTimeZone(Timezones::UTC)): DateTime|null
9095
{
91-
return $this->dateRange->getTo($dateTimeZoneOutput);
96+
return $this->dateRange->getTo($dateTimeZone);
9297
}
9398

9499
/**
95100
* Returns the "from" date as DateTimeImmutable object.
96101
*
97-
* @param DateTimeZone $dateTimeZoneOutput
102+
* @param DateTimeZone $dateTimeZone
98103
* @return DateTimeImmutable|null
99104
* @throws CaseUnsupportedException
100105
*/
101-
public function getFromImmutable(DateTimeZone $dateTimeZoneOutput = new DateTimeZone(Timezones::UTC)): DateTimeImmutable|null
106+
public function getFromImmutable(DateTimeZone $dateTimeZone = new DateTimeZone(Timezones::UTC)): DateTimeImmutable|null
102107
{
103-
return $this->dateRange->getFromImmutable($dateTimeZoneOutput);
108+
return $this->dateRange->getFromImmutable($dateTimeZone);
104109
}
105110

106111
/**
107112
* Returns the "to" date as DateTimeImmutable object.
108113
*
109-
* @param DateTimeZone $dateTimeZoneOutput
114+
* @param DateTimeZone $dateTimeZone
110115
* @return DateTimeImmutable|null
111116
* @throws CaseUnsupportedException
112117
*/
113-
public function getToImmutable(DateTimeZone $dateTimeZoneOutput = new DateTimeZone(Timezones::UTC)): DateTimeImmutable|null
118+
public function getToImmutable(DateTimeZone $dateTimeZone = new DateTimeZone(Timezones::UTC)): DateTimeImmutable|null
114119
{
115-
return $this->dateRange->getToImmutable($dateTimeZoneOutput);
120+
return $this->dateRange->getToImmutable($dateTimeZone);
116121
}
117122
}

0 commit comments

Comments
 (0)