百科.dev
全部条目在线工具AI 编程趋势榜开源项目技术资讯提交条目
登录
< 返回工具列表
D

date-time

> 编程语言
开源

适用于 PHP 的日期和时间库

361 stars0 点赞0 次浏览
访问官网GitHub

工具介绍

适用于 PHP 的日期和时间库

Brick\DateTime

A powerful set of immutable classes to work with dates and times. Introduction

This library builds an extensive API on top of the native PHP date-time classes, and adds missing concepts such as LocalDate, LocalTime, YearMonth, MonthDay, etc.

The classes follow the ISO 8601 standard for representing date and time concepts.

This component follows an important part of the JSR 310 (Date and Time API) specification from Java. Don't expect an exact match of class and method names though, as a number of differences exist for technical or practical reasons.

All the classes are immutable, they can be safely passed around without being affected.

Installation

This library is installable via Composer:

bash
composer require brick/date-time

Requirements

This library requires PHP 8.2 or later.

Project status & release process

While this library is still under development, it is well tested and should be stable enough to use in production environments.

The current releases are numbered 0.x.y. When a non-breaking change is introduced (adding new methods, optimizing existing code, etc.), y is incremented.

When a breaking change is introduced, a new 0.x version cycle is always started.

It is therefore safe to lock your project to a given release cycle, such as 0.9.*.

If you need to upgrade to a newer release cycle, check the release history for a list of changes introduced by each further 0.x.0 version.

Overview

Main classes

The following classes/enums represent the date-time concepts:

  • DayOfWeek: a day-of-week such as Monday (enum)
  • Duration: a duration measured in seconds and nanoseconds
  • Instant: a point in time, with a nanosecond precision
  • Interval: a period of time between two instants
  • LocalDate: an isolated date such as 2014-08-31
  • LocalDateRange: an inclusive range of local dates, such as 2014-01-01/2014-12-31
  • LocalDateTime: a date-time without a time-zone, such as 2014-08-31T10:15:30
  • LocalTime: an isolated time such as 10:15:30
  • Month: a month-of-year such as January (enum)
  • MonthDay: a combination of a month and a day, without a year, such as --12-31
  • Period: a date-based amount of time, such as '2 years, 3 months and 4 days'
  • TimeZoneOffset: an offset-based time-zone, such as +01:00
  • TimeZoneRegion: a region-based time-zone, such as Europe/London
  • Year: a year in the proleptic calendar
  • YearMonth: a combination of a year and a month, such as 2014-08
  • ZonedDateTime: a date-time with a time-zone, such as 2014-08-31T10:15:30+01:00. This class is conceptually equivalent to the native DateTime class

These classes belong to the Brick\DateTime namespace.

Clocks

All objects read the current time from a Clock implementation. The following implementations are available:

  • SystemClock returns the system time; it's the default clock
  • FixedClock: returns a pre-configured time
  • OffsetClock: adds an offset to another clock
  • ScaleClock: makes another clock fast-forward by a scale factor

These classes belong to the Brick\DateTime\Clock namespace.

In your application, you will most likely never touch the defaults, and always use the default clock:

php
use Brick\DateTime\LocalDate;
use Brick\DateTime\TimeZone;

echo LocalDate::now(TimeZone::utc()); // 2017-10-04

In your tests however, you might need to set the current time to test your application in known conditions. To do this, you can either explicitly pass a Clock instance to now() methods:

php
use Brick\DateTime\Clock\FixedClock;
use Brick\DateTime\Instant;
use Brick\DateTime\LocalDate;
use Brick\DateTime\TimeZone;

$clock = new FixedClock(Instant::of(1000000000));
echo LocalDate::now(TimeZone::utc(), $clock); // 2001-09-09

Or you can change the default clock for all date-time classes. All methods such as now(), unless provided with an explicit Clock, will use the default clock you provide:

