Add Broadcast->isOnAir and Service->isActive

Add clarifying comments on if start/end times for services and
broadcasts are inclusive or exclusive (starts are inclusive,
ends are exclusive)

src/Domain/Entity/Broadcast.php

@@ -101,11 +101,23 @@ public function getService(): Service
         return $this->service;
     }
 
+    /**
+     * When the broadcast started. This is inclusive, this is the very first
+     * moment of the broadcast.
+     * Given two broadcasts, the first will end at at 06:30:00 and the second
+     * will start at 06:30:00.
+     */
     public function getStartAt(): DateTimeImmutable
     {
         return $this->startAt;
     }
 
+    /**
+     * When the broadcast ended. This is exclusive, this is the very first
+     * moment that the broadcast is no longer on.
+     * Given two broadcasts, the first will end at at 06:30:00 and the second
+     * will start at 06:30:00.
+     */
     public function getEndAt(): DateTimeImmutable
     {
         return $this->endAt;
@@ -125,4 +137,15 @@ public function isRepeat(): bool
     {
         return $this->isRepeat;
     }
+
+    /**
+     * Returns true if the broadcast is on air at a given date.
+     * Broadcast starts are inclusive and ends are exclusive.
+     * Given two broadcasts, the first will end at at 06:30:00 and the second
+     * will start at 06:30:00.
+     */
+    public function isOnAirAt(DateTimeImmutable $dateTime): bool
+    {
+        return $this->startAt <= $dateTime && $dateTime < $this->endAt;
+    }
 }

src/Domain/Entity/Service.php

@@ -111,11 +111,26 @@ public function getNetwork(): ?Network
         return $this->network;
     }
 
+    /**
+     * When the service started. This is inclusive, this is the very first
+     * moment of the service.
+     * Non-broadcast services do not have a start date.
+     */
     public function getStartDate(): ?DateTimeImmutable
     {
         return $this->startDate;
     }
 
+    /**
+     * When the service ended. This is exclusive, this is the very first
+     * moment that the service is no longer active.
+     * On-air but not yet stopped services do not have an end date.
+     *
+     * Honestly PIPS is not clear on if this should be exclusive or
+     * inclusive - It is pretty much a 50/50 split on services stopping at
+     * :59 or :00 seconds. We go with exclusive to keep consistency with
+     * Broadcast start and end times.
+     */
     public function getEndDate(): ?DateTimeImmutable
     {
         return $this->endDate;
@@ -125,4 +140,17 @@ public function getLiveStreamUrl(): ?string
     {
         return $this->liveStreamUrl;
     }
+
+    /**
+     * Returns true if the service is active on a given date.
+     * If a service has no start date then we assume it was active since the
+     * dawn of time.
+     * If a service has no end date then we assume it will be active until the
+     * end of time.
+     * Service starts are inclusive and ends are exclusive.
+     */
+    public function isActiveAt(DateTimeImmutable $dateTime): bool
+    {
+        return (!$this->startDate || $this->startDate <= $dateTime) && (!$this->endDate || $dateTime < $this->endDate);
+    }
 }

tests/Domain/Entity/BroadcastTest.php

@@ -15,8 +15,8 @@ public function testConstructorRequiredArgs()
         $version = $this->createMock('BBC\ProgrammesPagesService\Domain\Entity\Version');
         $programmeItem = $this->createMock('BBC\ProgrammesPagesService\Domain\Entity\ProgrammeItem');
         $service = $this->createMock('BBC\ProgrammesPagesService\Domain\Entity\Service');
