PHPackages alex-patterson-webdev/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. alex-patterson-webdev/date-time ActiveLibrary alex-patterson-webdev/date-time =============================== DateTime factory components for PHP 0.6.1(3y ago)12.0k—0%[1 PRs](https://github.com/alex-patterson-webdev/date-time/pulls)3MITPHPPHP >=8.1 Since May 1Pushed 1y ago1 watchersCompare [ Source](https://github.com/alex-patterson-webdev/date-time)[ Packagist](https://packagist.org/packages/alex-patterson-webdev/date-time)[ RSS](/packages/alex-patterson-webdev-date-time/feed)WikiDiscussions master Synced 1mo ago READMEChangelog (4)Dependencies (6)Versions (6)Used By (3) [![build](https://github.com/alex-patterson-webdev/date-time/actions/workflows/workflow.yml/badge.svg)](https://github.com/alex-patterson-webdev/date-time/actions/workflows/workflow.yml/badge.svg)[![codecov](https://camo.githubusercontent.com/64ec1861b2b1ddf30fdf8162578658b38f83a30c1322ad2e58c27ad978417c1b/68747470733a2f2f636f6465636f762e696f2f67682f616c65782d706174746572736f6e2d7765626465762f646174652d74696d652f6272616e63682f6d61737465722f67726170682f62616467652e737667)](https://codecov.io/gh/alex-patterson-webdev/date-time)[![Scrutinizer Code Quality](https://camo.githubusercontent.com/eacd5301425694d5fa7d8a39bfb78d5bdd7dab41ac6884f03af38c7f87ca939a/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f616c65782d706174746572736f6e2d7765626465762f646174652d74696d652f6261646765732f7175616c6974792d73636f72652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/alex-patterson-webdev/date-time/?branch=master) Arp\\DateTime ============= [](#arpdatetime) About ----- [](#about) The library provides implementations of the [PSR-20 Clock](https://www.php-fig.org/psr/psr-20/) `ClockInterface` and a number of factories which abstract the creation of native PHP DateTime objects. Installation ------------ [](#installation) Installation via [composer](https://getcomposer.org). ``` require alex-patterson-webdev/date-time ^0.6 ``` Theory ------ [](#theory) By abstracting the creation of Date Time objects behind a simple collection of interfaces, we can allow developers to treat date time creation as a service. The `Arp\DateTime\DateTimeFactory` can be used as a replacement for any code that would normally require `new \DateTime()`. Consider an example `UserService::updateLastLoginDate()` method; designed to update a user's last login date with the current date and time. ``` class UserService { public function updateLastLoginDate($user) { $user->setLastLoginDate(new \DateTime()); } } ``` This approach, while simple, would be difficult to assert a value for the 'current time' in a unit test. Alternatively, we could update this example to include the `DateTimeFactory`, which would abstract the creation of the `\DateTime` object. ``` class UserService { private DateTimeFactoryInterface $dateTimeFactory; public function __construct(DateTimeFactoryInterface $dateTimeFactory) { $this->dateTimeFactory = $dateTimeFactory; } public function updateLastLoginDate($user) { $user->setLastLoginDate($this->dateTimeFactory->createDateTime()); } } ``` The approach has a number of notable benefits - The `DateTimeFactoryInterface` provides an abstraction for all `\DateTime` object creation. - Unit testing and asserting date time values becomes very easy as we can now mock the return value of `$this->dateTimeFactory->createDateTime()`. - Rather than returning a boolean `false` when unable to create date objects, the factory classes will instead throw a `DateTimeException`. DateTimeFactoryInterface ------------------------ [](#datetimefactoryinterface) The `DateTimeFactoryInterface` exposes two public methods, `createDateTime()` and `createFromFormat()`. The method signatures are similar to the PHP `\DateTime` methods. ``` interface DateTimeFactoryInterface { /** * @throws DateTimeFactoryException */ public function createDateTime(?string $spec = null, $timeZone = null): \DateTimeInterface; /** * @throws DateTimeFactoryException */ public function createFromFormat(string $format, string $spec, $timeZone = null): \DateTimeInterface; } ``` The `createDateTime()` method can replace uses of [\\DateTime::\_\_construct](https://www.php.net/manual/en/datetime.construct.php). The `createFromFormat()` method can replace uses of [\\DateTime::createFromFormat()](https://www.php.net/manual/en/datetime.createfromformat.php). There are however a number of differences to consider. - The methods of the interface are defined as non-static and require a factory instance to invoke them. - A `DateTimeFactoryException` will be thrown if the `\DateTime` instance cannot be created. - The `$spec` parameter of `createDateTime()` accepts `null`. Passing `null` is equivalent to using the current date and time, i.e. `now`. - The `$timeZone` can be either a `string` or `\DateTimeZone` instance. If a [supported `DateTimeZone` string](https://www.php.net/manual/en/timezones.php)is provided, the `\DateTimeZone` instance will be created internally; otherwise a `DateTimeFactoryException` will be thrown. ### Implementations [](#implementations) The package provides two default implementations of the `DateTimeFactoryInterface`. - `DateTimeFactory` can be used to create `\DateTime` instances. - `DateTimeImmutableFactory` can be used to create `\DateTimeImmutible` instances Because both classes implement the `DateTimeFactoryInterface`, they can be used in the same way. ``` $dateTimeFactory = new \Arp\DateTime\DateTimeFactory(); $dateTimeImmutableFactory = new \Arp\DateTime\DateTimeImmutableFactory(); try { /** @var \DateTime $dateTime **/ $dateTime = $dateTimeFactory->createDateTime(); /** @var \DateTimeImmutable $dateTimeImmutable **/ $dateTimeImmutable = $dateTimeImmutableFactory->createDateTime(); } catch (\DateTimeFactoryException $e) { // if the date creation fails } ``` ### DateTimeZoneFactory [](#datetimezonefactory) `\DateTimeZone` instances can be created using any class that implements `Arp\DateTime\DateTimeZoneFactoryInterface`. ``` /* * @throws DateTimeZoneFactoryException */ public function createDateTimeZone(string $spec): \DateTimeZone; ``` The default implementation of the interface is `Arp\DateTime\DateTimeZoneFactory`. ``` $dateTimeZoneFactory = new \Arp\DateTime\DateTimeZoneFactory(); try { /** @var \DateTimeZone $dateTimeZone **/ $dateTimeZone = $dateTimeZoneFactory->createDateTimeZone('UTC'); } catch (\DateTimeZoneFactoryException $e) { // The \DateTimeZone() could not be created } ``` ### PSR-20 ClockInterface [](#psr-20-clockinterface) Using the PSR standards provides implementing projects interoperability between other packages by creating a standard way of accessing the current time. The package provides a number of implementations of the [PSR-20 Clock](https://www.php-fig.org/psr/psr-20/) interface. - `Arp\DateTime\Psr\Clock` A default implementation of `Psr\Clock\ClockInterface` where a desired DateTimeZone can be provided. - `Arp\DateTime\Psr\SystemClock` An implementation of `Psr\Clock\ClockInterface` that will always provide the current time using the configured system timezone. - `Arp\DateTime\Psr\FixedClock` An implementation of `Psr\Clock\ClockInterface` that will always return a fixed `\DateTimeImmutable`; which can be useful in testing. Example usages ``` use Arp\DateTime\DateTimeImmutableFactory; use Arp\DateTime\Psr\SystemClock; // Fetch the current time using the UTC timezone $clock = new Clock(new DateTimeImmutableFactory(), 'UTC'); $utcTime = $clock->now(); // Fetch the current time using the systems configured timezone $clock = new SystemClock(new DateTimeImmutableFactory()); $systemTime = $clock->now(); // Calls to FixedClock::now() will always return the same time provided in the constructor $clock = new FixedClock(new \DateTimeImmutable()); $fixedTime = $clock->now(); ``` Unit tests ---------- [](#unit-tests) Unit tests can be executed using PHPUnit from the application root directory. ``` php vendor/bin/phpunit ``` ### Health Score 32 — LowBetter than 72% of packages Maintenance30 Infrequent updates — may be unmaintained Popularity22 Limited adoption so far Community12 Small or concentrated contributor base Maturity54 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 ~236 days Total 4 Last Release 1125d ago PHP version history (2 changes)0.4.0PHP >=7.4 || >=8.0 0.6.0PHP >=8.1 ### Community Maintainers ![](https://www.gravatar.com/avatar/8ffd0597cab058e2b719b482a502868f91eb143581b159835d7a97c5da302f8f?d=identicon)[alex-patterson-webdev](/maintainers/alex-patterson-webdev) --- Top Contributors [![alex-patterson-webdev](https://avatars.githubusercontent.com/u/1563851?v=4)](https://github.com/alex-patterson-webdev "alex-patterson-webdev (116 commits)") ### Code Quality TestsPHPUnit Static AnalysisPHPStan Code StylePHP CS Fixer Type Coverage Yes ### Embed Badge ![Health badge](/badges/alex-patterson-webdev-date-time/health.svg) ``` [![Health](https://phpackages.com/badges/alex-patterson-webdev-date-time/health.svg)](https://phpackages.com/packages/alex-patterson-webdev-date-time) ``` ### Alternatives [symfony/symfony The Symfony PHP framework 31.3k86.3M2.2k](/packages/symfony-symfony)[kreait/firebase-php Firebase Admin SDK 2.4k39.7M72](/packages/kreait-firebase-php)[cakephp/chronos A simple API extension for DateTime. 1.4k47.7M121](/packages/cakephp-chronos)[nesbot/carbon An API extension for DateTime that supports 281 different languages. 169661.4M4.8k](/packages/nesbot-carbon)[simplesamlphp/saml2 SAML2 PHP library from SimpleSAMLphp 30317.2M40](/packages/simplesamlphp-saml2)[eventsauce/eventsauce A pragmatic event sourcing library for PHP with a focus on developer experience. 8632.1M47](/packages/eventsauce-eventsauce) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)