php
use Brick\DateTime\Clock\FixedClock;
use Brick\DateTime\DefaultClock;
use Brick\DateTime\Instant;
use Brick\DateTime\LocalDate;
use Brick\DateTime\TimeZone;

DefaultClock::set(new FixedClock(Instant::of(1000000000)));
echo LocalDate::now(TimeZone::utc()); // 2001-09-09

DefaultClock::reset(); // do not forget to reset the clock to the system clock!

There are also useful shortcut methods to use clocks in your tests, inspired by timecop:

  • freeze() freezes time to a specific point in time
  • travelTo() travels to an Instant in time, but allows time to continue moving forward from there
  • travelBy() travels in time by a Duration, which may be forward (positive) or backward (negative)
  • scale() makes time move at a given pace

Freeze the time to a specific point

php
use Brick\DateTime\DefaultClock;
use Brick\DateTime\Instant;

DefaultClock::freeze(Instant::of(2000000000));

$a = Instant::now(); sleep(1);
$b = Instant::now();

echo $a, PHP_EOL; // 2033-05-18T03:33:20Z
echo $b, PHP_EOL; // 2033-05-18T03:33:20Z

DefaultClock::reset();

Travel to a specific point in time

php
use Brick\DateTime\DefaultClock;
use Brick\DateTime\Instant;

DefaultClock::travelTo(Instant::of(2000000000));
$a = Instant::now(); sleep(1);
$b = Instant::now();

echo $a, PHP_EOL; // 2033-05-18T03:33:20.000342Z
echo $b, PHP_EOL; // 2033-05-18T03:33:21.000606Z

DefaultClock::reset();

Make time move at a given pace

php
use Brick\DateTime\DefaultClock;
use Brick\DateTime\Instant;

DefaultClock::travelTo(Instant::of(2000000000));
DefaultClock::scale(60); // 1 second becomes 60 seconds

$a = Instant::now(); sleep(1);
$b = Instant::now();

echo $a, PHP_EOL; // 2033-05-18T03:33:20.00188Z
echo $b, PHP_EOL; // 2033-05-18T03:34:20.06632Z

DefaultClock::reset();

As you can see, you can even combine travelTo() and scale() methods.

Be very careful to reset() the DefaultClock after each of your tests! If you're using PHPUnit, a good place to do this is in the tearDown() method.

Exceptions

The following exceptions can be thrown:

  • Brick\DateTime\DateTimeException when an illegal operation is performed
  • Brick\DateTime\Parser\DateTimeParseException when parse()ing an invalid string representation

Doctrine mappings

You can use brick/date-time types in your Doctrine entities using the brick/date-time-doctrine package.

Contributing

Before submitting a pull request, you can check the code using the following tools. Your CI build will fail if any of the following tools reports any issue.

First of all, install dependencies:

bash
composer install

Unit tests

Run PHPUnit tests:

bash
vendor/bin/phpunit

Static analysis

Install PHPStan in its own folder:

bash
composer install --working-dir=tools/phpstan

Run PHPStan static analysis:

bash
tools/phpstan/vendor/bin/phpstan --configuration=tools/phpstan/phpstan.neon

Coding Style

Install Easy Coding Standard in its own folder:

bash
composer install --working-dir=tools/ecs

Run coding style analysis checks:

bash
tools/ecs/vendor/bin/ecs check --config tools/ecs/ecs.php

Or fix issues found directly:

bash
tools/ecs/vendor/bin/ecs check --config tools/ecs/ecs.php --fix

Rector automated refactoring

Install Rector in its own folder:

bash
composer install --working-dir=tools/rector

Run automated refactoring:

bash
tools/rector/vendor/bin/rector --config tools/rector/rector.php

Issues· 0 开放

查看全部 Issues在 GitHub 打开

暂无开放 Issues,或尚未同步最近议题。

> 标签

PHPdate-timephptimezone

暂无评论,来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日
最后更新2026年9月17日
分类编程语言
定价开源

> 相关工具

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言