wapmorgan/time-parser

A parser for date & time written in natural language

2.0.0 2017-04-27 16:14 UTC

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.

Composer package Latest Stable Version Total Downloads Latest Unstable Version License Testing

  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