README

A parser for date and time written in natural language for PHP.

1. Installation
2. Usage
3. Languages support
4. 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.

1. 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.

2. Enable and disable parsing of alphabetic values.

   // To enable alphabetic parsing.
   $parser->allowAlphabeticUnits();
   // To disable alphabetic parsing.
   $parser->disallowAlphabeticUnits();

3. Parse string and return a DateTimeImmutable object. If second argument is true, method will return false 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);

4. 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
   });
   

5. 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