diff --git a/src/ConvertKit_API.php b/src/ConvertKit_API.php index 173a193..5b43cbe 100644 --- a/src/ConvertKit_API.php +++ b/src/ConvertKit_API.php @@ -386,31 +386,77 @@ public function get_growth_stats(\DateTime $starting = null, \DateTime $ending = } /** - * Gets all forms. + * Get forms. + * + * @param string $status Form status (active|archived|trashed|all). + * @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 1.0.0 * * @see https://developers.convertkit.com/v4.html#convertkit-api-forms * - * @return false|mixed + * @return false|array */ - public function get_forms() - { - return $this->get_resources('forms'); + public function get_forms( + string $status = 'active', + bool $include_total_count = false, + string $after_cursor = '', + string $before_cursor = '', + int $per_page = 100 + ) { + return $this->get( + endpoint: 'forms', + args: $this->build_total_count_and_pagination_params( + params: [ + 'type' => 'embed', + 'status' => $status, + ], + include_total_count: $include_total_count, + after_cursor: $after_cursor, + before_cursor: $before_cursor, + per_page: $per_page + ) + ); } /** - * Gets all landing pages. + * Get landing pages. + * + * @param string $status Form status (active|archived|trashed|all). + * @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 1.0.0 * * @see https://developers.convertkit.com/v4.html#convertkit-api-forms * - * @return false|mixed + * @return false|array */ - public function get_landing_pages() - { - return $this->get_resources('landing_pages'); + public function get_landing_pages( + string $status = 'active', + bool $include_total_count = false, + string $after_cursor = '', + string $before_cursor = '', + int $per_page = 100 + ) { + return $this->get( + endpoint: 'forms', + args: $this->build_total_count_and_pagination_params( + params: [ + 'type' => 'hosted', + 'status' => $status, + ], + include_total_count: $include_total_count, + after_cursor: $after_cursor, + before_cursor: $before_cursor, + per_page: $per_page + ) + ); } /** @@ -883,121 +929,6 @@ public function get_email_templates( ); } - /** - * Gets a resource index - * Possible resources: forms, landing_pages, subscription_forms, tags - * - * GET /{$resource}/ - * - * @param string $resource Resource type. - * - * @throws \InvalidArgumentException If the resource argument is not a supported resource type. - * - * @return array API response - */ - public function get_resources(string $resource) - { - // Assign the resource to the request variable. - $request = $resource; - - // Landing pages are included in the /forms endpoint. - if ($resource === 'landing_pages') { - $request = 'forms'; - } - - // Fetch resources. - $resources = $this->get($request); - - $this->create_log(sprintf('%s response %s', $resource, json_encode($resources))); - - // Return a blank array if no resources exist. - if (!$resources) { - $this->create_log('No resources'); - return []; - } - - // Build array of resources. - $_resource = []; - switch ($resource) { - // Forms. - case 'forms': - // Bail if no forms are set. - if (!isset($resources->forms)) { - $this->create_log('No form resources'); - return []; - } - - // Build array of forms. - foreach ($resources->forms as $form) { - // Exclude archived forms. - if (isset($form->archived) && $form->archived) { - continue; - } - - // Exclude hosted forms. - if ($form->type === 'hosted') { - continue; - } - - $_resource[] = $form; - } - break; - - // Landing Pages. - case 'landing_pages': - // Bail if no landing pages are set. - if (!isset($resources->forms)) { - $this->create_log('No landing page resources'); - return []; - } - - foreach ($resources->forms as $form) { - // Exclude archived landing pages. - if (isset($form->archived) && $form->archived) { - continue; - } - - // Exclude non-hosted (i.e. forms). - if ($form->type !== 'hosted') { - continue; - } - - $_resource[] = $form; - } - break; - - // Subscription Forms. - case 'subscription_forms': - // Exclude archived subscription forms. - foreach ($resources as $mapping) { - if (isset($mapping->archived) && $mapping->archived) { - continue; - } - - $_resource[$mapping->id] = $mapping->form_id; - } - break; - - // Tags. - case 'tags': - // Bail if no tags are set. - if (!isset($resources->tags)) { - $this->create_log('No tag resources'); - return []; - } - - foreach ($resources->tags as $tag) { - $_resource[] = $tag; - } - break; - - default: - throw new \InvalidArgumentException('An unsupported resource was specified.'); - }//end switch - - return $_resource; - } - /** * List subscribers. * diff --git a/tests/ConvertKitAPITest.php b/tests/ConvertKitAPITest.php index ea78d5a..c123fd9 100644 --- a/tests/ConvertKitAPITest.php +++ b/tests/ConvertKitAPITest.php @@ -725,18 +725,154 @@ public function testGetGrowthStatsWithEndDate() public function testGetForms() { $result = $this->api->get_forms(); - $this->assertIsArray($result); - // Convert to array to check for keys, as assertObjectHasAttribute() will be deprecated in PHPUnit 10. - $form = get_object_vars($result[0]); - $this->assertArrayHasKey('id', $form); - $this->assertArrayHasKey('name', $form); - $this->assertArrayHasKey('created_at', $form); - $this->assertArrayHasKey('type', $form); - $this->assertArrayHasKey('format', $form); - $this->assertArrayHasKey('embed_js', $form); - $this->assertArrayHasKey('embed_url', $form); - $this->assertArrayHasKey('archived', $form); + // Assert forms and pagination exist. + $this->assertDataExists($result, 'forms'); + $this->assertPaginationExists($result); + + // Iterate through each form, confirming no landing pages were included. + foreach ($result->forms as $form) { + $form = get_object_vars($form); + + // Assert shape of object is valid. + $this->assertArrayHasKey('id', $form); + $this->assertArrayHasKey('name', $form); + $this->assertArrayHasKey('created_at', $form); + $this->assertArrayHasKey('type', $form); + $this->assertArrayHasKey('format', $form); + $this->assertArrayHasKey('embed_js', $form); + $this->assertArrayHasKey('embed_url', $form); + $this->assertArrayHasKey('archived', $form); + + // Assert form is not a landing page i.e embed. + $this->assertEquals($form['type'], 'embed'); + + // Assert form is not archived. + $this->assertFalse($form['archived']); + } + } + + /** + * Test that get_forms() returns the expected data when + * the status is set to archived. + * + * @since 2.0.0 + * + * @return void + */ + public function testGetFormsWithArchivedStatus() + { + $result = $this->api->get_forms( + status: 'archived' + ); + + // Assert forms and pagination exist. + $this->assertDataExists($result, 'forms'); + $this->assertPaginationExists($result); + + // Iterate through each form, confirming no landing pages were included. + foreach ($result->forms as $form) { + $form = get_object_vars($form); + + // Assert shape of object is valid. + $this->assertArrayHasKey('id', $form); + $this->assertArrayHasKey('name', $form); + $this->assertArrayHasKey('created_at', $form); + $this->assertArrayHasKey('type', $form); + $this->assertArrayHasKey('format', $form); + $this->assertArrayHasKey('embed_js', $form); + $this->assertArrayHasKey('embed_url', $form); + $this->assertArrayHasKey('archived', $form); + + // Assert form is not a landing page i.e embed. + $this->assertEquals($form['type'], 'embed'); + + // Assert form is not archived. + $this->assertTrue($form['archived']); + } + } + + /** + * Test that get_forms() returns the expected data + * when the total count is included. + * + * @since 2.0.0 + * + * @return void + */ + public function testGetFormsWithTotalCount() + { + $result = $this->api->get_forms( + include_total_count: true + ); + + // Assert forms and pagination exist. + $this->assertDataExists($result, 'forms'); + $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_forms() returns the expected data when pagination parameters + * and per_page limits are specified. + * + * @since 2.0.0 + * + * @return void + */ + public function testGetFormsPagination() + { + $result = $this->api->get_forms( + per_page: 1 + ); + + // Assert forms and pagination exist. + $this->assertDataExists($result, 'forms'); + $this->assertPaginationExists($result); + + // Assert a single form was returned. + $this->assertCount(1, $result->forms); + + // 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_forms( + per_page: 1, + after_cursor: $result->pagination->end_cursor + ); + + // Assert forms and pagination exist. + $this->assertDataExists($result, 'forms'); + $this->assertPaginationExists($result); + + // Assert a single form was returned. + $this->assertCount(1, $result->forms); + + // 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_forms( + per_page: 1, + before_cursor: $result->pagination->start_cursor + ); + + // Assert forms and pagination exist. + $this->assertDataExists($result, 'forms'); + $this->assertPaginationExists($result); + + // Assert a single form was returned. + $this->assertCount(1, $result->forms); + + // Assert has_previous_page and has_next_page are correct. + $this->assertFalse($result->pagination->has_previous_page); + $this->assertTrue($result->pagination->has_next_page); } /** @@ -749,19 +885,136 @@ public function testGetForms() public function testGetLandingPages() { $result = $this->api->get_landing_pages(); - $this->assertIsArray($result); - // Convert to array to check for keys, as assertObjectHasAttribute() will be deprecated in PHPUnit 10. - $landingPage = get_object_vars($result[0]); - $this->assertArrayHasKey('id', $landingPage); - $this->assertArrayHasKey('name', $landingPage); - $this->assertArrayHasKey('created_at', $landingPage); - $this->assertArrayHasKey('type', $landingPage); - $this->assertEquals('hosted', $landingPage['type']); - $this->assertArrayHasKey('format', $landingPage); - $this->assertArrayHasKey('embed_js', $landingPage); - $this->assertArrayHasKey('embed_url', $landingPage); - $this->assertArrayHasKey('archived', $landingPage); + // Assert forms and pagination exist. + $this->assertDataExists($result, 'forms'); + $this->assertPaginationExists($result); + + // Iterate through each landing page, confirming no forms were included. + foreach ($result->forms as $form) { + $form = get_object_vars($form); + + // Assert shape of object is valid. + $this->assertArrayHasKey('id', $form); + $this->assertArrayHasKey('name', $form); + $this->assertArrayHasKey('created_at', $form); + $this->assertArrayHasKey('type', $form); + $this->assertArrayHasKey('format', $form); + $this->assertArrayHasKey('embed_js', $form); + $this->assertArrayHasKey('embed_url', $form); + $this->assertArrayHasKey('archived', $form); + + // Assert form is a landing page i.e. hosted. + $this->assertEquals($form['type'], 'hosted'); + + // Assert form is not archived. + $this->assertFalse($form['archived']); + } + } + + /** + * Test that get_landing_pages() returns the expected data when + * the status is set to archived. + * + * @since 2.0.0 + * + * @return void + */ + public function testGetLandingPagesWithArchivedStatus() + { + $result = $this->api->get_forms( + status: 'archived' + ); + + // Assert forms and pagination exist. + $this->assertDataExists($result, 'forms'); + $this->assertPaginationExists($result); + + // Assert no landing pages are returned, as the account doesn't have any archived landing pages. + $this->assertCount(0, $result->forms); + } + + /** + * Test that get_landing_pages() returns the expected data + * when the total count is included. + * + * @since 2.0.0 + * + * @return void + */ + public function testGetLandingPagesWithTotalCount() + { + $result = $this->api->get_landing_pages( + include_total_count: true + ); + + // Assert forms and pagination exist. + $this->assertDataExists($result, 'forms'); + $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_landing_pages() returns the expected data when pagination parameters + * and per_page limits are specified. + * + * @since 2.0.0 + * + * @return void + */ + public function testGetLandingPagesPagination() + { + $result = $this->api->get_landing_pages( + per_page: 1 + ); + + // Assert forms and pagination exist. + $this->assertDataExists($result, 'forms'); + $this->assertPaginationExists($result); + + // Assert a single form was returned. + $this->assertCount(1, $result->forms); + + // 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_landing_pages( + per_page: 1, + after_cursor: $result->pagination->end_cursor + ); + + // Assert forms and pagination exist. + $this->assertDataExists($result, 'forms'); + $this->assertPaginationExists($result); + + // Assert a single form was returned. + $this->assertCount(1, $result->forms); + + // Assert has_previous_page and has_next_page are correct. + $this->assertTrue($result->pagination->has_previous_page); + $this->assertFalse($result->pagination->has_next_page); + + // Use pagination to fetch previous page. + $result = $this->api->get_landing_pages( + per_page: 1, + before_cursor: $result->pagination->start_cursor + ); + + // Assert forms and pagination exist. + $this->assertDataExists($result, 'forms'); + $this->assertPaginationExists($result); + + // Assert a single form was returned. + $this->assertCount(1, $result->forms); + + // Assert has_previous_page and has_next_page are correct. + $this->assertFalse($result->pagination->has_previous_page); + $this->assertTrue($result->pagination->has_next_page); } /** @@ -2358,74 +2611,6 @@ public function testGetTagSubscriptionsWithInvalidTagID() $result = $this->api->get_tag_subscriptions(12345); } - /** - * Test that get_resources() for Forms returns the expected data. - * - * @since 1.0.0 - * - * @return void - */ - public function testGetResourcesForms() - { - $result = $this->api->get_resources('forms'); - $this->assertIsArray($result); - } - - /** - * Test that get_resources() for Landing Pages returns the expected data. - * - * @since 1.0.0 - * - * @return void - */ - public function testGetResourcesLandingPages() - { - $result = $this->api->get_resources('landing_pages'); - $this->assertIsArray($result); - } - - /** - * Test that get_resources() for Subscription Forms returns the expected data. - * - * @since 1.0.0 - * - * @return void - */ - public function testGetResourcesSubscriptionForms() - { - $this->markTestIncomplete(); - $result = $this->api->get_resources('subscription_forms'); - $this->assertIsArray($result); - } - - /** - * Test that get_resources() for Tags returns the expected data. - * - * @since 1.0.0 - * - * @return void - */ - public function testGetResourcesTags() - { - $result = $this->api->get_resources('tags'); - $this->assertIsArray($result); - } - - /** - * Test that get_resources() throws a ClientException when an invalid - * resource type is specified. - * - * @since 1.0.0 - * - * @return void - */ - public function testGetResourcesInvalidResourceType() - { - $this->expectException(ClientException::class); - $result = $this->api->get_resources('invalid-resource-type'); - $this->assertIsArray($result); - } - /** * Test that add_subscriber_to_form_by_email() returns the expected data. *