@@ -77,9 +77,67 @@ echo $today->modify('+3 hours');
7777
7878Like instances of ` Chronos ` , ` ChronosDate ` objects are also * immutable* .
7979
80+ # Time-only Values
81+
82+ When you need to work with just times (without dates), use ` ChronosTime ` :
83+
84+ ``` php
85+ use Cake\Chronos\ChronosTime;
86+
87+ $time = new ChronosTime('14:30:00');
88+ echo $time->format('g:i A'); // 2:30 PM
89+
90+ // Create from components
91+ $time = ChronosTime::create(14, 30, 0);
92+
93+ // Arithmetic
94+ $later = $time->addHours(2)->addMinutes(15);
95+ ```
96+
97+ ` ChronosTime ` is useful for recurring schedules, business hours, or any scenario
98+ where the date is irrelevant.
99+
100+ # Testing with Chronos
101+
102+ Chronos provides ` setTestNow() ` to freeze time during testing:
103+
104+ ``` php
105+ use Cake\Chronos\Chronos;
106+
107+ // Freeze time for predictable tests
108+ Chronos::setTestNow('2024-01-15 10:00:00');
109+
110+ $now = Chronos::now(); // Always 2024-01-15 10:00:00
111+
112+ // Reset to real time
113+ Chronos::setTestNow(null);
114+ ```
115+
116+ # PSR-20 Clock Interface
117+
118+ For dependency injection, use ` ClockFactory ` which implements PSR-20:
119+
120+ ``` php
121+ use Cake\Chronos\ClockFactory;
122+
123+ $clock = new ClockFactory('UTC');
124+ $now = $clock->now(); // Returns Chronos instance
125+
126+ // In your service
127+ class OrderService
128+ {
129+ public function __construct(private ClockInterface $clock) {}
130+
131+ public function createOrder(): Order
132+ {
133+ return new Order(createdAt: $this->clock->now());
134+ }
135+ }
136+ ```
137+
80138# Documentation
81139
82- A more descriptive documentation can be found at [ book.cakephp.org/chronos/3/en/ ] ( https://book.cakephp.org/chronos/3/en / ) .
140+ A more descriptive documentation can be found at [ book.cakephp.org/chronos/3/] ( https://book.cakephp.org/chronos/3/ ) .
83141
84142# API Documentation
85143
0 commit comments