NaturalDate
, (*1)
When telling stories, people usually don't give an exact date for the events of the story. They often say things like:, (*2)
the summer of '87, (*3)
or, (*4)
last Christmas, (*5)
You can use NaturalDate to translate these date approximations to usable dates or date ranges in your code., (*6)
If NaturalDate can't determine an exact date from the input, it will give you a start and end date that the actual date should be between., (*7)
Example
$naturalDate = NaturalDate::parse( "Early 2016", 'America/Phoenix' );
echo $naturalDate->toJson();
Output
{
"utcStart": {
"date": "2016-01-01 07:00:00.000000",
"timezone_type": 3,
"timezone": "UTC"
},
"utcEnd": {
"date": "2016-05-01 05:59:59.000000",
"timezone_type": 3,
"timezone": "UTC"
},
"localStart": {
"date": "2016-01-01 00:00:00.000000",
"timezone_type": 3,
"timezone": "America\/Denver"
},
"localEnd": {
"date": "2016-04-30 23:59:59.000000",
"timezone_type": 3,
"timezone": "America\/Denver"
}
}
Summary of Functions
$naturalDate = NaturalDate::parse( "between thanksgiving and christmas 2017", 'America/Phoenix' );
// $localStartDateTime will be a Carbon object.
$localStartDateTime = $naturalDate->getLocalStart();
echo $localStartDateTime; // '2017-11-23 00:00:00'
// $utcStartDateTime will be a Carbon object.
$utcStartDateTime = $naturalDate->getUtcStart();
echo $utcStartDateTime; // '2017-11-23 07:00:00'
// $localEndDateTime will be a Carbon object as well.
$localEndDateTime = $naturalDate->getLocalEnd();
echo $localEndDateTime; // '2017-12-31 23:59:59'
// $utcEndDateTime will be a Carbon object.
$utcEndDateTime = $naturalDate->getUtcEnd();
echo $utcEndDateTime; // '2018-01-01 06:59:59'
echo $naturalDate->getType(); // 'range'
parse( string $string = '', string $timezoneId = 'UTC', string $languageCode = 'en', $patternModifiers = [], NaturalDate $existingNaturalDate = NULL, bool $cleanOutput = TRUE ): NaturalDate
Explaining the parameters:
- $string - The user supplied string that you want to parse.
- $timezoneId - The timezone for the user. Defaults to UTC
- $languageCode - The 2 character language code of the user.
- $patternModifiers - An array of custom pattern modifiers you want NaturalDate to use. Explained in detail below.
- $existingNaturalDate - Shouldn't really ever be used by you. More for internal usage.
- $cleanOutput - Shouldn't really be used by you either. But set to false if you want to see what NaturalDate is doing under the hood., (*8)
getLocalStart()
This method returns a Carbon object with the user's timezone. The Carbon object represents when NaturalDate thinks the earliest possible time was based on the user's input., (*9)
getLocalEnd()
This method returns a Carbon object with the user's timezone. The Carbon object represents when NaturalDate thinks the latest possible time was based on the user's input., (*10)
getUtcStart() and getUtcEnd()
These methods act the same as getLocalStart() and getLocalEnd() but the Carbon objects they return use the UTC timezone., (*11)
getType()
This method will return a string that gives you an idea of the "confidence" that NaturalDate has on the data it's returning to you., (*12)
Possible values are:
- datetime - The most specific/highest confidence.
- date
- week
- month
- year
- season
- quarter
- range - Often seen when the user asks for "Between x and y", (*13)
toJson()
For convenience, I've added a toJson() method that returns the NaturalDate object created by NaturalDate::parse() in a json encoded string., (*14)
__toString()
I also created an implementation of the magic __toString() method, so if you echo the NaturalDate object, you will get a prettified output describing the NaturalDate object., (*15)
Missing holidays? Just ask for them.
If you see that NaturalDate is missing some holidays (it is), create an issue on GitHub and I will add them. Holidays from all countries should be part of the base library., (*16)
Building onto the PatternModifiers
This is the really cool thing. You can create your own PatternModifiers. What does that mean exactly?, (*17)
Think about this scenario...
You want to let your users enter a date like:
"my freshman year in high school", (*18)
Well obviously NaturalDate doesn't know when that is. So you could create your own PatternModifier to pass into the parse() method., (*19)
Your pattern modifier would need a regular expression that would trigger it, and dates to fill in when triggered., (*20)
Use the class named JohnMcClanesBirthday in the PatternModifiers directory as a model., (*21)
It should be pretty easy for you to copy that and modify it to suit your needs., (*22)
use MichaelDrennen\NaturalDate\PatternModifiers\PatternModifier;
use MichaelDrennen\NaturalDate\NaturalDate;
class JohnMcClanesBirthday extends PatternModifier {
protected $patterns = [
"/john mcclane\'s birthday/i",
"/john mcclanes birthday/i",
"/john mcclane birthday/i",
];
public function modify( NaturalDate $naturalDate ): NaturalDate {
$naturalDate->setStartYear( 1955 );
$naturalDate->setStartMonth( 11 );
$naturalDate->setStartDay( 2 );
$naturalDate->setStartHour( 0 );
$naturalDate->setStartMinute( 0 );
$naturalDate->setStartSecond( 0 );
$naturalDate->setEndYear( 1955 );
$naturalDate->setEndMonth( 11 );
$naturalDate->setEndDay( 2 );
$naturalDate->setEndHour( 23 );
$naturalDate->setEndMinute( 59 );
$naturalDate->setEndSecond( 59 );
$naturalDate->setType( NaturalDate::date );
return $naturalDate;
}
}
Wallogit.com
