PHP Classes

PHP Time Parse to Timestamp: Parse time in natural language and multiple idioms

Recommend this page to a friend!
  Info   View files Documentation   View files View files (12)   DownloadInstall with Composer Download .zip   Reputation   Support forum   Blog    
Ratings Unique User Downloads Download Rankings
Not yet rated by the usersTotal: 189 All time: 8,586 This week: 125Up
Version License PHP version Categories
time-parser 1.0BSD License5.3PHP 5, Time and Date, Parsers


This class can parse time in natural language and multiple idioms.

The class takes a string with date and time written in natural language and tries to match its format according to rules for known formats.

If the class matches one of the supported format rules, it returns the parsed time as a DateTime object.

The date and time format rules are retrieved from configuration files in the JSON format.

Currently it supports Russian, English, French, German, Chinese and Spanish.

Innovation Award
PHP Programming Innovation award nominee
November 2014
Number 5

Prize: One year server license IP to country, region, city, latitude, longitude, ZIP code, time zone, area code database
Date and time values can be represented in natural language in formats that vary from language to language.

This class can detect date and time values expressed in natural language in several different languages.

The detected formats are parsed and the date and time values are returned as a DateTime object, so applications do not need to deal with the details of representation in the original language.

Manuel Lemos
Picture of Sergey Vanyushin
  Performance   Level  
Name: Sergey Vanyushin is available for providing paid consulting. Contact Sergey Vanyushin .
Classes: 15 packages by
Country: Russian Federation Russian Federation
Age: 28
All time rank: 57516 in Russian Federation Russian Federation
Week rank: 100 Up6 in Russian Federation Russian Federation Up
Innovation award
Innovation award
Nominee: 15x

Winner: 2x


TimeParser - is a parser for date and time written in natural language for PHP.

How to use

  1. Install through composer: `composer require wapmorgan/time-parser`
  2. Parse some input from user and receive a `DateTime` object.
    $datetime = wapmorgan\TimeParser\TimeParser::parse(fgets(STDIN), 'all');

    Second arg is a language. Applicable values: * 'all' - scan for all available languages. Use it when you can not predict user's preferred language. * 'english' - scan only as english time. * array('english', 'russian') - scan as english and then the rest as russian time. * 'nonexistent-language' - force scan with system strtotime() function. In case of strtotime() scan failure, current DateTime will be returned.

Examples of dates written in natural language that will work.

в 15:12:13 в следующий понедельник в следующем году в феврале через 15 часов через 10 минут через 11 секунд через 5 лет через 2 недели через 1 день через 10 месяцев
at 15:12:13 next monday next year in february in 15 hours in 10 minutes in 11 seconds in 5 years in 2 weeks in 1 day in 10 months

They both will be parsed and result DateTime will contain right date:

Sun, 03 Oct 2021 06:22:24 +0400

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. For developing reasons you may would like to see process of parsing. To do this call related methods:

// and

Parsable substrings

To understand, how it works, look at substrings separately:

  • 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

Alphabetic unit values

If you set third argument of parse() to true, TimeParser will be able to parse alphabetic values:

  • in fifteen hours
  • in ten minutes
  • in eleven seconds
  • in five years
  • in two weeks
  • in one day
  • in ten months

If you want to disallow users use words instead of numbers, save default settings or set third argument of parse() to false. In this case alphabetic values will not be parsed. Numbers up to 20 are available to use.


  1. Library is very sensitive to all sorts of rubbish: extra spaces between numbers and prepositions, etc.
  2. Implies that the incoming data comes in lower case.


  • [ ] Tests.
  • [ ] Try to parse combinations: in 5 hours and 2 minutes.
  • [x] Try to parse alphabetic offsets: in five hours and через пять часов.

Languages ToDo

  • [x] Chinese - check hieroglyphs.
  • [x] Spanish - check prepositions.
  • [ ] Portuguese
  • [ ] Arabic
  • [ ] Korean

  Files folder image Files  
File Role Description
Files folder imagerules (6 files)
Files folder imagesrc (3 files)
Plain text file composer.json Data Auxiliary data
Plain text file Doc. Documentation
Plain text file test.php Test Unit test script

  Files folder image Files  /  rules  
File Role Description
  Plain text file chinese.json Data Auxiliary data
  Plain text file english.json Data Auxiliary data
  Plain text file french.json Data Auxiliary data
  Plain text file german.json Data Auxiliary data
  Plain text file russian.json Data Auxiliary data
  Plain text file spanish.json Data Auxiliary data

  Files folder image Files  /  src  
File Role Description
  Plain text file DebugStream.php Class Class source
  Plain text file Language.php Class Class source
  Plain text file TimeParser.php Class Class source

 Version Control Unique User Downloads Download Rankings  
This week:0
All time:8,586
This week:125Up