add halfOfYear, isFirstHalfOfYear, IsSecondHalfOfYear; improve getter…

docs/en/index.rst

@@ -290,6 +290,7 @@ Other properties that can be accessed are:
 - daysInMonth
 - timestamp
 - quarter
+- halfOfYear
 
 Testing Aids
 ------------

docs/fr/index.rst

@@ -302,6 +302,7 @@ Les autres propriétés accessibles sont:
 - daysInMonth
 - timestamp
 - quarter
+- halfOfYear
 
 Aides aux Tests
 ---------------

docs/ja/index.rst

@@ -276,6 +276,7 @@ Chronos は、出力した日時オブジェクトを表示するための多く
 - daysInMonth
 - timestamp
 - quarter
+- halfOfYear
 
 テストの支援
 ------------

docs/pt/index.rst

@@ -258,6 +258,7 @@ Outras propriedades que podem ser acessadas são:
 - daysInMonth
 - timestamp
 - quarter
+- halfOfYear
 
 Auxílio para testes
 -------------------

src/Chronos.php

@@ -29,23 +29,24 @@
  *
  * @property-read int $year
  * @property-read int $yearIso
- * @property-read int $month
- * @property-read int $day
- * @property-read int $hour
- * @property-read int $minute
- * @property-read int $second
- * @property-read int $micro
- * @property-read int $microsecond
+ * @property-read int<1, 12> $month
+ * @property-read int<1, 31> $day
+ * @property-read int<0, 23> $hour
+ * @property-read int<0, 59> $minute
+ * @property-read int<0, 59> $second
+ * @property-read int<0, 999999> $micro
+ * @property-read int<0, 999999> $microsecond
  * @property-read int $timestamp seconds since the Unix Epoch
  * @property-read \DateTimeZone $timezone the current timezone
  * @property-read \DateTimeZone $tz alias of timezone
- * @property-read int $dayOfWeek 1 (for Monday) through 7 (for Sunday)
- * @property-read int $dayOfYear 0 through 365
- * @property-read int $weekOfMonth 1 through 5
- * @property-read int $weekOfYear ISO-8601 week number of year, weeks starting on Monday
- * @property-read int $daysInMonth number of days in the given month
+ * @property-read int<1, 7> $dayOfWeek 1 (for Monday) through 7 (for Sunday)
+ * @property-read int<0, 365> $dayOfYear 0 through 365
+ * @property-read int<1, 5> $weekOfMonth 1 through 5
+ * @property-read int<1, 53> $weekOfYear ISO-8601 week number of year, weeks starting on Monday
+ * @property-read int<1, 31> $daysInMonth number of days in the given month
  * @property-read int $age does a diffInYears() with default parameters
- * @property-read int $quarter the quarter of this instance, 1 - 4
+ * @property-read int<1, 4> $quarter the quarter of this instance, 1 - 4
+ * @property-read int<1, 2> $halfOfYear the half of the year, with 1 for months Jan...Jun and 2 for Jul...Dec.
  * @property-read int $offset the timezone offset in seconds from UTC
  * @property-read int $offsetHours the timezone offset in hours from UTC
  * @property-read bool $dst daylight savings time indicator, true if DST, false otherwise
@@ -2055,6 +2056,26 @@ public function isLastYear(): bool
         return $this->year === static::now($this->tz)->subYears(1)->year;
     }
 
