PHPackages matt-harvey/civil-date-time - 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. matt-harvey/civil-date-time ActiveLibrary[Utility & Helpers](/categories/utility) matt-harvey/civil-date-time =========================== Civil date and time library for PHP v0.2.1(3y ago)13479[2 issues](https://github.com/matt-harvey/civil-date-time/issues)MITPHPPHP >=8.1.0 Since May 7Pushed 3y ago1 watchersCompare [ Source](https://github.com/matt-harvey/civil-date-time)[ Packagist](https://packagist.org/packages/matt-harvey/civil-date-time)[ Docs](https://github.com/matt-harvey/civil-date-time)[ RSS](/packages/matt-harvey-civil-date-time/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependencies (1)Versions (4)Used By (0) civil-date-time =============== [](#civil-date-time) [![Github actions Build](https://github.com/matt-harvey/civil-date-time/workflows/tests/badge.svg)](https://github.com/matt-harvey/civil-date-time/actions/workflows/check.yml)[![Latest Stable Version](https://camo.githubusercontent.com/ddd809d110c999820625053603f7f2d404a268e2e3d95f965c726a213dc84809/687474703a2f2f706f7365722e707567782e6f72672f6d6174742d6861727665792f636976696c2d646174652d74696d652f76)](https://packagist.org/packages/matt-harvey/civil-date-time)[![Total Downloads](https://camo.githubusercontent.com/e43fa4b363643a5be43efd489a8d3e37acc7c5d726d9c946e4450b3869756a7b/687474703a2f2f706f7365722e707567782e6f72672f6d6174742d6861727665792f636976696c2d646174652d74696d652f646f776e6c6f616473)](https://packagist.org/packages/matt-harvey/civil-date-time)[![Latest Unstable Version](https://camo.githubusercontent.com/5cca5677f2e618c49f6a58020e9405ba6d8c5ac1e47c92b5600fea6fcf3b50cd/687474703a2f2f706f7365722e707567782e6f72672f6d6174742d6861727665792f636976696c2d646174652d74696d652f762f756e737461626c65)](https://packagist.org/packages/matt-harvey/civil-date-time)[![License](https://camo.githubusercontent.com/4d002bf185dea340bb0764c7fcb67fafcd01a88067bd878774b0d1a0c0a83756/687474703a2f2f706f7365722e707567782e6f72672f6d6174742d6861727665792f636976696c2d646174652d74696d652f6c6963656e7365)](https://packagist.org/packages/matt-harvey/civil-date-time)[![PHP Version Require](https://camo.githubusercontent.com/1aaabcb74f7d3c9b270e35bdcdbfc0d215666d53b77fb6d0cee5df37c594d02a/687474703a2f2f706f7365722e707567782e6f72672f6d6174742d6861727665792f636976696c2d646174652d74696d652f726571756972652f706870)](https://packagist.org/packages/matt-harvey/civil-date-time) > a civil date and time library for PHP Motivation ---------- [](#motivation) A *civil date*, or civil time, is a date/time without any timezone specified. Such an entity should not be used for representing a precise, absolute moment or period in time. However, it is a good way to represent the concept of a "calendar date" or "clock time" as it is used in many everyday contexts. For example, if someone was born on 1 January 2000, then they will typically want to celebrate their birthday on 1 January each year, in *whichever* timezone they happen to be living in at the time. In other words, the entity "1 January 2000", insofar as it represents their date of birth, is timezone-agnostic. In a software context, this might be important if, for example, we want to send an email to each user on their birthday, where each user may have a different timezone associated with them. A given user's timezone might change over time; but their date of birth will not. It is with the user that the timezone should be associated here—not with their date of birth. While it's possible to use the standard library's `DateTime` or `DateTimeImmutable` to represent civil dates and times in PHP, it isn't ideal, as it requires an out-of-band convention about how to interpret the timezone information attached to such an object. (Should the timezone data *merely* be ignored? Should the date time be converted to UTC and *then* have its timezone ignored? Or should non-UTC `DateTime`s be considered invalid as representations of civil dates?) A dedicated class, that omits timezone information by design, allows civil dates, times, and date-time pairings, to be represented cleanly and directly. For additional concrete use cases for civil dates, times, and date-times, see [this](https://github.com/golang/go/issues/19700#issuecomment-557820096)comment in relation to a similar library proposed for Go. Installation ------------ [](#installation) ``` composer require matt-harvey/civil-date-time ``` Note this library is still in a pre-v1 state, and there may be breaking changes in any release. (Although, I will generally avoid making breaking changes in patch version releases.) Usage ----- [](#usage) There are three classes offered: - `CivilDate` - `CivilTime` - `CivilDateTime` Each of these is immutable: methods such as `CivilDate::addDays()` always return new instances, rather than mutating the existing one. ### Civil dates [](#civil-dates) ``` use MattHarvey\CivilDateTime\CivilDate; // 15 March 2022 new CivilDate(2022, 3, 15); // or... CivilDate::fromIsoDateStamp('2022-03-15'); // format - signature mirrors \DateTime::format CivilDate::fromIsoDateStamp('2022-03-15')->format('D j M Y'); // 'Sat 15 Mar 2022' // convenience method for ISO format CivilDate::fromIsoDateStamp('2022-03-15')->toIsoDateStamp(); // 2022-03-15 // or just CivilDate::fromIsoDateStamp('2022-03-15')->__toString(); // 2022-03-15 // converting from standard library \DateTimeInterface to CivilDate // e.g., the moment that is 1:30pm in UTC on 22 Jan. 2021, falls on 23 January 2021 in Sydney $dateTime = new DateTimeImmutable('2021-01-22 13:30:01+0'); $sydney = new DateTimeZone('Australia/Sydney'); CivilDate::forMomentInTimezone($dateTime, $sydney); // 23 January 2021 // immutable addition/subtraction of days CivilDate::fromIsoDateStamp('2022-03-15')->addDays(3); // 18 March 2022 CivilDate::fromIsoDateStamp('2022-03-15')->addDays(-3); // 12 March 2022 // difference in days $dayA = CivilDate::fromIsoDateStamp('2010-03-05'); $dayB = CivilDate::fromIsoDateStamp('2010-04-05'); CivilDate::diffDays($dayB, $dayA); // 31 CivilDate::diffDays($dayA, $dayB); // -31 // comparison $dayB->laterThan($dayA); // true // extracting components $dayA->getYear(); // 2010 $dayA->getMonth(); // 3 $dayA->getDay(); // 5 ``` ### Civil times [](#civil-times) ``` use MattHarvey\CivilDateTime\CivilTime; $civilTime = new CivilTime(22, 11, 18); // 10:11:18 p.m. CivilTime::from24HoursStamp('22:11:18'); // 10:11:18 p.m. CivilTime::from12HourClock(10, 11, 18, CivilTime::PM); // 10:11:18 p.m. $civilTime->get24Hour(); // 22 $civilTime->get12Hour(); // 10 $civilTime->getMinute(); // 11 $civilTime->getSecond(); // 18 $civilTime->getAmPm(); // 'pm' $civilTime->to24HourStamp(); // '22:11:18' $civilTimeB = new CivilTime(22, 11, 19); $civilTimeB->laterThan($civilTime); // true ``` ### Civil date/times [](#civil-datetimes) ``` use MattHarvey\CivilDateTime\CivilTime; use MattHarvey\CivilDateTime\CivilDate; use MattHarvey\CivilDateTime\CivilDateTime; $civilDate = new CivilDate(2022, 3, 15); $civilTime = new CivilTime(22, 11, 18); $civilDateTime = new CivilDateTime($civilDate, $civilTime); // 10:11:18 p.m. on 15 Mar. 2022 CivilDateTime::fromIsoDateTimeStamp('2022-03-15T22:11:18'); $sydney = new DateTimeZone('Australia/Sydney'); $civilDateTime = new DateTimeImmutable('2021-06-26 20:34:05+10'); CivilDateTime::forMomentInTimezone($dateTime, $sydney); // 26 Jun. 2021, 8:34:05pm // convert back $civilDateTime->toDateTimeImmutable('Australia/Sydney'); // 26 Jun. 2021, 8:34:05pm, Australia/Sydney // or $civilDateTime->toDateTimeImmutable('Australia/Perth'); // 26 Jun. 2021, 8:34:05pm, Australia/Perth ``` Civil date/time in other PHP libraries -------------------------------------- [](#civil-datetime-in-other-php-libraries) - offers the `LocalDate`, `LocalTime` and `LocalDateTime`classes, that are analogous to `civil-date-time`'s `CivilDate`, `CivilTime` and `CivilDateTime`. It also offers classes for modelling many other date/time concepts, which `civil-date-time` doesn't do—including `ZonedDateTime` as a replacement for the standard library `DateTimeImmutable`. You might prefer it to `civil-date-time` if you're looking for a more extensive set of date/time utilities, rather than a minimal adjunct to the standard library to plug just the civil date/time gap. - offers a `Date` class, which is notionally similar to `civil-date-time`'s `CivilDate`; however it extends `DateTimeImmutable` and so carries a lot of redundant data as well as no-op functions inherited from the latter. Civil date/time libraries in other programming languages -------------------------------------------------------- [](#civil-datetime-libraries-in-other-programming-languages) - Go: - C++: Contributing ------------ [](#contributing) PRs, bug reports, and suggestions are all welcome. Please ensure unit test coverage is maintained. You will need `xdebug` installed to generate the coverage report. `composer test` runs the test suite. ### Health Score 26 — LowBetter than 43% of packages Maintenance17 Infrequent updates — may be unmaintained Popularity19 Limited adoption so far Community7 Small or concentrated contributor base Maturity49 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% 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 ~3 days Total 3 Last Release 1459d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/b92046d7067a88a8fa81cd464784b3cf41d1e2cc691613fd574770e69747e8e1?d=identicon)[matt-harvey](/maintainers/matt-harvey) --- Top Contributors [![matt-harvey](https://avatars.githubusercontent.com/u/6045346?v=4)](https://github.com/matt-harvey "matt-harvey (29 commits)") --- Tags timedatecivilcivil datecivil timecivil date time ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/matt-harvey-civil-date-time/health.svg) ``` [![Health](https://phpackages.com/badges/matt-harvey-civil-date-time/health.svg)](https://phpackages.com/packages/matt-harvey-civil-date-time) ``` ### Alternatives [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)[florianv/business DateTime calculations in business hours 359775.9k1](/packages/florianv-business) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)