-        $startAt = new DateTimeImmutable();
-        $endAt = new DateTimeImmutable();
+        $startAt = new DateTimeImmutable('2015-01-01 06:00:00');
+        $endAt = new DateTimeImmutable('2015-01-01 07:00:00');
 
         $broadcast = new Broadcast(
             $pid,
@@ -37,6 +37,14 @@ public function testConstructorRequiredArgs()
         $this->assertSame(1, $broadcast->getDuration());
         $this->assertSame(false, $broadcast->isBlanked());
         $this->assertSame(false, $broadcast->isRepeat());
+
+        // Exactly at the start and a moment before - starts are inclusive
+        $this->assertTrue($broadcast->isOnAirAt(new DateTimeImmutable('2015-01-01 06:00:00')));
+        $this->assertFalse($broadcast->isOnAirAt(new DateTimeImmutable('2015-01-01 05:59:59')));
+
+        // Exactly at the end and a moment after - ends are exclusive
+        $this->assertTrue($broadcast->isOnAirAt(new DateTimeImmutable('2015-01-01 06:59:59')));
+        $this->assertFalse($broadcast->isOnAirAt(new DateTimeImmutable('2015-01-01 07:00:00')));
     }
 
     public function testConstructorOptionalArgs()

tests/Domain/Entity/ServiceTest.php

@@ -36,8 +36,8 @@ public function testConstructorOptionalArgs()
         $sid = new Sid('bbc_1xtra');
         $pid = new Pid('b0000001');
         $network = $this->createMock('BBC\ProgrammesPagesService\Domain\Entity\Network');
-        $startDate = new DateTimeImmutable('2015-01-01');
-        $endDate = new DateTimeImmutable('2016-01-01');
+        $startDate = new DateTimeImmutable('2015-01-01 06:00:00');
+        $endDate = new DateTimeImmutable('2016-01-01 06:00:00');
 
         $service = new Service(
             0,
@@ -58,6 +58,32 @@ public function testConstructorOptionalArgs()
         $this->assertEquals($startDate, $service->getStartDate());
         $this->assertEquals($endDate, $service->getEndDate());
         $this->assertEquals('liveStreamUrl', $service->getLiveStreamUrl());
+
+        // Exactly at the start and a moment before - starts are inclusive
+        $this->assertTrue($service->isActiveAt(new DateTimeImmutable('2015-01-01 06:00:00')));
+        $this->assertFalse($service->isActiveAt(new DateTimeImmutable('2015-01-01 05:59:59')));
+
+        // Exactly at the end and a moment after - ends are exclusive
+        $this->assertTrue($service->isActiveAt(new DateTimeImmutable('2016-01-01 05:59:00')));
+        $this->assertFalse($service->isActiveAt(new DateTimeImmutable('2016-01-01 06:00:00')));
+    }
+
+    public function testIsActiveAtWithIndefiniteEnd()
+    {
+        $service = $this->serviceWithDates(new DateTimeImmutable('2015-01-01 06:00:00'), null);
+
+        // Exactly at the start and a moment before - starts are inclusive
+        $this->assertTrue($service->isActiveAt(new DateTimeImmutable('2015-01-01 06:00:00')));
+        $this->assertFalse($service->isActiveAt(new DateTimeImmutable('2015-01-01 05:59:59')));
+    }
+
+    public function testIsActiveAtWithIndefiniteStart()
+    {
+        $service = $this->serviceWithDates(null, new DateTimeImmutable('2016-01-01 06:00:00'));
+
+        // Exactly at the end and a moment after - ends are exclusive
+        $this->assertTrue($service->isActiveAt(new DateTimeImmutable('2016-01-01 05:59:00')));
+        $this->assertFalse($service->isActiveAt(new DateTimeImmutable('2016-01-01 06:00:00')));
     }
 
     /**
@@ -78,4 +104,19 @@ public function testRequestingUnfetchedNetworkThrowsException()
 
         $service->getNetwork();
     }
+
+    private function serviceWithDates(?DateTimeImmutable $start, ?DateTimeImmutable $end): Service
+    {
+        return new Service(
+            0,
+            new Sid('bbc_1xtra'),
+            new Pid('b0000001'),
+            'Name',
+            'shortName',
+            'urlKey',
+            $this->createMock('BBC\ProgrammesPagesService\Domain\Entity\Network'),
+            $start,
+            $end
+        );
+    }
 }