PHPackages                             flying/date - 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. flying/date

ActiveLibrary[Utility & Helpers](/categories/utility)

flying/date
===========

DateTime generator with support for adjusting current time

v2.0.0(2y ago)017MITPHPPHP ^8.1

Since Aug 25Pushed 2y ago1 watchersCompare

[ Source](https://github.com/FlyingDR/date)[ Packagist](https://packagist.org/packages/flying/date)[ RSS](/packages/flying-date/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (1)Versions (10)Used By (0)

date
====

[](#date)

`DateTime` generator with support for adjusting current time.

Purpose
-------

[](#purpose)

The main purpose of the library is to assist testing application in time-sensitive scenarios without a need to adjust its code (besides switching to use library itself for creating dates in application).

It is relatively simple to test time-sensitive scenarios for unit tests, but for functional tests it is much harder. Of course, there are plenty of solutions:

- [`slope-it/clock-mock`](https://packagist.org/packages/slope-it/clock-mock) looks great, but depends on the PHP extension.
- [`lcobucci/clock`](https://packagist.org/packages/lcobucci/clock) is very popular, but requires dependency on its own `Clock` object which would require updates of signatures of functions and methods and types of class properties.
- [Clock mocking](https://symfony.com/doc/current/components/phpunit_bridge.html#clock-mocking) in Symfony's PHPUnit bridge only mocks time-related functions, not `\DateTimeInterface` based classes.

This library aims to keep the number of required changes at a level comparable with other solutions. Required [updates for the code](#usage-in-application) are listed below and basically limited to change of `\DateTime` constructor methods into call to static method of the different class. It also simplifies testing cases when code execution took some time and this time change used somehow (think of performance tracking as an example).

General information
-------------------

[](#general-information)

Whole API is exposed as a single `\Flying\Date\Date` class. API is provided as a set of static methods to make sure that they will be accessible from any part of code without a need to introduce any kind of additional dependencies.

Generated date objects are limited to `\DateTimeImmutable`. Upcoming `ClockInterface` from [PSR-20](https://github.com/php-fig/fig-standards/blob/master/proposed/clock.md) also provides only immutable dates.

Main API methods - [`now`](#now) and [`from`](#from) returning `\DateTimeImmutable` instances, whose values can be adjusted relative to the actual current time by providing a time shifting interval using [`adjust`](#adjust) method.

Usage in application
--------------------

[](#usage-in-application)

In order to benefit from the ability to use time shifting, it is required to update parts of your code which creates new instances of the `\DateTime` or `\DateTimeInterval` objects.

To get `\DateTime` object it is required to convert obtained `\DateTimeInterval` object:

```
$mutableDateTime = \DateTime::createFromImmutable($immutableDateTime);
```

### Creating objects for current time and default timezone

[](#creating-objects-for-current-time-and-default-timezone)

- Before: `new \DateTimeImmutable()`
- After: `\Flying\Date\Date::now()`

### Creating objects for arbitrary time and / or timezone

[](#creating-objects-for-arbitrary-time-and--or-timezone)

#### Creating from string

[](#creating-from-string)

- Before: `new \DateTimeImmutable('2022-08-01', new \DateTimeZone('UTC'))`
- After: `\Flying\Date\Date::from('2022-08-01', 'UTC')`

#### Creating from format

[](#creating-from-format)

- Before: `\DateTimeImmutable::createFromFormat(\DateTimeInterface::ATOM, 2022-08-01T12:23:34Z')`
- After: `\Flying\Date\Date::fromFormat(\DateTimeInterface::ATOM, '2022-08-01T12:23:34Z')`

Usage in tests
--------------

[](#usage-in-tests)

In order to test application behavior in different points of time, you need to do two things:

1. Provide date adjustment value by calling `\Flying\Date\Date::adjust()` and pass either `\DateTimeInterface` that represents new target date or `\DateInterval` to define time shift relatively to the current time. Calling `adjust()` with no arguments removes date adjustment.
2. Enable date adjustment by calling `\Flying\Date\Date::allowAdjustment(true)`

**IMPORTANT!** You should never use date adjustment in your application's code, ONLY IN TESTS! Use of it in application's code may result in unexpected behavior!

Even in tests, you should limit use of this feature to the tests which actually needs date adjustment functionality and disable it after doing the test.

### Simplified configuration using attribute

[](#simplified-configuration-using-attribute)

In order to simplify use of the library and to ensure correct enabling / disabling of the date adjustment functionality in tests - it is possible to use `AdjustableDate` PHP attribute.

To enable use of the attribute you need to edit your PHPUnit configuration (`phpunit.xml`) and add test extension:

```

```

Then for test classes or (preferably) test methods that need to use adjustable date functionality you need to add `#[AdjustableDate]` attribute. It accepts optional configuration parameters:

- `bool $enabled` - to control default state of the adjustable date functionality (`true` by default)
- `\DateTimeZone|string|null $timezone` - to define timezone to use by default

### Note on microseconds in date adjustment

[](#note-on-microseconds-in-date-adjustment)

For time shifting interval and adjusted dates, generated by the [`now`](#now) and [`from`](#from) methods microseconds part of the resulted date is forcibly set to zero. Date objects, which are generated without a date adjustment, are **not affected**.

It should be safe because date adjustment is meant to only be used for tests. Testing time shifts with microsecond precision on intervals less than a second is more reliable with use of the `usleep()`. For larger intervals include of microseconds may introduce difference of the whole second which may cause tests to break from time to time.

API methods
-----------

[](#api-methods)

### `now`

[](#now)

Signature:

```
\Flying\Date\Date::now(): \DateTimeImmutable
```

Provides the date object for the current date. Either timezone, defined through [`setTimezone()`](#settimezone) or PHP default timezone is used.

In case if date adjustment is enabled - returned date will be adjusted by the defined time shifting interval.

### `from`

[](#from)

Signature:

```
\Flying\Date\Date::from(\DateTimeInterface|\DateInterval|string $date, \DateTimeZone|string|null $timezone = null): \DateTimeImmutable
```

Create the date object for a given arbitrary point of time from provided date and timezone information. Either given timezone, timezone defined through [`setTimezone()`](#settimezone) or PHP default timezone is used. It is allowed to pass valid timezone name as timezone value.

In case if date adjustment is enabled - returned date will be adjusted by the defined time shifting interval.

### `fromFormat`

[](#fromformat)

Signature:

```
\Flying\Date\Date::fromFormat(string $format, string $datetime, \DateTimeZone|string|null $timezone = null): \DateTimeImmutable|bool
```

Create the date object for given date string, formatted using given format using given timezone information. Either given timezone, timezone defined through [`setTimezone()`](#settimezone) or PHP default timezone is used. It is allowed to pass valid timezone name as timezone value.

In case if date adjustment is enabled - returned date will be adjusted by the defined time shifting interval.

### `getTimezone`

[](#gettimezone)

Signature:

```
\Flying\Date\Date::getTimezone(): \DateTimeZone
```

Get timezone that is used for creating date objects.

### `setTimezone`

[](#settimezone)

Signature:

```
\Flying\Date\Date::setTimezone(\DateTimeZone|string|null $timezone = null): void
```

Defines (or resets) timezone that is used for creating date objects. It is allowed to pass valid timezone name as value.

### `adjust`

[](#adjust)

Signature:

```
\Flying\Date\Date::adjust(\DateInterval|\DateTimeInterface|string|null $adjustment = null): void
```

Defines (or resets) the time shifting interval that is used for date adjusting while creating date objects. It is allowed to define either absolute point of time by passing `\DateTimeInterface` instance or a time shift relative to the current point of time by passing `\DateInterval` object.

It is also allowed to pass [date formats](https://www.php.net/manual/en/datetime.formats.php) or [date interval](https://www.php.net/manual/en/dateinterval.construct.php) definitions.

### `getAdjustment`

[](#getadjustment)

Signature:

```
\Flying\Date\Date::getAdjustment(): ?\DateInterval
```

Returns currently defined the time shifting interval that is used for date adjusting while creating date objects.

### `allowAdjustment`

[](#allowadjustment)

Signature:

```
\Flying\Date\Date::allowAdjustment(bool $status): void
```

Allows control of the status of date adjustment functionality.

### `isAdjustmentAllowed`

[](#isadjustmentallowed)

Signature:

```
\Flying\Date\Date::isAdjustmentAllowed(): bool
```

Returns current status of date adjustment functionality.

License
-------

[](#license)

Library is licensed under [MIT License](LICENSE).

###  Health Score

26

—

LowBetter than 43% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity6

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity62

Established project with proven stability

 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 ~54 days

Recently: every ~108 days

Total

9

Last Release

925d ago

Major Versions

v1.2.3 → v2.0.02023-11-04

PHP version history (2 changes)v1.0.0PHP ^8.0

v2.0.0PHP ^8.1

### Community

Maintainers

![](https://www.gravatar.com/avatar/2219fdfdf70c7118270dfa18596299660a51d4cced164e98d139dd03b3579128?d=identicon)[Flying](/maintainers/Flying)

---

Top Contributors

[![FlyingDR](https://avatars.githubusercontent.com/u/822673?v=4)](https://github.com/FlyingDR "FlyingDR (29 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/flying-date/health.svg)

```
[![Health](https://phpackages.com/badges/flying-date/health.svg)](https://phpackages.com/packages/flying-date)
```

###  Alternatives

[mckenziearts/laravel-command

A simple Laravel package to provide artisan new commands

321.2k](/packages/mckenziearts-laravel-command)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)