PHPackages s-mcdonald/chronicle - 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. s-mcdonald/chronicle ActiveLibrary[Utility & Helpers](/categories/utility) s-mcdonald/chronicle ==================== A Lightweight utility for Dealing with Date and Time in PHP 0.0.1(3y ago)09MITPHPPHP >=8.1 Since May 10Pushed 3y ago1 watchersCompare [ Source](https://github.com/s-mcdonald/Chronicle)[ Packagist](https://packagist.org/packages/s-mcdonald/chronicle)[ Docs](https://github.com/s-mcdonald/Chronicle)[ RSS](/packages/s-mcdonald-chronicle/feed)WikiDiscussions develop Synced 1mo ago READMEChangelog (1)Dependencies (3)Versions (3)Used By (0) Chronicle ========= [](#chronicle) [![Source](https://camo.githubusercontent.com/b0fa7fe0a303018e8c3063b1480830471bb56c9f5ea456aca9d16eb312905baa/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f736f757263652d535f4d63446f6e616c642d626c75652e737667)](https://github.com/s-mcdonald/Chronicle)[![Source](https://camo.githubusercontent.com/46ed314e73590919c29d4f70d8319d8462b1d8fcc9892ec2902cdb34f2ddf6fa/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d676f6c642e737667)](https://github.com/s-mcdonald/Chronicle) `Chronicle` is a Date and Time package that provides fluent expression and functionality to manage the Date and Time in your PHP program. The Chronicle object has some common useful functions ``` Chronicle::isLeapYear(2028); // true Chronicle::agoText($date1, $date2); // 3 day ago ``` The Date object represents just the date, no time, so there is no timezone component. You can express your date in fluent/chainable commands, and every value returned is both immutable, and a new object. ``` $today = Date::create(6,11, 2024); $today->nextFortnight()->addDays(1)->getDayOfWeek(); // Thursday ``` Comparing a current month to a prior month can be tricky in some applications. This is because not every month has the same number of days. Both `Chronicle` and the `Date` object have a method that can handle comparing date easily. ``` /// /// Period Shifting /// $feb29 = Date::create(29,2, 2024); $feb29->getSameDayLastMonth(); // 29-01-2024 $feb29->getSameDayLastMonth(DateShiftRule::Business); // 31-01-2024 $feb29->getSameDayLastMonth(DateShiftRule::Strict); // 29-01-2024 $july31 = Date::create(31,7, 2024); $july31->getSameDayLastMonth(DateShiftRule::PhpCore); // 01-07-2024 $july31->getSameDayLastMonth(DateShiftRule::Business); // 30-06-2024 $july31->getSameDayLastMonth(DateShiftRule::Strict); // 30-06-2024 $today->greaterThan($date); // true $today->shiftToFirstDayOfMonth(); // 01-11-2024 $today->shiftToLastDayOfMonth(); // 30-11-2024 ``` #### Clock [](#clock) ``` echo "\n\n\nChronicle: Clock\n---------------------\n"; $clock = new Clock(); for ($i = 0; $i < 5; $i++) { sleep(1); echo $clock->getTime(), PHP_EOL; } echo "\n\n\nChronicle: FrozenClock\n---------------------\n"; $frozen = new FrozenClock($clock->getDateTimeImmutable()); for ($i = 0; $i < 5; $i++) { sleep(1); echo $frozen->getTime(), PHP_EOL; } ``` produces the following output ``` Chronicle: Clock --------------------- 12:21:07.758297 12:21:10.759012 12:21:13.759637 12:21:16.759783 12:21:19.760419 Chronicle: FrozenClock --------------------- 12:21:19.760695 12:21:19.760695 12:21:19.760695 12:21:19.760695 12:21:19.760695 ``` #### Time (object) [](#time-object) Chronicle also comes with a Time class. As this is a time class, there is no notion of a date, so like the Date object, there is no need for a timezone. This is purely to assist in displaying and formatting time and converting between object types. Time object is immutable. ``` $time = Time::create(3,15,20,500); $time->getHour(); // 3 $time->getMinute(); // 15 $time->getSeconds(); // 20 $time->getMicroseconds(); // 500 $time->getUnixTimestamp(); // -62170007072 $time->getTimestamp(); // -62170007072 $time->toShortTimeString(); // 03:15 AM $time->toLongTimeString(); // 03:15:20 AM $time->toMySqlDateTimeString(); // 00-00-00 03:15:20 ``` #### More examples [](#more-examples) Most of the Chronicle methods are dealing with the current date or time. So for the values presented, the examples were executed on `12-05-2023`` ``` /// /// Chronicle class /// Chronicle::createDate(1,1,1969); // 01-01-1969 Chronicle::dateNow(); // 12-05-2023 Chronicle::dateLastWeek(); // 05-05-2023 Chronicle::dateNextWeek(); // 19-05-2023 Chronicle::dateTomorrow(); // 13-05-2023 Chronicle::dateYesterday(); // 11-05-2023 Chronicle::dateLastFortnight(); // 28-04-2023 Chronicle::dateNextFortnight(); // 26-05-2023 Chronicle::sameDayLastMonth(); // 12-04-2023 Chronicle::sameDayLastMonth(DateShiftRule::Business); // 12-04-2023 Chronicle::sameDayLastMonth(DateShiftRule::Strict); // 12-04-2023 Chronicle::dayOfWeek(); // Friday Chronicle::monthOfYear(); // May Chronicle::agoText($date1, $date2); // 1 day ago Chronicle::getWeekOfYear("2023-01-23"); // 4 Chronicle::weekOfYear(); // int value representing current week of the year Chronicle::isLeapYear(2028); // true /// /// Date (as created as 1/November/2024) /// $today = Date::create(6,11, 2024); $today->getDay(); // 6 $today->getMonth(); // 11 $today->getYear(); // 2024 $today->addDays(3); // 09-11-2024 $today->subDays(9); // 28-10/2024 $today->subMoths(1); // 06-12-2024 $today->subMoths(1)->addMonths(2); // 06-12-2024 $today->addYears(3); // 06-11-2027 $today->subYears(9); // 06-11-2015 $today->getTimestamp(); // 1730811600 $today->getUnixTimestamp(); // 1730811600 $today->toMySqlDateTimeString(); // 2024-11-06 00:00:00 $date = new DateTime("1/1/2005"); $today->greaterThan($date); // true $today->shiftToFirstDayOfMonth(); // 01-11-2024 $today->shiftToLastDayOfMonth(); // 30-11-2024 $today->tomorrow(); // 07-11-2024 $today->yesterday(); // 05-11-2024 $today->lastWeek(); // 30-10-2024 $today->nextWeek(); // 13-11-2024 $today->lastFortnight(); // 23-10-2024 $today->nextFortnight(); // 20-11-2024 $today->getDayOfWeek(); // Wednesday $today->lastFortnight()->getDayOfWeek(); // Wednesday $today->nextFortnight()->tomorrow()->getDayOfWeek(); // Thursday $today->nextFortnight()->addDays(1)->getDayOfWeek(); // Thursday $today->getWeekOfYear(); // 45 $today->setYear(2024)->isLeapYear(); // true /// /// String formatting /// $today->asYmd(DateSeperator::Dash); // 2024-11-06 $today->asYmd(DateSeperator::ForwardSlash); // 2024/11/06 $today->toShortDateString(); // 2024-11-06 $today->toUSShortDateString(); // 11-06-2024 $today->toLongDateString(); // Wednesday 6th of November 2024 $today->getDayOfWeek(); // Wednesday $today->getMonthOfYear(); // November $today->getDayOfWeekInt(); // 3 $today->toAbbreviatedDayMonthYearString(); // Wed, Nov 06, 2024 $today->toAbbreviatedMonthDayString(); // Nov 6 /// /// Period Shifting /// $feb29 = Date::create(29,2, 2024); $feb29->getSameDayLastMonth(); // 29-01-2024 $feb29->getSameDayLastMonth(DateShiftRule::Business); // 31-01-2024 $feb29->getSameDayLastMonth(DateShiftRule::Strict); // 29-01-2024 $july31 = Date::create(31,7, 2024); $july31->getSameDayLastMonth(DateShiftRule::PhpCore); // 01-07-2024 $july31->getSameDayLastMonth(DateShiftRule::Business); // 30-06-2024 $july31->getSameDayLastMonth(DateShiftRule::Strict); // 30-06-2024 /// /// Static methods /// Date::createFromDateTimeInterface(new DateTime("now")); Date::createFromTimestamp(string $timestamp); // example Date::createFromTimestamp("1730811600"); Date::create(int $day, int $month, int $year); Date::today(); Date::dateNextWeek(); Date::dateLastWeek(); Date::dateTomorrow(); Date::dateYesterday(); Date::dateLastFortnight(); Date::dateNextFortnight(); Date::validateDateString(); ``` Documentation ------------- [](#documentation) - [Installation](#installation) - [Dependencies](#dependencies) Installation ------------ [](#installation) Via Composer. Run the following command from your project's root. ``` composer require s-mcdonald/chronicle ``` Dependencies ------------ [](#dependencies) - Php 8.0 License ------- [](#license) Chronicle is licensed under the terms of the [MIT License](http://opensource.org/licenses/MIT)(See LICENSE file for details). ### Health Score 20 — LowBetter than 14% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity4 Limited adoption so far Community7 Small or concentrated contributor base Maturity44 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 Unknown Total 1 Last Release 1104d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/1759b23f11dcfe1753788c7d3fe306af5bfcb11d1e199ccee0b8ad04b70bc00a?d=identicon)[S-McDonald](/maintainers/S-McDonald) --- Top Contributors [![s-mcdonald](https://avatars.githubusercontent.com/u/1879824?v=4)](https://github.com/s-mcdonald "s-mcdonald (5 commits)") --- Tags psr-20datetimetimedatechronicle ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/s-mcdonald-chronicle/health.svg) ``` [![Health](https://phpackages.com/badges/s-mcdonald-chronicle/health.svg)](https://phpackages.com/packages/s-mcdonald-chronicle) ``` ### Alternatives [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)[kartik-v/php-date-formatter A Javascript datetime formatting and manipulation library using PHP date-time formats. 461.5M3](/packages/kartik-v-php-date-formatter)[dater/dater Compact PHP library for working with date/time in different formats & timezones. 14282.3k](/packages/dater-dater) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)