Merge pull request #85 from ConvertKit/v4-api-segments

v4 API: Segments

Author: n7studios

src/ConvertKit_API.php

@@ -1760,6 +1760,44 @@ public function create_purchase(
         return $this->post('purchases', $options);
     }
 
+    /**
+     * List segments.
+     *
+     * @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.
+     *
+     * @since 2.0.0
+     *
+     * @see https://developers.convertkit.com/v4.html#convertkit-api-segments
+     *
+     * @return false|mixed
+     */
+    public function get_segments(
+        bool $include_total_count = false,
+        string $after_cursor = '',
+        string $before_cursor = '',
+        int $per_page = 100
+    ) {
+        // Build parameters.
+        $options = ['include_total_count' => $include_total_count];
+
+        // Build pagination parameters.
+        $options = $this->build_pagination_params(
+            params: $options,
+            after_cursor: $after_cursor,
+            before_cursor: $before_cursor,
+            per_page: $per_page
+        );
+
+        // Send request.
+        return $this->get(
+            endpoint: 'segments',
+            args: $options
+        );
+    }
+
     /**
      * Get markup from ConvertKit for the provided $url.
      *

tests/ConvertKitAPITest.php

@@ -4012,6 +4012,105 @@ public function testCreatePurchaseWithInvalidData()
         );
     }
 
+    /**
+     * Test that get_segments() returns the expected data.
+     *
+     * @since   2.0.0
+     *
+     * @return void
+     */
+    public function testGetSegments()
+    {
+        $result = $this->api->get_segments();
+
+        // Assert segments and pagination exist.
+        $this->assertDataExists($result, 'segments');
+        $this->assertPaginationExists($result);
+    }
+
+    /**
+     * Test that get_segments() returns the expected data
+     * when the total count is included.
+     *
+     * @since   1.0.0
+     *
+     * @return void
+     */
+    public function testGetSegmentsWithTotalCount()
+    {
+        $result = $this->api->get_segments(
+            include_total_count: true
+        );
+
+        // Assert segments and pagination exist.
+        $this->assertDataExists($result, 'segments');
+        $this->assertPaginationExists($result);
+
+        // Assert total count is included.
+        $this->assertArrayHasKey('total_count', get_object_vars($result->pagination));
+        $this->assertGreaterThan(0, $result->pagination->total_count);
+    }
+
+    /**
+     * Test that get_segments() returns the expected data
+     * when pagination parameters and per_page limits are specified.
+     *
+     * @since   2.0.0
+     *
+     * @return void
+     */
+    public function testGetSegmentsPagination()
+    {
+        $result = $this->api->get_segments(
+            per_page: 1
+        );
+
+        // Assert segments and pagination exist.
+        $this->assertDataExists($result, 'segments');
+        $this->assertPaginationExists($result);
+
+        // Assert a single segment was returned.
+        $this->assertCount(1, $result->segments);
+
+        // Assert has_previous_page and has_next_page are correct.
+        $this->assertFalse($result->pagination->has_previous_page);
+        $this->assertTrue($result->pagination->has_next_page);
+
+        // Use pagination to fetch next page.
+        $result = $this->api->get_segments(
+            per_page: 1,
+            after_cursor: $result->pagination->end_cursor
+        );
+
+        // Assert segments and pagination exist.
+        $this->assertDataExists($result, 'segments');
+        $this->assertPaginationExists($result);
+
+        // Assert a single segment was returned.
+        $this->assertCount(1, $result->segments);
+
+        // Assert has_previous_page and has_next_page are correct.
+        $this->assertTrue($result->pagination->has_previous_page);
+        $this->assertTrue($result->pagination->has_next_page);
+
+        // Use pagination to fetch previous page.
+        $result = $this->api->get_segments(
+            per_page: 1,
+            before_cursor: $result->pagination->start_cursor
+        );
+
+        // Assert segments and pagination exist.
+        $this->assertDataExists($result, 'segments');
+        $this->assertPaginationExists($result);
+
+        // Assert a single segment was returned.
+        $this->assertCount(1, $result->segments);
+
+        // Assert has_previous_page and has_next_page are correct.
+        $this->assertFalse($result->pagination->has_previous_page);
+        $this->assertTrue($result->pagination->has_next_page);
+    }
+
     /**
      * Test that fetching a legacy form's markup works.
      *