+    /**
+     * Determines if the instance is within the first half of year
+     *
+     * @return bool
+     */
+    public function isFirstHalfOfYear(): bool
+    {
+        return $this->halfOfYear === 1;
+    }
+
+    /**
+     * Determines if the instance is within the second half of year
+     *
+     * @return bool
+     */
+    public function isSecondHalfOfYear(): bool
+    {
+        return $this->halfOfYear === 2;
+    }
+
     /**
      * Determines if the instance is in the future, ie. greater (after) than now
      *
@@ -2592,6 +2613,9 @@ public function __get(string $name): string|float|int|bool|DateTimeZone
             case $name === 'quarter':
                 return (int)ceil($this->month / 3);
 
+            case $name === 'halfOfYear':
+                return $this->month <= 6 ? 1 : 2;
+
             case $name === 'offset':
                 return $this->getOffset();
 

src/ChronosDate.php

@@ -30,15 +30,16 @@
  *
  * @property-read int $year
  * @property-read int $yearIso
- * @property-read int $month
- * @property-read int $day
- * @property-read int $dayOfWeek 1 (for Monday) through 7 (for Sunday)
- * @property-read int $dayOfYear 0 through 365
- * @property-read int $weekOfMonth 1 through 5
- * @property-read int $weekOfYear ISO-8601 week number of year, weeks starting on Monday
- * @property-read int $daysInMonth number of days in the given month
+ * @property-read int<1, 12> $month
+ * @property-read int<1, 31> $day
+ * @property-read int<1, 7> $dayOfWeek 1 (for Monday) through 7 (for Sunday)
+ * @property-read int<0, 365> $dayOfYear 0 through 365
+ * @property-read int<1, 5> $weekOfMonth 1 through 5
+ * @property-read int<1, 53> $weekOfYear ISO-8601 week number of year, weeks starting on Monday
+ * @property-read int<1, 31> $daysInMonth number of days in the given month
  * @property-read int $age does a diffInYears() with default parameters
- * @property-read int $quarter the quarter of this instance, 1 - 4
+ * @property-read int<1, 4> $quarter the quarter of this instance, 1 - 4
+ * @property-read int<1, 2> $halfOfYear the half of the year, with 1 for months Jan...Jun and 2 for Jul...Dec.
  * @psalm-immutable
  * @psalm-consistent-constructor
  */
@@ -1225,6 +1226,26 @@ public function isLastYear(DateTimeZone|string|null $timezone = null): bool
         return $this->year === static::now($timezone)->subYears(1)->year;
     }
 
+    /**
+     * Determines if the instance is within the first half of year
+     *
+     * @return bool
+     */
+    public function isFirstHalfOfYear(): bool
+    {
+        return $this->halfOfYear === 1;
+    }
+
+    /**
+     * Determines if the instance is within the second half of year
+     *
+     * @return bool
+     */
+    public function isSecondHalfOfYear(): bool
+    {
+        return $this->halfOfYear === 2;
+    }
+
     /**
      * Determines if the instance is in the future, ie. greater (after) than now
      *
@@ -1566,6 +1587,9 @@ public function __get(string $name): string|float|int|bool
             case $name === 'quarter':
                 return (int)ceil($this->month / 3);
 
+            case $name === 'halfOfYear':
+                return $this->month <= 6 ? 1 : 2;
+
             default:
                 throw new InvalidArgumentException(sprintf("Unknown getter '%s'", $name));
         }

tests/TestCase/Date/GettersTest.php

@@ -0,0 +1,41 @@
+<?php
+declare(strict_types=1);
+
+/**
+ * Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
+ *
+ * Licensed under The MIT License
+ * Redistributions of files must retain the above copyright notice.
+ *
+ * @copyright     Copyright (c) Cake Software Foundation, Inc. (https://cakefoundation.org)
+ * @copyright     Copyright (c) Brian Nesbitt <[email protected]>
+ * @link          https://cakephp.org CakePHP(tm) Project
+ * @license       https://www.opensource.org/licenses/mit-license.php MIT License
+ */
+
+namespace Cake\Chronos\Test\TestCase\Date;
+
+use Cake\Chronos\ChronosDate;
+use Cake\Chronos\Test\TestCase\TestCase;
+use PHPUnit\Framework\Attributes\TestWith;
+
+class GettersTest extends TestCase
+{
+    #[TestWith([1, 1])]
+    #[TestWith([2, 1])]
+    #[TestWith([3, 1])]
+    #[TestWith([4, 1])]
+    #[TestWith([5, 1])]
+    #[TestWith([6, 1])]
+    #[TestWith([7, 2])]
+    #[TestWith([8, 2])]
+    #[TestWith([9, 2])]
+    #[TestWith([10, 2])]
+    #[TestWith([11, 2])]
+    #[TestWith([12, 2])]
+    public function testHalfOfYear(int $month, int $expectedHalfOfYear): void
+    {
+        $d = ChronosDate::create(year: 2012, month: $month, day: 1);
+        $this->assertSame($expectedHalfOfYear, $d->halfOfYear);
+    }
+}

tests/TestCase/Date/IsTest.php

@@ -17,6 +17,7 @@
 use Cake\Chronos\Chronos;
 use Cake\Chronos\ChronosDate;
 use Cake\Chronos\Test\TestCase\TestCase;
