Skip to content

Latest commit

 

History

History
292 lines (226 loc) · 21.1 KB

README.md

File metadata and controls

292 lines (226 loc) · 21.1 KB

PHP Date Parser

Release PHP PHPStan PHPUnit PHPCS PHPMD Rector - Instant Upgrades and Automated Refactoring LICENSE

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 <[email protected]>

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 [email protected]: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