{"id":16414573,"url":"https://github.com/wapmorgan/timeparser","last_synced_at":"2025-09-01T13:41:16.221Z","repository":{"id":23202934,"uuid":"26559654","full_name":"wapmorgan/TimeParser","owner":"wapmorgan","description":"A parser for date and time written in natural language for PHP.","archived":false,"fork":false,"pushed_at":"2019-01-27T18:48:34.000Z","size":51,"stargazers_count":96,"open_issues_count":0,"forks_count":23,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-06-23T06:17:13.547Z","etag":null,"topics":["chinese","english","french","german","language","multilingual","natural-language","russian","spanish","timeparser"],"latest_commit_sha":null,"homepage":"http://wapmorgan.github.io/TimeParser/","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wapmorgan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-11-12T22:38:32.000Z","updated_at":"2025-06-10T13:03:05.000Z","dependencies_parsed_at":"2022-07-15T13:47:02.864Z","dependency_job_id":null,"html_url":"https://github.com/wapmorgan/TimeParser","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/wapmorgan/TimeParser","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wapmorgan%2FTimeParser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wapmorgan%2FTimeParser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wapmorgan%2FTimeParser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wapmorgan%2FTimeParser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wapmorgan","download_url":"https://codeload.github.com/wapmorgan/TimeParser/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wapmorgan%2FTimeParser/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273135950,"owners_count":25051999,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-01T02:00:09.058Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chinese","english","french","german","language","multilingual","natural-language","russian","spanish","timeparser"],"created_at":"2024-10-11T06:54:28.659Z","updated_at":"2025-09-01T13:41:16.196Z","avatar_url":"https://github.com/wapmorgan.png","language":"PHP","readme":"TimeParser\r\n=====\r\nA parser for date and time written in natural language for PHP.\r\n\r\n[![Composer package](http://composer.network/badge/wapmorgan/time-parser)](https://packagist.org/packages/wapmorgan/time-parser) [![Latest Stable Version](https://poser.pugx.org/wapmorgan/time-parser/v/stable)](https://packagist.org/packages/wapmorgan/time-parser) [![Total Downloads](https://poser.pugx.org/wapmorgan/time-parser/downloads)](https://packagist.org/packages/wapmorgan/time-parser) [![Latest Unstable Version](https://poser.pugx.org/wapmorgan/time-parser/v/unstable)](https://packagist.org/packages/wapmorgan/time-parser) [![License](https://poser.pugx.org/wapmorgan/time-parser/license)](https://packagist.org/packages/wapmorgan/time-parser) [![Testing](https://travis-ci.org/wapmorgan/TimeParser.svg?branch=master)](https://travis-ci.org/wapmorgan/TimeParser)\r\n\r\n1. Installation\r\n2. Usage\r\n3. Languages support\r\n5. ToDo\r\n\r\n## Installation\r\nThe preferred way to install package is via composer:\r\n\r\n```bash\r\ncomposer require wapmorgan/time-parser\r\n```\r\n\r\n## Usage\r\nParse some input from user and receive a `DateTime` object.\r\n\r\n1. Create a Parser object\r\n    ```php\r\n    $parser = new wapmorgan\\TimeParser\\TimeParser('all');\r\n    ```\r\n\r\n    First argument is a language. Applicable values:\r\n\r\n    * `'all'` (by default) - scan for all available languages. Use it when you can not predict user's preferred language.\r\n    * `'russian'` - scan only as string written in one language.\r\n    * `array('english', 'russian')` - scan as english and then the rest as russian.\r\n\r\n2. Enable and disable parsing of alphabetic values.\r\n    ```php\r\n    // To enable alphabetic parsing.\r\n    $parser-\u003eallowAlphabeticUnits();\r\n    // To disable alphabetic parsing.\r\n    $parser-\u003edisallowAlphabeticUnits();\r\n    ```\r\n\r\n3. Parse string and return a `DateTimeImmutable` object. If second argument is `true`, method will return `false` when no date\u0026time strings found. If third parameter is provided, then it is filled with the string obtained after all the transformations.\r\n    ```php\r\n    $datetime = $parser-\u003eparse(fgets(STDIN));\r\n    // next call returns false\r\n    $datetime = $parser-\u003eparse('abc', true);\r\n    // $result will contains \"we will come \"\r\n    $datetime = $parser-\u003eparse('We will come in a week', true, $result);\r\n    ```\r\n4. 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.\r\n    ```\r\n    use wapmorgan\\TimeParser\\TimeParser;\r\n\r\n    // $string will contains alphabetic value for advanced parsing. \r\n    // Ex.: for string \"in twenty five minutes\", it will contains \"twenty five\".\r\n    // $lang will contains name of the parsed language.\r\n    TimeParser::setWordsToNumberCallback(function($string, $lang) {\r\n        // do some magic\r\n    });\r\n    ```\r\n5. You can add your own custom language.\r\n    ```php\r\n    // $date must be an array with a structure like the existing rules.\r\n    $parser-\u003eaddLanguage($data);\r\n    ```\r\n\r\n## Languages support\r\nFor this moment four languages supported: Russian, English, French and German. Two languages support is in progress: Chinese, Spanish.\r\nTheir rules are in `rules` catalog so you can improve TimeParser by adding new language or by improving existing one.\r\n\r\nLanguages with examples of strings containing date\u0026time:\r\n\r\n| Language | Example                                                                                                                                                                                   |\r\n|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\r\n| chinese  | 15:12:13 下星期一 下年 二月 経由15小时 経由10分钟 経由11秒钟 経由5年 経由2星期 経由1天 経由10月                                                                                                     |\r\n| english  | 15 december 1977 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                                        |\r\n| french   | 15:12:13 prochaine lundi prochaine année février bout de 15 heures bout de 10 minutes bout de 11 secondes bout de 5 années bout de 2 semaines bout de 1 jour bout de 10 mois              |\r\n| german   | 15:12:13 nächsten montag nächsten jahr im februar nach 15 uhr nach 10 minuten nach 11 secunden nach 5 jahre nach 2 wochen nach 1 tag nach 10 monate                                       |\r\n| russian  | 15 декабря 1977 года в 15:12:13 в следующий понедельник в следующем году в феврале через 15 часов через 10 минут через 11 секунд через 5 лет через 2 недели через 1 день через 10 месяцев |\r\n| spanish  | 15:12:13 el próximo lunes en próximo año en febrero en 15 horas en 10 minutos en 11 segundos en 5 años en 2 semanas en 1 día en 10 meses                                                  |\r\n\r\nFor developing reasons you may would like to see process of parsing. To do this call related methods:\r\n\r\n```php\r\nTimeParser::enableDebug();\r\n// and\r\nTimeParser::disableDebug();\r\n```\r\n\r\n### Parsable substrings\r\nTo understand, how it works, look at substrings separately:\r\n\r\n* **15 december 1977** - absolute date\r\n* **at 15:12:13** - absolute time\r\n* **next monday** or **this friday** - absolute date\r\n* **next year** or **2016 year** - absolute date\r\n* **in february** or **next month** - absolute date\r\n* **next week** - absolute date\r\n* **in 15 hours** - relative time\r\n* **in 10 minutes** - relative time\r\n* **in 11 seconds** - relative time\r\n* **in 2 weeks** - relative date\r\n* **in 1 day** - relative date\r\n* **in 10 months** - relative date\r\n* **через час** - relative date (russian, english only)\r\n* **in a hour** - relative date (russian, english only)\r\n* **через двадцать пять минут** - relative date (russian, english only)\r\n* **in twenty five minutes** - relative date (russian, english only)\r\n* **пять минут назад** - relative date (russian, english only)\r\n* **five minutes ago** - relative date (russian, english only)\r\n* **5 минут назад** - relative date (russian, english only)\r\n* **5 minutes ago** - relative date (russian, english only)\r\n* **вчера** - relative date (russian, english only)\r\n* **yesterday** - relative date (russian, english only)\r\n\r\n## ToDo\r\n\r\n- [x] Tests.\r\n- [ ] Try to parse combinations: *in 5 hours and 2 minutes*.\r\n- [x] Try to parse alphabetic offsets: *in five hours* and *через пять часов*.\r\n\r\n### Languages ToDo\r\n\r\n- [x] Chinese - check hieroglyphs.\r\n- [x] Spanish - check prepositions.\r\n- [ ] Portuguese\r\n- [ ] Arabic\r\n- [ ] Korean\r\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwapmorgan%2Ftimeparser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwapmorgan%2Ftimeparser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwapmorgan%2Ftimeparser/lists"}