feat: add more start/end convenience methods

Author: innocenzi

packages/datetime/src/DateTime.php

@@ -8,7 +8,6 @@
 use IntlCalendar;
 use Tempest\Clock\Clock;
 use Tempest\Container\GenericContainer;
-use Tempest\DateTime\Exception\UnexpectedValueException;
 use Tempest\Support\Language\Locale;
 
 /**
@@ -520,7 +519,55 @@ public function startOfDay(): static
      */
     public function endOfDay(): static
     {
-        return $this->withTime(23, 59, 59, 999999999);
+        return $this->withTime(23, 59, 59, 999_999_999);
+    }
+
+    /**
+     * Returns a new instance set to the start of the week.
+     */
+    public function startOfWeek(): static
+    {
+        return $this->withDay($this->day - ($this->getWeekday()->value - 1))->startOfDay();
+    }
+
+    /**
+     * Returns a new instance set to the end of the week.
+     */
+    public function endOfWeek(): static
+    {
+        return $this->withDay($this->getDay() + (7 - $this->getWeekday()->value))->endOfDay();
+    }
+
+    /**
+     * Returns a new instance set to the start of the month.
+     */
+    public function startOfMonth(): static
+    {
+        return $this->withDay(1)->startOfDay();
+    }
+
+    /**
+     * Returns a new instance set to the end of the month.
+     */
+    public function endOfMonth(): static
+    {
+        return $this->withDay(Month::from($this->month)->getDaysForYear($this->year))->endOfDay();
+    }
+
+    /**
+     * Returns a new instance set to the start of the year.
+     */
+    public function startOfYear(): static
+    {
+        return $this->withDate($this->getYear(), 1, 1)->startOfDay();
+    }
+
+    /**
+     * Returns a new instance set to the end of the year.
+     */
+    public function endOfYear(): static
+    {
+        return $this->withDate($this->getYear(), 12, Month::DECEMBER->getDaysForYear($this->getYear()))->endOfDay();
     }
 
     #[\Override]

packages/datetime/src/DateTimeConvenienceMethods.php

@@ -319,7 +319,9 @@ public function getISOWeekNumber(): array
      */
     public function getWeekday(): Weekday
     {
-        return Weekday::from((int) $this->format(
+        // Settings nanoseconds to 1 to a avoid rounding
+        // errors with extreme values (eg. 999_999_999)
+        return Weekday::from((int) $this->withNanoseconds(1)->format(
             pattern: 'e',
             locale: Locale::ENGLISH_UNITED_KINGDOM,
         ));

packages/datetime/tests/DateTimeTest.php

@@ -490,8 +490,8 @@ public function test_minus_methods(): void
         $this->assertSame(59, $datetime->minusSeconds(1)->getSeconds());
         $this->assertSame(59, $datetime->minusSecond()->getSeconds());
 
-        $this->assertSame(999999999, $datetime->minusNanoseconds(1)->getNanoseconds());
-        $this->assertSame(999999999, $datetime->minusNanosecond()->getNanoseconds());
+        $this->assertSame(999_999_999, $datetime->minusNanoseconds(1)->getNanoseconds());
+        $this->assertSame(999_999_999, $datetime->minusNanosecond()->getNanoseconds());
     }
 
     public function test_minus_months_edge_cases(): void
@@ -633,6 +633,72 @@ public function test_end_of_day(): void
         $this->assertSame(999999999, $new->getNanoseconds());
     }
 
+    public function test_start_of_week(): void
+    {
+        $date = DateTime::parse('2025-05-21 12:00');
+        $new = $date->startOfWeek();
+
+        $this->assertSame(5, $new->getMonth());
+        $this->assertSame(19, $new->getDay());
+        $this->assertSame(0, $new->getHours());
+    }
+
+    public function test_end_of_week(): void
+    {
+        $date = DateTime::parse('2025-05-21 12:00');
+        $new = $date->endOfWeek();
+
+        $this->assertSame(5, $new->getMonth());
+        $this->assertSame(25, $new->getDay());
+        $this->assertSame(23, $new->getHours());
+        $this->assertSame(59, $new->getMinutes());
+        $this->assertSame(59, $new->getSeconds());
+    }
+
+    public function test_start_of_month(): void
+    {
+        $date = DateTime::parse('2025-05-21 12:00');
+        $new = $date->startOfMonth();
+
+        $this->assertSame(5, $new->getMonth());
+        $this->assertSame(1, $new->getDay());
+        $this->assertSame(Weekday::THURSDAY, $new->getWeekday());
+        $this->assertSame(0, $new->getHours());
+    }
+
+    public function test_end_of_month(): void
+    {
+        $date = DateTime::parse('2025-05-21 12:00', timezone: Timezone::EUROPE_PARIS);
+        $new = $date->endOfMonth();
+
+        $this->assertSame(5, $new->getMonth());
+        $this->assertSame(31, $new->getDay());
+        $this->assertSame(Weekday::SATURDAY, $new->getWeekday());
+        $this->assertSame(23, $new->getHours());
+        $this->assertSame(59, $new->getMinutes());
+        $this->assertSame(59, $new->getSeconds());
+    }
+
+    public function test_end_of_month_edge_cases(): void
+    {
+        $date = DateTime::parse('2025-02-21 12:00');
+        $this->assertSame(2, $date->endOfMonth()->getMonth());
+        $this->assertSame(28, $date->endOfMonth()->getDay());
+        $this->assertSame(Weekday::FRIDAY, $date->endOfMonth()->getWeekday());
+
+        $date = DateTime::parse('2024-02-21 12:00');
+        $this->assertSame(2, $date->endOfMonth()->getMonth());
+        $this->assertSame(29, $date->endOfMonth()->getDay());
+        $this->assertSame(Weekday::THURSDAY, $date->endOfMonth()->getWeekday());
+
+        $date = DateTime::parse('2024-12-31 12:00');
+        $this->assertSame(12, $date->endOfMonth()->getMonth());
+        $this->assertSame(31, $date->endOfMonth()->getDay());
+        $this->assertSame(23, $date->endOfMonth()->getHours());
+        $this->assertSame(59, $date->endOfMonth()->getMinutes());
+        $this->assertSame(59, $date->endOfMonth()->getSeconds());
+    }
+
     public function test_timezone_info(): void
     {
         $timeZone = Timezone::EUROPE_BRUSSELS;