Skip to content

Commit 73b82b6

Browse files
dereuromarkdereuromark
authored
Restructure English documentation into focused pages (#513)
Split the monolithic index.md into dedicated pages: - Creating Instances: factory methods, timestamps, arrays - Modifying Values: setters, add/sub, boundaries, timezone - Comparing Values: comparisons, calendar checks, differences - Formatting & Output: format methods, toArray, components - ChronosDate: date-only class documentation - ChronosTime: time-only class documentation - Periods & Intervals: ChronosPeriod, ChronosDatePeriod, ChronosInterval - Testing: setTestNow, withTestNow, test setup - Configuration: week settings, localization, PSR-20 clock Added documentation for new 3.4.0 features: - withTestNow() for scoped time mocking - shiftTimezone() method - toArray() method for all classes - startOfHour()/endOfHour() for ChronosTime - Time comparison methods for ChronosTime - nextOccurrenceOf()/previousOccurrenceOf() methods Fixed typo: "affeced" -> "affected" Updated toc_en.json with organized sections.
1 parent 5c3a742 commit 73b82b6

File tree

11 files changed

+1407
-267
lines changed

11 files changed

+1407
-267
lines changed

‎docs/.vitepress/toc_en.json‎

Lines changed: 29 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,38 @@
11
{
22
"/": [
33
{
4-
"text": "CakePHP Chronos",
4+
"text": "Getting Started",
55
"collapsed": false,
66
"items": [
77
{ "text": "Introduction", "link": "/index" },
8-
{ "text": "3.x Migration Guide", "link": "/3-x-migration-guide" },
8+
{ "text": "Creating Instances", "link": "/creating-instances" },
9+
{ "text": "3.x Migration Guide", "link": "/3-x-migration-guide" }
10+
]
11+
},
12+
{
13+
"text": "Working with Chronos",
14+
"collapsed": false,
15+
"items": [
16+
{ "text": "Modifying Values", "link": "/modifying" },
17+
{ "text": "Comparing Values", "link": "/comparing" },
18+
{ "text": "Formatting & Output", "link": "/formatting" }
19+
]
20+
},
21+
{
22+
"text": "Other Classes",
23+
"collapsed": false,
24+
"items": [
25+
{ "text": "ChronosDate", "link": "/chronos-date" },
26+
{ "text": "ChronosTime", "link": "/chronos-time" },
27+
{ "text": "Periods & Intervals", "link": "/periods-and-intervals" }
28+
]
29+
},
30+
{
31+
"text": "Advanced",
32+
"collapsed": false,
33+
"items": [
34+
{ "text": "Testing", "link": "/testing" },
35+
{ "text": "Configuration", "link": "/configuration" },
936
{ "text": "API", "link": "https://api.cakephp.org/chronos" }
1037
]
1138
}

‎docs/en/chronos-date.md‎

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
# ChronosDate
2+
3+
PHP provides only datetime classes that combine both date and time parts.
4+
Representing calendar dates can be awkward with `DateTimeImmutable` as it includes
5+
time and timezones, which aren't part of a "date".
6+
7+
Chronos provides `ChronosDate` which allows you to represent dates without time.
8+
The time is always fixed to `00:00:00` and is not affected by the server timezone
9+
or modifier methods.
10+
11+
## Creating Instances
12+
13+
```php
14+
use Cake\Chronos\ChronosDate;
15+
16+
$today = ChronosDate::today();
17+
$yesterday = ChronosDate::yesterday();
18+
$tomorrow = ChronosDate::tomorrow();
19+
20+
// Parse from string
21+
$date = ChronosDate::parse('2015-12-25');
22+
23+
// Create from components
24+
$date = ChronosDate::create(2015, 12, 25);
25+
26+
// Parse with format
27+
$date = ChronosDate::createFromFormat('m/d/Y', '12/25/2015');
28+
29+
// From array
30+
$date = ChronosDate::createFromArray([
31+
'year' => 2015,
32+
'month' => 12,
33+
'day' => 25,
34+
]);
35+
```
36+
37+
## Timezone for "Today"
38+
39+
Although `ChronosDate` uses a fixed internal timezone, you can specify which
40+
timezone to use for determining the current date:
41+
42+
```php
43+
// Takes the current date from Asia/Tokyo timezone
44+
$today = ChronosDate::today('Asia/Tokyo');
45+
```
46+
47+
This is useful when you need "today" in a specific timezone that differs from
48+
the server's timezone.
49+
50+
## Time is Ignored
51+
52+
Time modifications have no effect on ChronosDate:
53+
54+
```php
55+
$today = ChronosDate::today();
56+
57+
// Time modifications are ignored
58+
$today->modify('+1 hour'); // Still the same date
59+
60+
// Outputs just the date: '2015-12-20'
61+
echo $today;
62+
```
63+
64+
## Available Methods
65+
66+
ChronosDate includes most of the same modifier and comparison methods as Chronos,
67+
but without time-related operations:
68+
69+
### Modifiers
70+
71+
```php
72+
$date = ChronosDate::today();
73+
74+
// Add/subtract time periods
75+
$date->addDays(5);
76+
$date->subWeeks(2);
77+
$date->addMonths(3);
78+
$date->addYears(1);
79+
80+
// Jump to boundaries
81+
$date->startOfMonth();
82+
$date->endOfMonth();
83+
$date->startOfYear();
84+
$date->endOfYear();
85+
$date->startOfWeek();
86+
$date->endOfWeek();
87+
88+
// Day of week navigation
89+
$date->next(Chronos::MONDAY);
90+
$date->previous(Chronos::FRIDAY);
91+
$date->firstOfMonth(Chronos::TUESDAY);
92+
$date->lastOfMonth(Chronos::SUNDAY);
93+
```
94+
95+
### Comparisons
96+
97+
```php
98+
$date1 = ChronosDate::parse('2015-12-25');
99+
$date2 = ChronosDate::parse('2015-12-31');
100+
101+
$date1->equals($date2);
102+
$date1->lessThan($date2);
103+
$date1->greaterThan($date2);
104+
$date1->between($start, $end);
105+
106+
// Calendar checks
107+
$date->isToday();
108+
$date->isYesterday();
109+
$date->isTomorrow();
110+
$date->isFuture();
111+
$date->isPast();
112+
$date->isWeekend();
113+
$date->isWeekday();
114+
$date->isMonday();
115+
// etc.
116+
```
117+
118+
### Differences
119+
120+
```php
121+
$date1->diffInDays($date2);
122+
$date1->diffInWeeks($date2);
123+
$date1->diffInMonths($date2);
124+
$date1->diffInYears($date2);
125+
$date1->diffInWeekdays($date2);
126+
$date1->diffInWeekendDays($date2);
127+
128+
// Human readable
129+
$date1->diffForHumans($date2); // "6 days before"
130+
```
131+
132+
## Extracting Components
133+
134+
```php
135+
$date = ChronosDate::parse('2015-12-25');
136+
137+
$date->year; // 2015
138+
$date->month; // 12
139+
$date->day; // 25
140+
$date->dayOfWeek; // 5 (Friday)
141+
$date->dayOfYear; // 359
142+
$date->quarter; // 4
143+
```
144+
145+
## Converting to Array
146+
147+
```php
148+
$date = ChronosDate::parse('2015-12-25');
149+
$array = $date->toArray();
150+
// [
151+
// 'year' => 2015,
152+
// 'month' => 12,
153+
// 'day' => 25,
154+
// 'dayOfWeek' => 5,
155+
// 'dayOfYear' => 359,
156+
// ]
157+
```
158+
159+
## Converting to DateTime
160+
161+
If you need a full datetime, you can convert to `DateTimeImmutable`:
162+
163+
```php
164+
$date = ChronosDate::parse('2015-12-25');
165+
166+
// Convert with optional timezone
167+
$datetime = $date->toDateTimeImmutable();
168+
$datetime = $date->toDateTimeImmutable('America/New_York');
169+
170+
// Alias
171+
$datetime = $date->toNative();
172+
```

‎docs/en/chronos-time.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# ChronosTime
2+
3+
`ChronosTime` represents a time of day without any date component. This is useful
4+
for representing things like business hours, schedules, or any scenario where
5+
you need to work with time independently of a specific date.
6+
7+
## Creating Instances
8+
9+
```php
10+
use Cake\Chronos\ChronosTime;
11+
12+
// Current time
13+
$now = ChronosTime::now();
14+
15+
// Parse from string
16+
$time = ChronosTime::parse('14:30:00');
17+
$time = ChronosTime::parse('2:30 PM');
18+
19+
// From a Chronos or DateTimeInterface
20+
$chronos = new Chronos('2015-12-25 14:30:00');
21+
$time = ChronosTime::parse($chronos);
22+
23+
// Special times
24+
$midnight = ChronosTime::midnight(); // 00:00:00
25+
$noon = ChronosTime::noon(); // 12:00:00
26+
$endOfDay = ChronosTime::endOfDay(); // 23:59:59
27+
```
28+
29+
## Getting and Setting Components
30+
31+
```php
32+
$time = ChronosTime::parse('14:30:45.123456');
33+
34+
// Getters
35+
$time->getHours(); // 14
36+
$time->getMinutes(); // 30
37+
$time->getSeconds(); // 45
38+
$time->getMicroseconds(); // 123456
39+
40+
// Setters (return new instance)
41+
$time = $time->setHours(16);
42+
$time = $time->setMinutes(45);
43+
$time = $time->setSeconds(30);
44+
$time = $time->setMicroseconds(0);
45+
46+
// Set all at once
47+
$time = $time->setTime(16, 45, 30, 0);
48+
```
49+
50+
## Hour Boundaries
51+
52+
Jump to the start or end of the current hour:
53+
54+
```php
55+
$time = ChronosTime::parse('14:35:22');
56+
57+
$time->startOfHour(); // 14:00:00
58+
$time->endOfHour(); // 14:59:59
59+
```
60+
61+
## Comparisons
62+
63+
ChronosTime provides comparison methods similar to Chronos:
64+
65+
```php
66+
$time1 = ChronosTime::parse('09:00:00');
67+
$time2 = ChronosTime::parse('17:00:00');
68+
69+
$time1->equals($time2); // false
70+
$time1->greaterThan($time2); // false
71+
$time1->greaterThanOrEquals($time2); // false
72+
$time1->lessThan($time2); // true
73+
$time1->lessThanOrEquals($time2); // true
74+
75+
// Check if between two times
76+
$lunchTime = ChronosTime::parse('12:30:00');
77+
$lunchTime->between($time1, $time2); // true
78+
```
79+
80+
## Special Time Checks
81+
82+
```php
83+
$time = ChronosTime::parse('00:00:00');
84+
85+
$time->isMidnight(); // true (00:00:00)
86+
$time->isStartOfDay(); // true (alias for midnight)
87+
$time->isMidday(); // false (checks for 12:00:00)
88+
$time->isEndOfDay(); // false (checks for 23:59:59)
89+
```
90+
91+
## Formatting
92+
93+
```php
94+
$time = ChronosTime::parse('14:30:45');
95+
96+
// Default format (H:i:s)
97+
echo $time; // "14:30:45"
98+
99+
// Custom format
100+
echo $time->format('g:i A'); // "2:30 PM"
101+
echo $time->format('H:i'); // "14:30"
102+
```
103+
104+
### Custom Default Format
105+
106+
You can change the default string format:
107+
108+
```php
109+
ChronosTime::setToStringFormat('g:i A');
110+
echo ChronosTime::parse('14:30:00'); // "2:30 PM"
111+
112+
// Reset to default
113+
ChronosTime::resetToStringFormat();
114+
```
115+
116+
## Converting to Array
117+
118+
```php
119+
$time = ChronosTime::parse('14:30:45.123456');
120+
$array = $time->toArray();
121+
// [
122+
// 'hour' => 14,
123+
// 'minute' => 30,
124+
// 'second' => 45,
125+
// 'microsecond' => 123456,
126+
// ]
127+
```
128+
129+
## Converting to DateTime
130+
131+
If you need a full datetime, you can convert to `DateTimeImmutable`:
132+
133+
```php
134+
$time = ChronosTime::parse('14:30:00');
135+
136+
// Converts to today at the given time
137+
$datetime = $time->toDateTimeImmutable();
138+
139+
// With specific timezone
140+
$datetime = $time->toDateTimeImmutable('America/New_York');
141+
142+
// Alias
143+
$datetime = $time->toNative();
144+
```
145+
146+
## Use Cases
147+
148+
### Business Hours
149+
150+
```php
151+
$openTime = ChronosTime::parse('09:00:00');
152+
$closeTime = ChronosTime::parse('17:00:00');
153+
$now = ChronosTime::now();
154+
155+
if ($now->between($openTime, $closeTime)) {
156+
echo "We're open!";
157+
}
158+
```
159+
160+
### Scheduling
161+
162+
```php
163+
$meetingTime = ChronosTime::parse('14:00:00');
164+
$currentTime = ChronosTime::now();
165+
166+
if ($currentTime->lessThan($meetingTime)) {
167+
echo "Meeting hasn't started yet";
168+
} elseif ($currentTime->equals($meetingTime)) {
169+
echo "Meeting is starting now!";
170+
} else {
171+
echo "Meeting has started";
172+
}
173+
```

0 commit comments

Comments
 (0)