+use PHPUnit\Framework\Attributes\TestWith;
 
 class IsTest extends TestCase
 {
@@ -364,4 +365,23 @@ public function testIsWithinNext()
         $this->assertTrue((new Chronos('+1 week'))->isWithinNext('7 day'));
         $this->assertTrue((new Chronos('+1 month'))->isWithinNext('1 month'));
     }
+
+    #[TestWith([1, true, false])]
+    #[TestWith([2, true, false])]
+    #[TestWith([3, true, false])]
+    #[TestWith([4, true, false])]
+    #[TestWith([5, true, false])]
+    #[TestWith([6, true, false])]
+    #[TestWith([7, false, true])]
+    #[TestWith([8, false, true])]
+    #[TestWith([9, false, true])]
+    #[TestWith([10, false, true])]
+    #[TestWith([11, false, true])]
+    #[TestWith([12, false, true])]
+    public function testIsFirstOrSecondHalfOfYear(int $month, bool $isFirstHalfOfYear, bool $isSecondHalfOfYear): void
+    {
+        $d = Chronos::createFromDate(2023, $month, 1);
+        $this->assertSame($isFirstHalfOfYear, $d->isFirstHalfOfYear());
+        $this->assertSame($isSecondHalfOfYear, $d->isSecondHalfOfYear());
+    }
 }

tests/TestCase/DateTime/GettersTest.php

@@ -18,6 +18,7 @@
 use Cake\Chronos\Chronos;
 use Cake\Chronos\Test\TestCase\TestCase;
 use InvalidArgumentException;
+use PHPUnit\Framework\Attributes\TestWith;
 
 class GettersTest extends TestCase
 {
@@ -162,6 +163,24 @@ public function testGetQuarterFirstLast()
         $this->assertSame(4, $d->quarter);
     }
 
+    #[TestWith([1, 1])]
+    #[TestWith([2, 1])]
+    #[TestWith([3, 1])]
+    #[TestWith([4, 1])]
+    #[TestWith([5, 1])]
+    #[TestWith([6, 1])]
+    #[TestWith([7, 2])]
+    #[TestWith([8, 2])]
+    #[TestWith([9, 2])]
+    #[TestWith([10, 2])]
+    #[TestWith([11, 2])]
+    #[TestWith([12, 2])]
+    public function testHalfOfYear(int $month, int $expectedHalfOfYear): void
+    {
+        $d = Chronos::createFromDate(2012, $month, 1);
+        $this->assertSame($expectedHalfOfYear, $d->halfOfYear);
+    }
+
     public function testGetLocalTrue()
     {
         // Default timezone has been set to America/Toronto in TestCase.php

tests/TestCase/DateTime/IsTest.php

@@ -16,7 +16,9 @@
 namespace Cake\Chronos\Test\TestCase\DateTime;
 
 use Cake\Chronos\Chronos;
+use Cake\Chronos\ChronosDate;
 use Cake\Chronos\Test\TestCase\TestCase;
+use PHPUnit\Framework\Attributes\TestWith;
 
 class IsTest extends TestCase
 {
@@ -440,4 +442,23 @@ public function testIsWithinNext()
         $this->assertTrue((new Chronos('+1 second'))->isWithinNext('1 minute'));
         $this->assertTrue((new Chronos('+1 month'))->isWithinNext('1 month'));
     }
+
+    #[TestWith([1, true, false])]
+    #[TestWith([2, true, false])]
+    #[TestWith([3, true, false])]
+    #[TestWith([4, true, false])]
+    #[TestWith([5, true, false])]
+    #[TestWith([6, true, false])]
+    #[TestWith([7, false, true])]
+    #[TestWith([8, false, true])]
+    #[TestWith([9, false, true])]
+    #[TestWith([10, false, true])]
+    #[TestWith([11, false, true])]
+    #[TestWith([12, false, true])]
+    public function testIsFirstOrSecondHalfOfYear(int $month, bool $isFirstHalfOfYear, bool $isSecondHalfOfYear): void
+    {
+        $d = ChronosDate::create(2023, $month, 1);
+        $this->assertSame($isFirstHalfOfYear, $d->isFirstHalfOfYear());
+        $this->assertSame($isSecondHalfOfYear, $d->isSecondHalfOfYear());
+    }
 }

tests/TestCase/DateTime/IssetTest.php

@@ -47,6 +47,7 @@ public function testIssetReturnTrueForProperties()
             'timezoneName',
             'tz',
             'tzName',
+            'halfOfYear',
         ];
 
         foreach ($properties as $property) {