How to migrate from Carbon to Chronos in PHP?

Migration involves replacing Carbon instances with Chronos and adapting to its immutable API, which requires reassigning all modified datetime objects. Refer to the README's 'Differences with nesbot/carbon' section and external documentation for specific guidance on breaking changes.

Chronos vs Carbon: which one should I use for a new project?

Choose Chronos if you prioritize strict immutability and side-effect-free datetime handling, especially for critical applications like financial systems. Opt for Carbon if you need a larger ecosystem, more features, or seamless integration with existing Carbon-based code.

How to handle time zones with Chronos in PHP?

Chronos supports time zones through its constructors and methods, similar to PHP's DateTime. Use the ClockFactory for PSR-20 compliance or specify time zones when creating instances, ensuring consistent handling across your application.

Can Chronos be used for date arithmetic without time components?

Yes, use ChronosDate for date-only arithmetic, where time is fixed at 00:00:00. This prevents time-related side effects, making it suitable for calendar calculations like adding days or months without worrying about time zones.

How to test with frozen time in Chronos without affecting other tests?

Use setTestNow() to freeze time at a specific datetime during tests, and reset it to null afterward to avoid side effects. This method is demonstrated in the README and ensures predictable test results across your suite.

Is Chronos compatible with PHP 8.2 or newer versions?

Yes, Chronos supports modern PHP versions; check the version map in the README for minimum and maximum PHP requirements. It's regularly updated to maintain compatibility with recent PHP releases and standards.

Chronos — Immutable DateTime Library for PHP

What is Chronos?

Chronos is a standalone PHP library for handling dates and times, focusing on immutable objects to prevent accidental modifications. It provides datetime, date-only, and time-only objects with a clean API, originally based on Carbon but now independent. It solves the problem of unpredictable datetime mutations in applications by enforcing immutability.

Target Audience

PHP developers building applications that require reliable and predictable datetime handling, such as scheduling systems, calendar features, or financial applications. It's also suitable for developers who need PSR-20 compliance or enhanced testing capabilities.

Value Proposition

Developers choose Chronos for its strict immutability, which eliminates side-effects and accidental datetime changes, ensuring data integrity. It offers additional utilities like calendar dates and time-only objects, along with testing support, making it more comprehensive than basic PHP datetime functions.

A standalone DateTime library originally based off of Carbon

Use Cases

Best For

Building applications where datetime consistency is critical, like financial or scheduling systems
Implementing calendar features that require date-only operations without time components
Handling time-only data such as business hours or recurring schedules
Writing predictable and reliable unit tests by freezing time with `setTestNow()`
Adopting PSR-20 standards for dependency injection in modern PHP applications
Replacing Carbon with a more focused and immutable datetime library

Not Ideal For

Projects requiring mutable datetime objects for in-place modifications and performance optimizations
Teams with extensive Carbon-based codebases seeking a drop-in replacement without refactoring
Simple, one-off scripts where the overhead of immutability and reassignment adds unnecessary complexity

Pros & Cons

Pros

Strict Immutability

Enforces immutability to prevent accidental datetime changes, ensuring predictable and side-effect-free code as emphasized in the README's philosophy.

Calendar Date Support

Provides ChronosDate for date-only operations with time frozen at 00:00:00, ideal for handling calendar features without time interference.

Time-Only Handling

Includes ChronosTime for scenarios like schedules or business hours, with dedicated methods such as addHours() for arithmetic on time-only values.

Testing Utilities

Offers setTestNow() to freeze time during unit tests, making results predictable and reliable, as demonstrated in the README examples.

PSR-20 Compliance

Implements ClockFactory for the PSR-20 interface, facilitating dependency injection and modern PHP application standards.

Cons

Mandatory Reassignment Overhead

Requires developers to always reassign modified objects, as shown in the README where failing to do so loses changes, which can be error-prone and less intuitive than mutable alternatives.

Carbon Incompatibility

Diverges from Carbon and no longer extends PHP's DateTime classes, breaking compatibility and making migration from Carbon non-trivial without API adjustments.

Smaller Ecosystem

Has a smaller community and fewer third-party extensions compared to Carbon, which may limit support, integrations, and available learning resources.

Frequently Asked Questions

What is Chronos?

Target Audience

Value Proposition

Use Cases

Best For

Building applications where datetime consistency is critical, like financial or scheduling systems
Implementing calendar features that require date-only operations without time components
Handling time-only data such as business hours or recurring schedules
Writing predictable and reliable unit tests by freezing time with `setTestNow()`
Adopting PSR-20 standards for dependency injection in modern PHP applications
Replacing Carbon with a more focused and immutable datetime library

Not Ideal For

Projects requiring mutable datetime objects for in-place modifications and performance optimizations
Teams with extensive Carbon-based codebases seeking a drop-in replacement without refactoring
Simple, one-off scripts where the overhead of immutability and reassignment adds unnecessary complexity

Pros & Cons

Pros

Strict Immutability

Enforces immutability to prevent accidental datetime changes, ensuring predictable and side-effect-free code as emphasized in the README's philosophy.

Calendar Date Support

Provides ChronosDate for date-only operations with time frozen at 00:00:00, ideal for handling calendar features without time interference.

Time-Only Handling

Includes ChronosTime for scenarios like schedules or business hours, with dedicated methods such as addHours() for arithmetic on time-only values.

Testing Utilities

Offers setTestNow() to freeze time during unit tests, making results predictable and reliable, as demonstrated in the README examples.

PSR-20 Compliance

Implements ClockFactory for the PSR-20 interface, facilitating dependency injection and modern PHP application standards.

Cons

Mandatory Reassignment Overhead

Requires developers to always reassign modified objects, as shown in the README where failing to do so loses changes, which can be error-prone and less intuitive than mutable alternatives.

Carbon Incompatibility

Diverges from Carbon and no longer extends PHP's DateTime classes, breaking compatibility and making migration from Carbon non-trivial without API adjustments.

Smaller Ecosystem

Has a smaller community and fewer third-party extensions compared to Carbon, which may limit support, integrations, and available learning resources.

Frequently Asked Questions

Chronos

What is Chronos?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?

Chronos

What is Chronos?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?