Weave Code
Chronos Laravel Package
cakephp/chronos
Chronos is an immutable date and datetime library for PHP. It offers Chronos and ChronosDate objects that prevent accidental modification, keeping data predictable, and adds handy conveniences beyond native DateTime. Install via Composer with cakephp/chronos.
CakePHP Chronos is a lightweight library for immutable date and datetime objects. By preventing accidental mutation, it keeps date values predictable and free of side effects—every modification returns a new instance instead of changing the original.
It also provides ChronosDate, which freezes the time at 00:00:00 in the server's default timezone, making it ideal for calendar-date handling.
- Immutable by design — no accidental side effects
- ChronosDate for timezone-safe calendar dates
- Familiar, expressive DateTime-style API
- Carbon-inspired, but no longer extends PHP's DateTime classes
- Install with
composer require cakephp/chronos
Frequently asked questions about Chronos
- How do I install CakePHP Chronos in a Laravel project?
- Run composer require cakephp/chronos, which pulls in the standalone library with no CakePHP framework dependency. The package requires PHP 8.1 or newer, and some newer features such as createFromTimestamp() need PHP 8.4. Once installed, import Cake\Chronos\Chronos and call Chronos::now() or new Chronos('2015-10-21 16:29:00') just like Carbon. No service provider registration is required for basic usage.
- What is the difference between cakephp/chronos and nesbot/carbon?
- Chronos was originally based on Carbon but has diverged and no longer extends PHP's DateTime or DateTimeImmutable classes. Both libraries offer immutable date objects, but Chronos intentionally keeps a smaller API surface instead of Carbon's broad Laravel-specific helpers. Carbon ships with Laravel by default and offers conveniences such as parse(), while Chronos focuses on predictable immutable values plus ChronosDate and ChronosTime types. Chronos provides toCarbon() and fromCarbon() adapters so you can bridge legacy Carbon code during a migration.
- Why does my Chronos modify() call not change the date?
- Chronos objects are immutable, so modify(), addDay(), and similar methods return a new instance instead of mutating the original. Writing $date->modify('+2 hours') without assignment silently discards the change, which is a common gotcha when migrating from mutable DateTime code. Always reassign the result, for example $date = $date->modify('+2 hours').
- What is ChronosDate and when should I use it instead of Chronos?
- ChronosDate represents a calendar date with its time component frozen at 00:00:00 and the timezone set to the server default. It is ideal for birthdays, invoice dates, business-day calculations, and any domain value where time-of-day is meaningless. Calling modify('+3 hours') on a ChronosDate still returns the same calendar date, so accidental time drift cannot occur. Use the full Chronos datetime type when you actually need a time component.
- How do I use Chronos datetime values with Laravel Eloquent models?
- Chronos has no native Eloquent model binding, so you map it yourself with attribute casts or custom accessors and mutators. A typical cast looks like 'created_at' => Chronos::class, or you can wrap values in an accessor that converts a database DateTime into a Chronos instance. When writing back to the database, format the Chronos object to a string your column accepts. Test both read and write paths, since column types such as DATE and TIME behave differently from DATETIME.
- How can I freeze time in PHPUnit tests with Chronos?
- Chronos provides setTestNow() and withTestNow() so you can pin the current time during tests, which removes flakiness from time-sensitive assertions. Use withTestNow() when you want the freeze automatically restored after the callback, or setTestNow(null) to reset manually. For dependency injection, the ClockFactory and ClockInterface support PSR-20 clocks and integrate cleanly with Laravel's service container. Add a regression test if any time-only field can carry sub-second input, because Chronos 3.5.1 now surfaces fractional seconds.
- Is Chronos compatible with Laravel and which PHP versions are supported?
- Chronos requires PHP 8.1 or newer, and specific features such as createFromTimestamp() require PHP 8.4, so check your deployment constraints first. It is a framework-agnostic library that works fine inside Laravel because Composer autoloading is the only integration needed. It does not register a Laravel service provider and does not ship Laravel-specific helpers, so write your own wrappers where needed. Verify that your Laravel version's PHP requirement matches before adding the dependency.
- How do I do daylight saving time safe date math with Chronos?
- Use elapsed-time helpers such as addElapsedHours() when you mean real hours passing rather than wall-clock hours, which avoids off-by-one errors across DST transitions. Wall-clock methods like addHours() preserve the local time and can therefore skip or repeat an hour. This distinction matters for billing, compliance reporting, and scheduled jobs that run at fixed intervals. Write tests around the DST boundaries your application actually operates in.
- What changed in Chronos 3.5.1 for ChronosTime fractional seconds?
- Chronos 3.5.1 fixes ChronosTime so fractional seconds are parsed as true fractions of a second instead of being mis-parsed or dropped. The API surface is unchanged and there are no deprecations, so upgrading from 3.5.0 with a ^3.5.1 constraint is a patch-level change. The output shape can differ, so audit MySQL TIME columns (only TIME(n) stores fractional seconds), API payloads, snapshot tests, and any equality or hash-key comparisons. Sub-second use cases like telemetry, media timestamps, and duration logging are materially more trustworthy after the fix.
- Should I replace all Carbon usage with Chronos, and what are the risks?
- Most teams start by adopting Chronos for new immutable value objects rather than rewriting every Carbon call at once, because Chronos 3.x has diverged and does not extend DateTime. Migration requires replacing Carbon::now() with Chronos::now(), updating mutation-style arithmetic to reassignment, and wrapping Carbon-only helpers such as parse(). Keep in mind that immutable objects can increase memory usage in high-throughput batch jobs, so benchmark critical paths against Carbon. Also confirm that no legacy code depends on Carbon's DateTime extension behavior before removing it.
Weaver
How can I help you explore Laravel packages today?