Broadcasts: Add Date Filtering

src/ConvertKit_API_Traits.php

@@ -1205,26 +1205,40 @@ public function get_subscriber_tags(
     /**
      * List broadcasts.
      *
-     * @param boolean $include_total_count To include the total count of records in the response, use true.
-     * @param string  $after_cursor        Return results after the given pagination cursor.
-     * @param string  $before_cursor       Return results before the given pagination cursor.
-     * @param integer $per_page            Number of results to return.
+     * @param \DateTime|null $sent_after          Get broadcasts sent after the given date.
+     * @param \DateTime|null $sent_before         Get broadcasts sent before the given date.
+     * @param boolean        $include_total_count To include the total count of records in the response, use true.
+     * @param string         $after_cursor        Return results after the given pagination cursor.
+     * @param string         $before_cursor       Return results before the given pagination cursor.
+     * @param integer        $per_page            Number of results to return.
      *
      * @see https://developers.kit.com/api-reference/broadcasts/list-broadcasts
      *
      * @return false|mixed
      */
     public function get_broadcasts(
+        \DateTime|null $sent_after = null,
+        \DateTime|null $sent_before = null,
         bool $include_total_count = false,
         string $after_cursor = '',
         string $before_cursor = '',
         int $per_page = 100
     ) {
+        // Build parameters.
+        $options = [];
+
+        if (!is_null($sent_after)) {
+            $options['sent_after'] = $sent_after->format('Y-m-d');
+        }
+        if (!is_null($sent_before)) {
+            $options['sent_before'] = $sent_before->format('Y-m-d');
+        }
+
         // Send request.
         return $this->get(
             'broadcasts',
             $this->build_total_count_and_pagination_params(
-                [],
+                $options,
                 $include_total_count,
                 $after_cursor,
                 $before_cursor,

tests/ConvertKitAPITest.php

@@ -4344,6 +4344,76 @@ public function testGetEmailTemplatesPagination()
         $this->assertTrue($result->pagination->has_next_page);
     }
 
+    /**
+     * Test that get_broadcasts() returns the expected data
+     * when a valid sent_after date is specified.
+     *
+     * @since   2.5
+     *
+     * @return void
+     */
+    public function testGetBroadcastsWithSentAfter()
+    {
+        $date = new DateTime('now');
+        $date->modify('-4 years');
+        $result = $this->api->get_broadcasts(
+            sent_after: $date,
+        );
+
+        // Assert broadcasts and pagination exist.
+        $this->assertDataExists($result, 'broadcasts');
+        $this->assertPaginationExists($result);
+
+        // Assert the expected number of broadcasts were returned.
+        $this->assertCount(8, $result->broadcasts);
+    }
+
+    /**
+     * Test that get_broadcasts() returns no broadcasts
+     * when a sent_after date is specified that is after all broadcasts.
+     *
+     * @since   2.5
+     *
+     * @return void
+     */
+    public function testGetBroadcastsWithSentAfterNow()
+    {
+        $date = new DateTime('now');
+        $date->modify('-1 day');
+        $result = $this->api->get_broadcasts(
+            sent_after: $date,
+        );
+
+        // Assert broadcasts and pagination exist.
+        $this->assertDataExists($result, 'broadcasts');
+        $this->assertPaginationExists($result);
+
+        // Assert no broadcasts were returned.
+        $this->assertCount(0, $result->broadcasts);
+    }
+
+    /**
+     * Test that get_broadcasts() returns the expected data
+     * when a valid sent_before date is specified.
+     *
+     * @since   2.5
+     *
+     * @return void
+     */
+    public function testGetBroadcastsWithSentBefore()
+    {
+        $date = new DateTime('now');
+        $result = $this->api->get_broadcasts(
+            sent_before: new DateTime('now'),
+        );
+
+        // Assert broadcasts and pagination exist.
+        $this->assertDataExists($result, 'broadcasts');
+        $this->assertPaginationExists($result);
+
+        // Assert the expected number of broadcasts were returned.
+        $this->assertCount(12, $result->broadcasts);
+    }
 
     /**
      * Test that get_broadcasts() returns the expected data