PHPackages icecave/chrono - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Utility & Helpers](/categories/utility) 4. / 5. icecave/chrono ActiveLibrary[Utility & Helpers](/categories/utility) icecave/chrono ============== A date & time library that is decoupled from the system clock. 2.0.0(5y ago)54188.9k—8.7%2[29 issues](https://github.com/icecave/chrono/issues)7MITPHPPHP >=7.2CI failing Since May 6Pushed 5y ago3 watchersCompare [ Source](https://github.com/icecave/chrono)[ Packagist](https://packagist.org/packages/icecave/chrono)[ Docs](https://github.com/icecave/chrono)[ RSS](/packages/icecave-chrono/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (10)Dependencies (6)Versions (12)Used By (7) Chrono ====== [](#chrono) [![Build Status](https://camo.githubusercontent.com/25809b4e672f771c932ac5374aec0efc6423a124fd54b26f9686a0492e981491/687474703a2f2f696d672e736869656c64732e696f2f7472617669732f696365636176652f6368726f6e6f2f6d61737465722e7376673f7374796c653d666c61742d737175617265)](https://travis-ci.org/icecave/chrono)[![Code Coverage](https://camo.githubusercontent.com/6cd39e49825350c180d21f815e5b717f640febd027bef3ddf42756b60c322a40/68747470733a2f2f696d672e736869656c64732e696f2f636f6465636f762f632f6769746875622f696365636176652f6368726f6e6f2f6d61737465722e7376673f7374796c653d666c61742d737175617265)](https://codecov.io/github/icecave/chrono)[![Latest Version](https://camo.githubusercontent.com/f0115d26ff8d8d6863d3b50fed7895d4596511ef4b3e05d91b0d9e36d5a5fd4c/687474703a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f696365636176652f6368726f6e6f2e7376673f7374796c653d666c61742d737175617265266c6162656c3d73656d766572)](https://semver.org) **Chrono** is a PHP date & time library that is decoupled from the system clock. ``` composer require icecave/chrono ``` Rationale --------- [](#rationale) Many date & time operations in the core PHP libraries require access to system state such as the current wall time, or resources such as timezone databases. These hard-wired dependencies can make it very difficult to write well-abstracted and testable code when dealing with time-sensitive operations. **Chrono** provides a set of date & time classes that are completely decoupled from the system and hence behave consistently, regardless of system state and configuration (such as the [date.timezone INI directive](http://www.php.net/manual/en/datetime.configuration.php#ini.date.timezone)). A [SystemClock](src/Clock/SystemClock.php) instance must be explicitly constructed before any global date & time operations are used. Classes that require use of a clock may take a [ClockInterface](src/Clock/ClockInterface.php)as a [dependency](http://en.wikipedia.org/wiki/Dependency_injection), improving decoupling and testability. Concepts -------- [](#concepts) - [Clock](src/Clock/ClockInterface.php): A factory for chronological measurements. - [Time](src/TimeInterface.php): A chronological measurement with a time component. - [Date](src/DateInterface.php): A chronological measurement with a date component. - [Time Point](src/TimePointInterface.php): A discreet point on the time-continuum. - [Time Span](src/TimeSpan/TimeSpanInterface.php): An un-anchored span of time. - [Interval](src/Interval/IntervalInterface.php): A span of time between two *Time Points*. Implementations --------------- [](#implementations) - [System Clock](src/Clock/SystemClock.php): A factory for chronological measurements that uses the system clock. - [Test Clock](src/Clock/TestClock.php): A clock that can be manually manipulated for testing purposes. - [Date](src/Date.php): Represents a date. Models the *Time Point* and *Date* concepts. - [Time of Day](src/TimeOfDay.php): Represents a time of day. Models the *Time* concept. - [Date Time](src/DateTime.php): Represents a time of day on specific date. Models the *Time Point*, *Date* and *Time* concepts. - [Interval](src/Interval/Interval.php): A span of time between two *Time Points*. Models the *Interval* concept. - [Month](src/Interval/Month.php): A one month time span. Models the *Interval* concept. - [Year](src/Interval/Year.php): A one year time span. Models the *Interval* concept. - [Duration](src/TimeSpan/Duration.php): A time span measured in seconds with no beginning or end. Models the *Time Span* concept. - [Period](src/TimeSpan/Period.php): A time span specified in component form (eg: 3 months, 4 days), models the *Time Span* concept. Examples -------- [](#examples) ### Getting the current time [](#getting-the-current-time) In order to get the current time you need to use a [clock](src/Clock/ClockInterface.php). Most of the time in production code you will use the [SystemClock](src/Clock/SystemClock.php) class, which uses the machine's current system time and time zone information. ``` use Icecave\Chrono\Clock\SystemClock; // Construct a new system clock ... $clock = new SystemClock; // Obtain a DateTime instance representing the current date and time ... $now = $clock->localDateTime(); // Obtain a Date instance representing the current date ... $today = $clock->localDate(); // Obtain the current time of day ... $timeOfDay = $clock->localTime(); ``` Each of the clock methods shown above has a [UTC](http://en.wikipedia.org/wiki/Coordinated_Universal_Time) counterpart. For example, to obtain the current time in UTC you can use the following code: ``` $nowUtc = $clock->utcDateTime(); ``` ### String formatting [](#string-formatting) To produce a formatted string representing a [Date](src/Date.php), [DateTime](src/DateTime.php), [TimeOfDay](src/TimeOfDay.php) or [TimeZone](src/TimeZone.php) instance use the `format()`method. The output is specified using the same format as PHP's [built-in date() function](http://php.net/manual/en/function.date.php). ``` $now = $clock->localDateTime(); $string = $now->format('Y-m-d H:i:s'); ``` Casting the object as a string (or calling `isoString()`) produces an [ISO-8601](http://en.wikipedia.org/wiki/ISO_8601)string representation. ### Unix timestamps [](#unix-timestamps) [Date](src/Date.php) and [DateTime](src/DateTime.php) instances can be produced from unix timestamps using the `fromUnixTime()` static method. The unix timestamp can be retrieved using `unixTime()`. ``` $dateTime = DateTime::fromUnixTime(1367823963); $timestamp = $dateTime->unixTime(); ``` ### PHP native "DateTime" objects [](#php-native-datetime-objects) [Date](src/Date.php) and [DateTime](src/DateTime.php) instances can be produced from native PHP [DateTime](http://php.net/manual/en/class.datetime.php) instances using the `fromNativeDateTime()` static method, and can be converted to a native DateTime using `nativeDateTime()`. ``` use DateTime as NativeDateTime; use Icecave\Chrono\DateTime; $dateTime = DateTime::fromNativeDateTime(new NativeDateTime); $nativeDateTime = $dateTime->nativeDateTime(); ``` ### Health Score 38 — LowBetter than 85% of packages Maintenance9 Infrequent updates — may be unmaintained Popularity44 Moderate usage in the ecosystem Community20 Small or concentrated contributor base Maturity65 Established project with proven stability Bus Factor1 Top contributor holds 86.3% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~266 days Recently: every ~534 days Total 11 Last Release 2093d ago Major Versions 0.4.0 → 1.0.02014-09-09 1.0.4 → 2.0.02020-08-25 PHP version history (3 changes)0.1.0PHP >=5.3.3 0.3.0PHP >=5.3 2.0.0PHP >=7.2 ### Community Maintainers ![](https://www.gravatar.com/avatar/93a71bd75fcd51efee464532dbdd54927cd00e938805998c76e0a804d38fa3fb?d=identicon)[jmalloc](/maintainers/jmalloc) --- Top Contributors [![jmalloc](https://avatars.githubusercontent.com/u/761536?v=4)](https://github.com/jmalloc "jmalloc (214 commits)")[![koden-km](https://avatars.githubusercontent.com/u/1037307?v=4)](https://github.com/koden-km "koden-km (29 commits)")[![ezzatron](https://avatars.githubusercontent.com/u/100152?v=4)](https://github.com/ezzatron "ezzatron (5 commits)") --- Tags clockisotimedatetimerchrono ### Code Quality TestsPHPUnit Code StylePHP CS Fixer ### Embed Badge ![Health badge](/badges/icecave-chrono/health.svg) ``` [![Health](https://phpackages.com/badges/icecave-chrono/health.svg)](https://phpackages.com/packages/icecave-chrono) ``` ### Alternatives [symfony/clock Decouples applications from the system clock 431168.9M205](/packages/symfony-clock)[knplabs/knp-time-bundle Making your dates and durations look sensible and descriptive 6308.9M39](/packages/knplabs-knp-time-bundle)[league/period Time range API for PHP 7335.4M21](/packages/league-period)[brick/date-time Date and time library 3623.3M61](/packages/brick-date-time)[aeon-php/calendar PHP type safe, immutable calendar library 2079.7M16](/packages/aeon-php-calendar)[tplaner/when Date/Calendar recursion library. 5261.0M5](/packages/tplaner-when) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)