Search by 
ixnode / php-date-parser
PHP Date Parser - This library parses various given date and time strings into DateTime or DateTimeImmutable classes which return the time range. Can be used e.g. excellently for command line arguments and options to make database queries with.
1.0.3
2023-07-22 15:34 UTC
Requires
- php: ^8.2
- adhocore/cli: ^v1.0.0
- ixnode/php-naming-conventions: ^0.1.1
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.13
- ixnode/bash-version-manager: ^0.1.3
- phpmd/phpmd: ^2.13
- phpstan/phpstan: ^1.9
- phpunit/phpunit: ^9.5
- povils/phpmnd: ^3.0
- rector/rector: ^0.15.1
README
This library parses various given date and time strings into DateTime or DateTimeImmutable classes which return the time range. Can be used e.g. excellently for command line arguments and options to make database queries with.
Examples / Usage
use Ixnode\PhpDateParser\DateParser;
Date parser (UTC)
print (new DateParser('2023-07-01'))->formatFrom('Y-m-d H:i:s'); // 2023-07-01 00:00:00 print (new DateParser('2023-07-01'))->formatTo('Y-m-d H:i:s'); // 2023-07-01 23:59:59
Word parser (UTC)
- Imagine that now is the time:
2023-07-07 12:34:56
print (new DateParser('today'))->formatFrom('Y-m-d H:i:s'); // 2023-07-07 00:00:00 print (new DateParser('today'))->formatTo('Y-m-d H:i:s'); // 2023-07-07 23:59:59
Date parser with timezones
- Input:
America/New_York - Output:
Europe/Berlin
/* Parses given date time from timezone America/New_York; Output to timezone Europe/Berlin */ print (new DateParser('<2023-07-01', 'America/New_York'))->formatFrom('Y-m-d H:i:s', 'Europe/Berlin'); // null /* Parses given date time from timezone America/New_York; Output to timezone Europe/Berlin */ print (new DateParser('<2023-07-01', 'America/New_York'))->formatTo('Y-m-d H:i:s', 'Europe/Berlin'); // 2023-07-01 05:59:59
Working with DateRange class
/* Parses given date time from timezone America/New_York */ $dateParser = (new DateParser('2023-07-01', 'America/New_York')); /* Sets default output to timezone Asia/Tokyo */ $dateRange = $dateParser->getDateRange('Asia/Tokyo'); print $dateRange->getFrom()?->format('Y-m-d H:i:s (e)'); // 2023-07-01 13:00:00 (Asia/Tokyo) print $dateRange->getTo()?->format('Y-m-d H:i:s (e)'); // 2023-07-02 12:59:59 (Asia/Tokyo)
Parsing formats
Supported words
| Word | Description |
|---|---|
next-second |
Next second ('s' + 1) |
this-second |
This second ('s') |
last-second |
Last second ('s' - 1) |
next-minute |
Next minute ('i' + 1) |
this-minute |
This minute ('i') |
last-minute |
Last minute ('i' - 1) |
next-hour |
Next hour ('G' + 1) |
this-hour |
This hour ('G') |
last-hour |
Last hour ('G' - 1) |
tomorrow |
The day tomorrow ('j' + 1) |
today |
The day today ('j') |
yesterday |
The day yesterday ('j' - 1) |
next-month |
Next month ('n' + 1) |
this-month |
This month ('n') |
last-month |
Last month ('n' - 1) |
next-year |
Next year ('Y' + 1) |
this-year |
This year ('Y') |
last-year |
Last year ('Y' - 1) |
Overview
Exact time parser (=datetime)
- Imagine that now is the time:
2023-07-07 12:34:56
| Given format | Description | From ('Y-m-d H:i:s') |
To ('Y-m-d H:i:s') |
|---|---|---|---|
"next-hour" |
Returns the date range from the next hour. Alias of "2023-07-07 13". |
"2023-07-07 13:00:00" |
"2023-07-07 13:59:59" |
"=next-hour" |
Alias of "next-hour". |
"2023-07-07 13:00:00" |
"2023-07-07 13:59:59" |
"this-hour" |
Returns the date range from current hour. Alias of "2023-07-07 12". |
"2023-07-07 12:00:00" |
"2023-07-07 12:59:59" |
"=this-hour" |
Alias of "this-hour". |
"2023-07-07 12:00:00" |
"2023-07-07 12:59:59" |
"last-hour" |
Returns the date range from the last hour. Alias of "2023-07-07 11". |
"2023-07-07 11:00:00" |
"2023-07-07 11:59:59" |
"=last-hour" |
Alias of "last-hour". |
"2023-07-07 11:00:00" |
"2023-07-07 11:59:59" |
"tomorrow" |
Returns the date range from tomorrow. Alias of "2023-07-08". |
"2023-07-08 00:00:00" |
"2023-07-08 23:59:59" |
"=tomorrow" |
Alias of "tomorrow". |
"2023-07-08 00:00:00" |
"2023-07-08 23:59:59" |
"today" |
Returns the date range from today. Alias of "2023-07-07". |
"2023-07-07 00:00:00" |
"2023-07-07 23:59:59" |
"=today" |
Alias of "today". |
"2023-07-07 00:00:00" |
"2023-07-07 23:59:59" |
"yesterday" |
Returns the date range from yesterday. Alias of "2023-07-06". |
"2023-07-06 00:00:00" |
"2023-07-06 23:59:59" |
"=yesterday" |
Alias of "yesterday" |
"2023-07-06 00:00:00" |
"2023-07-06 23:59:59" |
"this-month" |
Date range from first day to last day this month. Alias of "2023-07-01|2023-07-31". |
"2023-07-01 00:00:00" |
"2023-07-31 23:59:59" |
"=this-month" |
Alias of "this-month" |
"2023-07-01 00:00:00" |
"2023-07-31 23:59:59" |
"2023-07-01" |
Exactly the given date. | "2023-07-01 00:00:00" |
"2023-07-01 23:59:59" |
"=2023-07-01" |
Alias of "2023-07-01" |
"2023-07-01 00:00:00" |
"2023-07-01 23:59:59" |
Time is greater than parser (>from)
- Imagine that now is the time:
2023-07-07 12:34:56 - "To" values are
NULL
| Given format | Description | From ('Y-m-d H:i:s') |
To ('Y-m-d H:i:s') |
|---|---|---|---|
">tomorrow" |
Later than tomorrow1) | "2023-07-09 00:00:00" |
NULL |
">=tomorrow" |
Later than tomorrow2) | "2023-07-08 00:00:00" |
NULL |
">+tomorrow" |
Alias of ">=tomorrow" |
"2023-07-08 00:00:00" |
NULL |
"+tomorrow" |
Alias of ">=tomorrow" |
"2023-07-08 00:00:00" |
NULL |
">today" |
Later than today1) | "2023-07-08 00:00:00" |
NULL |
">=today" |
Later than today2) | "2023-07-07 00:00:00" |
NULL |
">+today" |
Alias of ">=today" |
"2023-07-07 00:00:00" |
NULL |
"+today" |
Alias of ">=today" |
"2023-07-07 00:00:00" |
NULL |
">yesterday" |
Later than yesterday1) | "2023-07-07 00:00:00" |
NULL |
">=yesterday" |
Later than yesterday2) | "2023-07-06 00:00:00" |
NULL |
">+yesterday" |
Alias of ">=yesterday" |
"2023-07-06 00:00:00" |
NULL |
"+yesterday" |
Alias of ">=yesterday" |
"2023-07-06 00:00:00" |
NULL |
">2023-07-01" |
Later than the given date1) | "2023-07-02 00:00:00" |
NULL |
">=2023-07-01" |
Later than the given date2) | "2023-07-01 00:00:00" |
NULL |
">+2023-07-01" |
Alias of ">=2023-07-01" |
"2023-07-01 00:00:00" |
NULL |
"+2023-07-01" |
Alias of ">=2023-07-01" |
"2023-07-01 00:00:00" |
NULL |
- 1) - excluding the given one
- 2) - including the given one
Time is less than parser (<to)
- Imagine that now is the time:
2023-07-07 12:34:56 - "From" values are
NULL
| Given format | Description | From ('Y-m-d H:i:s') |
To ('Y-m-d H:i:s') |
|---|---|---|---|
"<tomorrow" |
Before tomorrow1) | NULL |
"2023-07-07 23:59:59" |
"<=tomorrow" |
Before tomorrow2) | NULL |
"2023-07-08 23:59:59" |
"<+tomorrow" |
Alias of "<=tomorrow" |
NULL |
"2023-07-08 23:59:59" |
"-tomorrow" |
Alias of "<=tomorrow" |
NULL |
"2023-07-08 23:59:59" |
"<today" |
Before today1) | NULL |
"2023-07-06 23:59:59" |
"<=today" |
Before today2) | NULL |
"2023-07-07 23:59:59" |
"<+today" |
Alias of "<=today" |
NULL |
"2023-07-07 23:59:59" |
"-today" |
Alias of "<=today" |
NULL |
"2023-07-07 23:59:59" |
"<yesterday" |
Before yesterday1) | NULL |
"2023-07-05 23:59:59" |
"<=yesterday" |
Before yesterday2) | NULL |
"2023-07-06 23:59:59" |
"<+yesterday" |
Alias of "<=yesterday" |
NULL |
"2023-07-06 23:59:59" |
"-yesterday" |
Alias of "<=yesterday" |
NULL |
"2023-07-06 23:59:59" |
"<2023-07-01" |
Before the given date1) | NULL |
"2023-06-30 23:59:59" |
"<=2023-07-01" |
Before the given date2) | NULL |
"2023-07-01 23:59:59" |
"<+2023-07-01" |
Alias of "<=2023-07-01" |
NULL |
"2023-07-01 23:59:59" |
"-2023-07-01" |
Alias of "<=2023-07-01" |
NULL |
"2023-07-01 23:59:59" |
- 1) - excluding the given one
- 2) - including the given one
Range parser (from|to)
- Imagine that now is the time:
2023-07-07 12:34:56
| Given format | Description | From ('Y-m-d H:i:s') |
To ('Y-m-d H:i:s') |
|---|---|---|---|
"2023-07-01|2023-07-03" |
Date range from "2023-07-01" to "2023-07-03" |
"2023-07-01 00:00:00" |
"2023-07-03 23:59:59" |
"2023-07-01|tomorrow" |
Date range from "2023-07-01" to "tomorrow" |
"2023-07-01 00:00:00" |
"2023-07-08 23:59:59" |
"2023-07-01|today" |
Date range from "2023-07-01" to "today" |
"2023-07-01 00:00:00" |
"2023-07-07 23:59:59" |
"2023-07-01|yesterday" |
Date range from "2023-07-01" to "yesterday" |
"2023-07-01 00:00:00" |
"2023-07-06 23:59:59" |
"yesterday|today" |
Date range from "yesterday" to "today" |
"2023-07-06 00:00:00" |
"2023-07-07 23:59:59" |
"yesterday|this-month" |
Date range from "yesterday" to last day of this month |
"2023-07-06 00:00:00" |
"2023-07-31 23:59:59" |
"this-month|today" |
Date range from first day this month to "today" |
"2023-07-01 00:00:00" |
"2023-07-07 23:59:59" |
Infinitive range parser (NULL)
| Given format | Description | From ('Y-m-d H:i:s') |
To ('Y-m-d H:i:s') |
|---|---|---|---|
NULL |
No range given (infinitive range). | NULL |
NULL |
Methods
Class DateParser
| method | description | type |
|---|---|---|
->getDateRange(DateTimeZone|string $dateTimeZone = null) |
Returns the range as DateRange class. |
DateRange |
->formatFrom(string $format, DateTimeZone|string $dateTimeZone = null) |
Returns the formatted "from" date. | string |
->formatTo(string $format, DateTimeZone|string $dateTimeZone = null) |
Returns the formatted "to" date. | string |
->getFrom(DateTimeZone|string $dateTimeZone = null) |
Returns the "from" date as DateTime object. |
DateTime|null |
->getTo(DateTimeZone|string $dateTimeZone = null) |
Returns the "to" date as DateTime object. |
DateTime|null |
->getFromImmutable(DateTimeZone|string $dateTimeZone = null) |
Returns the "from" date as DateTimeImmutable object. |
DateTimeImmutable|null |
->getToImmutable(DateTimeZone|string $dateTimeZone = null) |
Returns the "to" date as DateTimeImmutable object. |
DateTimeImmutable|null |
->getDuration() |
Returns the duration from "from" to "to" in seconds. | int|null |
->getDurationWithOwn() |
Returns the duration from "from" to "to" in seconds (including the first second). | int|null |
Installation
composer require ixnode/php-date-parser
vendor/bin/php-date-parser --version
0.1.10 (2023-07-21 21:39:44) - Björn Hempel <bjoern@hempel.li>
Command line tool
Used to quickly check a given date time directly in the command line.
vendor/bin/php-date-parser pdt --timezone-input=America/New_York --timezone-output=Europe/Berlin "<2023-07-01"
Given date time range: "2023-07-01" (America/New_York > Europe/Berlin)
+----------------------------------------------------------+------------------+
| Value | Given |
+----------------------------------------------------------+------------------+
| Given date time range (America/New_York > Europe/Berlin) | 2023-07-01 |
| Timezone (input) | America/New_York |
| Timezone (output) | Europe/Berlin |
+----------------------------------------------------------+------------------+
Parsed from given input string (duration: 86400 seconds):
+------+-------------+---------------------+---------------------+
| Type | Format | UTC | America/New York |
+------+-------------+---------------------+---------------------+
| From | Y-m-d H:i:s | 2023-07-01 04:00:00 | 2023-07-01 00:00:00 |
| To | Y-m-d H:i:s | 2023-07-02 03:59:59 | 2023-07-01 23:59:59 |
+------+-------------+---------------------+---------------------+
Parsed output (duration: 86400 seconds):
+------+-------------+---------------------+---------------------+
| Type | Format | UTC | Europe/Berlin |
+------+-------------+---------------------+---------------------+
| From | Y-m-d H:i:s | 2023-07-01 04:00:00 | 2023-07-01 06:00:00 |
| To | Y-m-d H:i:s | 2023-07-02 03:59:59 | 2023-07-02 05:59:59 |
+------+-------------+---------------------+---------------------+
Supported timezones
See: src/Constants/Timezones.php
Development
git clone git@github.com:ixnode/php-date-parser.git && cd php-date-parser
composer install
composer test
License
This tool is licensed under the MIT License - see the LICENSE file for details