Restructure English documentation into focused pages

docs/.vitepress/toc_en.json

@@ -1,11 +1,38 @@
 {
   "/": [
     {
-      "text": "CakePHP Chronos",
+      "text": "Getting Started",
       "collapsed": false,
       "items": [
         { "text": "Introduction", "link": "/index" },
-        { "text": "3.x Migration Guide", "link": "/3-x-migration-guide" },
+        { "text": "Creating Instances", "link": "/creating-instances" },
+        { "text": "3.x Migration Guide", "link": "/3-x-migration-guide" }
+      ]
+    },
+    {
+      "text": "Working with Chronos",
+      "collapsed": false,
+      "items": [
+        { "text": "Modifying Values", "link": "/modifying" },
+        { "text": "Comparing Values", "link": "/comparing" },
+        { "text": "Formatting & Output", "link": "/formatting" }
+      ]
+    },
+    {
+      "text": "Other Classes",
+      "collapsed": false,
+      "items": [
+        { "text": "ChronosDate", "link": "/chronos-date" },
+        { "text": "ChronosTime", "link": "/chronos-time" },
+        { "text": "Periods & Intervals", "link": "/periods-and-intervals" }
+      ]
+    },
+    {
+      "text": "Advanced",
+      "collapsed": false,
+      "items": [
+        { "text": "Testing", "link": "/testing" },
+        { "text": "Configuration", "link": "/configuration" },
         { "text": "API", "link": "https://api.cakephp.org/chronos" }
       ]
     }

docs/en/chronos-date.md

@@ -0,0 +1,172 @@
+# ChronosDate
+
+PHP provides only datetime classes that combine both date and time parts.
+Representing calendar dates can be awkward with `DateTimeImmutable` as it includes
+time and timezones, which aren't part of a "date".
+
+Chronos provides `ChronosDate` which allows you to represent dates without time.
+The time is always fixed to `00:00:00` and is not affected by the server timezone
+or modifier methods.
+
+## Creating Instances
+
+```php
+use Cake\Chronos\ChronosDate;
+
+$today = ChronosDate::today();
+$yesterday = ChronosDate::yesterday();
+$tomorrow = ChronosDate::tomorrow();
+
+// Parse from string
+$date = ChronosDate::parse('2015-12-25');
+
+// Create from components
+$date = ChronosDate::create(2015, 12, 25);
+
+// Parse with format
+$date = ChronosDate::createFromFormat('m/d/Y', '12/25/2015');
+
+// From array
+$date = ChronosDate::createFromArray([
+    'year' => 2015,
+    'month' => 12,
+    'day' => 25,
+]);
+```
+
+## Timezone for "Today"
+
+Although `ChronosDate` uses a fixed internal timezone, you can specify which
+timezone to use for determining the current date:
+
+```php
+// Takes the current date from Asia/Tokyo timezone
+$today = ChronosDate::today('Asia/Tokyo');
+```
+
+This is useful when you need "today" in a specific timezone that differs from
+the server's timezone.
+
+## Time is Ignored
+
+Time modifications have no effect on ChronosDate:
+
+```php
+$today = ChronosDate::today();
+
+// Time modifications are ignored
+$today->modify('+1 hour');  // Still the same date
+
+// Outputs just the date: '2015-12-20'
+echo $today;
+```
+
+## Available Methods
+
+ChronosDate includes most of the same modifier and comparison methods as Chronos,
+but without time-related operations:
+
+### Modifiers
+
+```php
+$date = ChronosDate::today();
+
+// Add/subtract time periods
+$date->addDays(5);
+$date->subWeeks(2);
+$date->addMonths(3);
+$date->addYears(1);
+
+// Jump to boundaries
+$date->startOfMonth();
+$date->endOfMonth();
+$date->startOfYear();
+$date->endOfYear();
+$date->startOfWeek();
+$date->endOfWeek();
+
+// Day of week navigation
+$date->next(Chronos::MONDAY);
+$date->previous(Chronos::FRIDAY);
+$date->firstOfMonth(Chronos::TUESDAY);
+$date->lastOfMonth(Chronos::SUNDAY);
+```
+
+### Comparisons
+
+```php
+$date1 = ChronosDate::parse('2015-12-25');
+$date2 = ChronosDate::parse('2015-12-31');
+
+$date1->equals($date2);
+$date1->lessThan($date2);
+$date1->greaterThan($date2);
+$date1->between($start, $end);
+
+// Calendar checks
+$date->isToday();
+$date->isYesterday();
+$date->isTomorrow();
+$date->isFuture();
+$date->isPast();
+$date->isWeekend();
+$date->isWeekday();
+$date->isMonday();
+// etc.
+```
+
+### Differences
+
+```php
+$date1->diffInDays($date2);
+$date1->diffInWeeks($date2);
+$date1->diffInMonths($date2);
+$date1->diffInYears($date2);
+$date1->diffInWeekdays($date2);
+$date1->diffInWeekendDays($date2);
+
+// Human readable
+$date1->diffForHumans($date2);  // "6 days before"
+```
+
+## Extracting Components
+
+```php
+$date = ChronosDate::parse('2015-12-25');
+
+$date->year;       // 2015
+$date->month;      // 12
+$date->day;        // 25
+$date->dayOfWeek;  // 5 (Friday)
+$date->dayOfYear;  // 359
+$date->quarter;    // 4
+```
+
+## Converting to Array
+
+```php
+$date = ChronosDate::parse('2015-12-25');
+$array = $date->toArray();
+// [
+//     'year' => 2015,
+//     'month' => 12,
+//     'day' => 25,
+//     'dayOfWeek' => 5,
+//     'dayOfYear' => 359,
+// ]
+```
+
+## Converting to DateTime
+
+If you need a full datetime, you can convert to `DateTimeImmutable`:
+
+```php
+$date = ChronosDate::parse('2015-12-25');
+
+// Convert with optional timezone
+$datetime = $date->toDateTimeImmutable();
+$datetime = $date->toDateTimeImmutable('America/New_York');
+
+// Alias
+$datetime = $date->toNative();
+```

docs/en/chronos-time.md

@@ -0,0 +1,173 @@
+# ChronosTime
+
+`ChronosTime` represents a time of day without any date component. This is useful
+for representing things like business hours, schedules, or any scenario where
+you need to work with time independently of a specific date.
+
+## Creating Instances
+
+```php
+use Cake\Chronos\ChronosTime;
+
+// Current time
+$now = ChronosTime::now();
+
+// Parse from string
+$time = ChronosTime::parse('14:30:00');
+$time = ChronosTime::parse('2:30 PM');
+
+// From a Chronos or DateTimeInterface
+$chronos = new Chronos('2015-12-25 14:30:00');
+$time = ChronosTime::parse($chronos);
+
+// Special times
+$midnight = ChronosTime::midnight();  // 00:00:00
+$noon = ChronosTime::noon();          // 12:00:00
+$endOfDay = ChronosTime::endOfDay();  // 23:59:59
+```
+
+## Getting and Setting Components
+
+```php
+$time = ChronosTime::parse('14:30:45.123456');
+
+// Getters
+$time->getHours();        // 14
+$time->getMinutes();      // 30
+$time->getSeconds();      // 45
+$time->getMicroseconds(); // 123456
+
+// Setters (return new instance)
+$time = $time->setHours(16);
+$time = $time->setMinutes(45);
+$time = $time->setSeconds(30);
+$time = $time->setMicroseconds(0);
+
+// Set all at once
+$time = $time->setTime(16, 45, 30, 0);
+```
+
+## Hour Boundaries
+
+Jump to the start or end of the current hour:
+
+```php
+$time = ChronosTime::parse('14:35:22');
+
+$time->startOfHour();  // 14:00:00
+$time->endOfHour();    // 14:59:59
+```
+
+## Comparisons
+
+ChronosTime provides comparison methods similar to Chronos:
+
+```php
+$time1 = ChronosTime::parse('09:00:00');
+$time2 = ChronosTime::parse('17:00:00');
+
+$time1->equals($time2);              // false
+$time1->greaterThan($time2);         // false
+$time1->greaterThanOrEquals($time2); // false
+$time1->lessThan($time2);            // true
+$time1->lessThanOrEquals($time2);    // true
+
+// Check if between two times
+$lunchTime = ChronosTime::parse('12:30:00');
+$lunchTime->between($time1, $time2); // true
+```
+
+## Special Time Checks
+
+```php
+$time = ChronosTime::parse('00:00:00');
+
+$time->isMidnight();    // true (00:00:00)
+$time->isStartOfDay();  // true (alias for midnight)
+$time->isMidday();      // false (checks for 12:00:00)
+$time->isEndOfDay();    // false (checks for 23:59:59)
+```
+
+## Formatting
+
+```php
+$time = ChronosTime::parse('14:30:45');
+
+// Default format (H:i:s)
+echo $time;  // "14:30:45"
+
+// Custom format
+echo $time->format('g:i A');  // "2:30 PM"
+echo $time->format('H:i');    // "14:30"
+```
+
+### Custom Default Format
+
+You can change the default string format:
+
+```php
+ChronosTime::setToStringFormat('g:i A');
+echo ChronosTime::parse('14:30:00');  // "2:30 PM"
+
+// Reset to default
+ChronosTime::resetToStringFormat();
+```
+
+## Converting to Array
+
+```php
+$time = ChronosTime::parse('14:30:45.123456');
+$array = $time->toArray();
+// [
+//     'hour' => 14,
+//     'minute' => 30,
+//     'second' => 45,
+//     'microsecond' => 123456,
+// ]
+```
+
+## Converting to DateTime
+
+If you need a full datetime, you can convert to `DateTimeImmutable`:
+
+```php
+$time = ChronosTime::parse('14:30:00');
+
+// Converts to today at the given time
+$datetime = $time->toDateTimeImmutable();
+
+// With specific timezone
+$datetime = $time->toDateTimeImmutable('America/New_York');
+
+// Alias
+$datetime = $time->toNative();
+```
+
+## Use Cases
+
+### Business Hours
+
+```php
+$openTime = ChronosTime::parse('09:00:00');
+$closeTime = ChronosTime::parse('17:00:00');
+$now = ChronosTime::now();
+
+if ($now->between($openTime, $closeTime)) {
+    echo "We're open!";
+}
+```
+
+### Scheduling
+
+```php
+$meetingTime = ChronosTime::parse('14:00:00');
+$currentTime = ChronosTime::now();
+
+if ($currentTime->lessThan($meetingTime)) {
+    echo "Meeting hasn't started yet";
+} elseif ($currentTime->equals($meetingTime)) {
+    echo "Meeting is starting now!";
+} else {
+    echo "Meeting has started";
+}
+```