wapmorgan / time-parser
A parser for date & time written in natural language
Installs: 108 341
Dependents: 2
Suggesters: 0
Security: 0
Stars: 95
Watchers: 12
Forks: 23
Open Issues: 0
Requires
- php: >=5.6.0
Requires (Dev)
- phpunit/phpunit: ~4.8
This package is auto-updated.
Last update: 2024-10-28 07:05:09 UTC
README
A parser for date and time written in natural language for PHP.
- Installation
- Usage
- Languages support
- ToDo
Installation
The preferred way to install package is via composer:
composer require wapmorgan/time-parser
Usage
Parse some input from user and receive a DateTime
object.
-
Create a Parser object
$parser = new wapmorgan\TimeParser\TimeParser('all');
First argument is a language. Applicable values:
'all'
(by default) - scan for all available languages. Use it when you can not predict user's preferred language.'russian'
- scan only as string written in one language.array('english', 'russian')
- scan as english and then the rest as russian.
-
Enable and disable parsing of alphabetic values.
// To enable alphabetic parsing. $parser->allowAlphabeticUnits(); // To disable alphabetic parsing. $parser->disallowAlphabeticUnits();
-
Parse string and return a
DateTimeImmutable
object. If second argument istrue
, method will returnfalse
when no date&time strings found. If third parameter is provided, then it is filled with the string obtained after all the transformations.$datetime = $parser->parse(fgets(STDIN)); // next call returns false $datetime = $parser->parse('abc', true); // $result will contains "we will come " $datetime = $parser->parse('We will come in a week', true, $result);
-
For advanced parsing of alphabetic values is used built-in function. You can specify your own handler for this feature. Сurrently is used for russian and english languages only.
use wapmorgan\TimeParser\TimeParser; // $string will contains alphabetic value for advanced parsing. // Ex.: for string "in twenty five minutes", it will contains "twenty five". // $lang will contains name of the parsed language. TimeParser::setWordsToNumberCallback(function($string, $lang) { // do some magic });
-
You can add your own custom language.
// $date must be an array with a structure like the existing rules. $parser->addLanguage($data);
Languages support
For this moment four languages supported: Russian, English, French and German. Two languages support is in progress: Chinese, Spanish.
Their rules are in rules
catalog so you can improve TimeParser by adding new language or by improving existing one.
Languages with examples of strings containing date&time:
For developing reasons you may would like to see process of parsing. To do this call related methods:
TimeParser::enableDebug(); // and TimeParser::disableDebug();
Parsable substrings
To understand, how it works, look at substrings separately:
- 15 december 1977 - absolute date
- at 15:12:13 - absolute time
- next monday or this friday - absolute date
- next year or 2016 year - absolute date
- in february or next month - absolute date
- next week - absolute date
- in 15 hours - relative time
- in 10 minutes - relative time
- in 11 seconds - relative time
- in 2 weeks - relative date
- in 1 day - relative date
- in 10 months - relative date
- через час - relative date (russian, english only)
- in a hour - relative date (russian, english only)
- через двадцать пять минут - relative date (russian, english only)
- in twenty five minutes - relative date (russian, english only)
- пять минут назад - relative date (russian, english only)
- five minutes ago - relative date (russian, english only)
- 5 минут назад - relative date (russian, english only)
- 5 minutes ago - relative date (russian, english only)
- вчера - relative date (russian, english only)
- yesterday - relative date (russian, english only)
ToDo
- Tests.
- Try to parse combinations: in 5 hours and 2 minutes.
- Try to parse alphabetic offsets: in five hours and через пять часов.
Languages ToDo
- Chinese - check hieroglyphs.
- Spanish - check prepositions.
- Portuguese
- Arabic
- Korean