Methods return null on error

Author: phpfui

README.md

@@ -25,7 +25,7 @@ This library normalizes the [Constant Contact API](https://v3.developer.constant
 Due to a mistake in naming conventions by Constant Contact API designers, several end points are duplicated between the end point that returns all objects, and the end point that just works with one object. Normally this is dealt with by using the singular form of the noun for CRUD type operations on a single object, and the plural noun form returns a list of objects. This library follows the correct naming convention (single nouns for CRUD and plural nouns for collections) and not the Constant Contact naming convention.
 
 ## Definitions
-This Constant Contact API defines all types of objects to interact with the API. They are defined in the **PHPFUI\ConstantContact\Definition** namespace. Only valid fields are allowed to be accessed. Types are fully validated as to the best ability of PHP.  Min and max lengths are enforced for strings.
+This Constant Contact API defines all types of objects to interact with the API. They are defined in the **PHPFUI\ConstantContact\Definition** namespace. Only valid fields are allowed to be accessed. Types are fully validated as to the best ability of PHP.  Min and max lengths are enforced for strings. Invalid values will throw exceptions for type safety.
 
 ## Usage Once Authorized (see below)
 ```php
@@ -95,6 +95,11 @@ $client->refreshToken();
 ```
 The token will expire requiring your user to reauthorize your app unless you refresh the token.  You should refresh the token on a regular basis to avoid reauthorization.
 
+## Method Return Values
+The library methods will return either raw PHP arrays, objects in the **\ConstantContact\Definition** namespace, or a null value. The plain end points like get(), post(), update(), etc. return plain PHP arrays. The end points suffixed with Typed will return a fully formed object in the **\ConstantContact\Definition** namespace. Some Typed() methods will return an array of typed **\ConstantContact\Definition** objects.
+
+If a raw or typed method returns null, then an error occured and you should check $client->getStatusCode() or $client->getLastError() for more information.
+
 ## Versioning
 Since the [Constant Contact API](https://v3.developer.constantcontact.com/api_guide/index.html) is constantly being updated, this library will track all updates on a calendar based versioning schema. The major version will be the last two digits of the year the update was released. The minor version will be the month it was released. Any bug fixes will be a patch version.  So V21.8.0 would be the first August 2021 version, and V21.8.1 would be a bug fix to V21.8.  All bug fixes will be included in subsequent versions, so V21.9.0 would include all fixes from the V21.8 version. YAML changes are tracked nightly and a new version will be generated automatically. Multiple YAML changes in a month will be tracked as patch versions.
 

Tool/Generator.php

@@ -540,7 +540,7 @@ private function writeClass(string $namespacedClass, string $apiPath, array $pro
 ~description~
 	 *~docblock~
 	 */
-	public function ~method~(~parameters~) : array
+	public function ~method~(~parameters~) : ?array
 		{
 ~code~
 METHOD;
@@ -607,7 +607,7 @@ public function ~method~(~parameters~) : array
 			$summary = $this->formatDescription($specs['summary']);
 			$description = $this->formatDescription($specs['description']);
 
-			// add in ReturnSchema methods
+			// add in Typed return methods
 			foreach ($specs['responses'] ?? [] as $returnCode => $parameter)
 				{
 				$returnCode = (int)$returnCode;
@@ -623,12 +623,18 @@ public function ~method~(~parameters~) : array
 						$returnSchema = <<<SCHEMA
 
 	/**
-	 * @return array<{$schema}>
+	 * @return ?array<{$schema}>
 	 */
-	public function ~method~ReturnSchema(~parameters~) : array
+	public function ~method~Typed(~parameters~) : ?array
 		{
+		{$dollar}data = {$dollar}this->~method~(~passedParameters~);
+		if (is_null({$dollar}data))
+			{
+			return null;
+			}
+
 		{$dollar}array = [];
-		foreach ({$dollar}this->~method~(~passedParameters~) as {$dollar}object)
+		foreach ({$dollar}data as {$dollar}object)
 			{
 			{$dollar}array[] = new {$schema}({$dollar}object);
 			}
@@ -638,26 +644,16 @@ public function ~method~ReturnSchema(~parameters~) : array
 
 SCHEMA;
 						}
-//					else if ('string' === $returnType)
-//						{
-//						$returnSchema = <<<SCHEMA
-//
-//
-//	public function ~method~ReturnSchema(~parameters~) : string
-//		{
-//		return {$dollar}this->~method~(~passedParameters~);
-//		}
-//
-//SCHEMA;
-//						}
 					else
 						{
 						$returnSchema = <<<SCHEMA
 
 
-	public function ~method~ReturnSchema(~parameters~) : {$schema}
+	public function ~method~Typed(~parameters~) : ?{$schema}
 		{
-		return new {$schema}({$dollar}this->~method~(~passedParameters~));
+		{$dollar}data = {$dollar}this->~method~(~passedParameters~);
+
+		return {$dollar}data ? new {$schema}({$dollar}data) : null;
 		}
 
 SCHEMA;

src/ConstantContact/Client.php

@@ -120,7 +120,7 @@ public function addScope(string $scope) : self
 	/**
 	 * Issue a delete request.  This is not normally called directly, but by the V3 namespace classes.
 	 */
-	public function delete(string $url) : array
+	public function delete(string $url) : ?array
 		{
 		try
 			{
@@ -135,13 +135,13 @@ public function delete(string $url) : array
 			$this->statusCode = $e->getResponse()->getStatusCode();
 			}
 
-		return [];
+		return null;
 		}
 
 	/**
 	 * Issue a get request.  This is not normally called directly, but by the V3 namespace classes.
 	 */
-	public function get(string $url, array $parameters) : array
+	public function get(string $url, array $parameters) : ?array
 		{
 		try
 			{
@@ -167,7 +167,7 @@ public function get(string $url, array $parameters) : array
 			$this->statusCode = $e->getResponse()->getStatusCode();
 			}
 
-		return [];
+		return null;
 		}
 
 	/**
@@ -244,15 +244,15 @@ public function next() : array
 	/**
 	 * Issue a patch request.  This is not normally called directly, but by the V3 namespace classes.
 	 */
-	public function patch(string $url, array $parameters) : array
+	public function patch(string $url, array $parameters) : ?array
 		{
 		return $this->put($url, $parameters, 'PATCH');
 		}
 
 	/**
 	 * Issue a post request.  This is not normally called directly, but by the V3 namespace classes.
 	 */
-	public function post(string $url, array $parameters) : array
+	public function post(string $url, array $parameters) : ?array
 		{
 		try
 			{
@@ -270,13 +270,13 @@ public function post(string $url, array $parameters) : array
 			$this->statusCode = $e->getResponse()->getStatusCode();
 			}
 
-		return [];
+		return null;
 		}
 
 	/**
 	 * Issue a put request.  This is not normally called directly, but by the V3 namespace classes.
 	 */
-	public function put(string $url, array $parameters, string $method = 'PUT') : array
+	public function put(string $url, array $parameters, string $method = 'PUT') : ?array
 		{
 		try
 			{
@@ -303,7 +303,7 @@ public function put(string $url, array $parameters, string $method = 'PUT') : ar
 			$this->statusCode = $e->getResponse()->getStatusCode();
 			}
 
-		return [];
+		return null;
 		}
 
 	/**
@@ -450,7 +450,7 @@ private function getHeaders(array $additional = []) : array
 		], $additional);
 		}
 
-	private function process(\Psr\Http\Message\ResponseInterface $response) : array
+	private function process(\Psr\Http\Message\ResponseInterface $response) : ?array
 		{
 		$this->next = '';
 		$this->lastError = $response->getReasonPhrase();
@@ -470,7 +470,7 @@ private function process(\Psr\Http\Message\ResponseInterface $response) : array
 		$this->lastError = \json_last_error_msg();
 		$this->statusCode = \json_last_error();
 
-		return [];
+		return null;
 		}
 
 	private function session(string $key, ?string $value) : string

src/ConstantContact/Definition/ActivityDeleteListResponse.php

@@ -7,13 +7,13 @@
 /**
  * @property \PHPFUI\ConstantContact\UUID $activity_id Unique ID for the delete list batch job.
  * @property string $state The state of the request:
- <p><ul>
- <li>initialized - request has been received</li>
- <li>processing - request is being processed</li>
- <li>completed - job completed</li>
- <li>cancelled - request was cancelled</li>
- <li>failed - job failed to complete</li>
- <li>timed_out - the request timed out before completing"</li>
+ * <p><ul>
+ * <li>initialized - request has been received</li>
+ * <li>processing - request is being processed</li>
+ * <li>completed - job completed</li>
+ * <li>cancelled - request was cancelled</li>
+ * <li>failed - job failed to complete</li>
+ * <li>timed_out - the request timed out before completing"</li>
  * </ul> </p>
  * @property \PHPFUI\ConstantContact\DateTime $created_at Date and time that the request was received, in ISO-8601 formmat.
  * @property \PHPFUI\ConstantContact\DateTime $updated_at Date and time that the request status was updated, in ISO-8601 format.

src/ConstantContact/Definition/ActivityExportStatus.php

@@ -7,13 +7,13 @@
 /**
  * @property \PHPFUI\ConstantContact\UUID $activity_id Unique ID for the activity.
  * @property string $state <p> The state of the request: <ul>
- <li>initialized - request has been received</li>
- <li>processing - request is being processed</li>
- <li>completed - job completed</li>
- <li>cancelled - request was cancelled</li>
- <li>failed - job failed to complete</li>
- <li>timed_out - the request timed out before completing"</li>
- </ul> </p>
+ * <li>initialized - request has been received</li>
+ * <li>processing - request is being processed</li>
+ * <li>completed - job completed</li>
+ * <li>cancelled - request was cancelled</li>
+ * <li>failed - job failed to complete</li>
+ * <li>timed_out - the request timed out before completing"</li>
+ * </ul> </p>
  * @property \PHPFUI\ConstantContact\DateTime $started_at Timestamp showing when we began processing the activity request, in ISO-8601 format.
  * @property \PHPFUI\ConstantContact\DateTime $completed_at Timestamp showing when we completed processing the activity, in ISO-8601 format.
  * @property \PHPFUI\ConstantContact\DateTime $created_at Timestamp showing when we created the activity, in ISO-8601 format.

src/ConstantContact/Definition/ActivityImport.php

@@ -7,8 +7,8 @@
 /**
  * @property \PHPFUI\ConstantContact\UUID $activity_id Unique ID for the activity.
  * @property string $state The state of the request:
- <p><ul>
-  * <li>initialized - request has been received</li>
+ * <p><ul>
+ * <li>initialized - request has been received</li>
  * <li>processing - request is being processed</li>
  * <li>completed - job completed</li>
  * <li>cancelled - request was cancelled</li>

src/ConstantContact/Definition/Base.php

@@ -310,4 +310,14 @@ public function getJSON() : string
 		{
 		return \json_encode($this->getData(), JSON_PRETTY_PRINT);
 		}
+
+	/**
+	 * More descriptive alternative to getData()
+	 *
+	 * @return array representation of data
+	 */
+	public function toArray() : array
+		{
+		return $this->getData();
+		}
 	}

src/ConstantContact/Definition/EmailSendHistory.php

@@ -10,23 +10,23 @@
  * @property array $segment_ids The contact segments that Constant Contact sent the email campaign activity to as an array of <code>segment_id</code> integers.
  * @property int $count The number of contacts that Constant Contact sent this email campaign activity to. This property is specific to each send history object. When you resend an email campaign activity, Constant Contact only sends it to new contacts in the contact lists or segments you are using.
  * @property \PHPFUI\ConstantContact\DateTime $run_date The system generated date and time that Constant Contact sent the email campaign activity to contacts in ISO-8601 format.
- * @property string $send_status The send status for the email campaign activity. Valid values are: <ul> 
+ * @property string $send_status The send status for the email campaign activity. Valid values are: <ul>
  * <li><code>COMPLETED</code>: Constant Contact successfully sent the email campaign activity.</li>
  * <li><code>ERRORED</code>: Constant Contact encountered an error when sending the email campaign activity.<li> * </ul>
  * @property int $reason_code The reason why the send attempt completed or encountered an error. This method returns <code>0</code> if Constant Contact successfully sent the email campaign activity to contacts. Possible <code>reason_code</code> values are: <ul>
-   * <li>0 — Constant Contact successfully sent the email to contacts.</li>
-   * <li>1 — An error occurred when sending this email. Try scheduling it again, or contact <a href='http://support.constantcontact.com' target='_blank'>Customer Support</a>.</li>
-   * <li>2 — We were unable to send the email. Please contact our <a href='http://knowledgebase.constantcontact.com/articles/KnowledgeBase/5782-contact-an-account-review-and-deliverability-specialist' target='_blank'>Account Review Team</a> for more information.</li>
-   * <li>3 — This Constant Contact account cannot currently send emails. This can be due to billing or product expiration.</li>
-   * <li>4 — You're not able to send the email to that many contacts. Remove contacts from the contact lists you are using or select a list with fewer contacts.</li>
-   * <li>5 — The email is currently in staging. For more information, see the <a href='http://knowledgebase.constantcontact.com/articles/KnowledgeBase/7402-email-staging' target='_blank>Email Staging Knowledge Base article</a>.</li>
-   * <li>6 — Constant Contact was unable to finish sending this email to all of the contacts on your list. Please contact <a href='http://support.constantcontact.com' target='_blank'>Customer Support</a> for more information.</li>
-   * <li>7 — The email contains invalid images. This can be caused when one or more images in the email are longer available in your image library.</li>
-   * <li>8 — The email contains a link URL that exceeds 1005 characters.</li>
-   * <li>9 — Constant Contact was unable to verify your authenticated Sender address. Please contact <a href='http://support.constantcontact.com' target='_blank'>Customer Support</a> for more information.</li>
-   * <li>10 — Constant Contact was unable to verify your authenticated Sender address. Please contact <a href='http://support.constantcontact.com' target='_blank'>Customer Support</a> for more information.</li>
-   * <li>11 — This Constant Contact account cannot send survey invitations.</li>
-   * <li>12 — Constant Contact attempted to send the email, but there were no eligible contacts to send it to. This can be caused by an invalid contact list, a contact list with no contacts, or a contact list with no new contacts during a resend. This method displays <code>reason_code</code> 12 as a send attempt with a <code>send_status</code> of COMPLETED and a <code>count</code> of 0.</li> * </ul>
+ * <li>0 — Constant Contact successfully sent the email to contacts.</li>
+ * <li>1 — An error occurred when sending this email. Try scheduling it again, or contact <a href='http://support.constantcontact.com' target='_blank'>Customer Support</a>.</li>
+ * <li>2 — We were unable to send the email. Please contact our <a href='http://knowledgebase.constantcontact.com/articles/KnowledgeBase/5782-contact-an-account-review-and-deliverability-specialist' target='_blank'>Account Review Team</a> for more information.</li>
+ * <li>3 — This Constant Contact account cannot currently send emails. This can be due to billing or product expiration.</li>
+ * <li>4 — You're not able to send the email to that many contacts. Remove contacts from the contact lists you are using or select a list with fewer contacts.</li>
+ * <li>5 — The email is currently in staging. For more information, see the <a href='http://knowledgebase.constantcontact.com/articles/KnowledgeBase/7402-email-staging' target='_blank>Email Staging Knowledge Base article</a>.</li>
+ * <li>6 — Constant Contact was unable to finish sending this email to all of the contacts on your list. Please contact <a href='http://support.constantcontact.com' target='_blank'>Customer Support</a> for more information.</li>
+ * <li>7 — The email contains invalid images. This can be caused when one or more images in the email are longer available in your image library.</li>
+ * <li>8 — The email contains a link URL that exceeds 1005 characters.</li>
+ * <li>9 — Constant Contact was unable to verify your authenticated Sender address. Please contact <a href='http://support.constantcontact.com' target='_blank'>Customer Support</a> for more information.</li>
+ * <li>10 — Constant Contact was unable to verify your authenticated Sender address. Please contact <a href='http://support.constantcontact.com' target='_blank'>Customer Support</a> for more information.</li>
+ * <li>11 — This Constant Contact account cannot send survey invitations.</li>
+ * <li>12 — Constant Contact attempted to send the email, but there were no eligible contacts to send it to. This can be caused by an invalid contact list, a contact list with no contacts, or a contact list with no new contacts during a resend. This method displays <code>reason_code</code> 12 as a send attempt with a <code>send_status</code> of COMPLETED and a <code>count</code> of 0.</li> * </ul>
  */
 class EmailSendHistory extends \PHPFUI\ConstantContact\Definition\Base
 	{

src/ConstantContact/Definition/PlanInfo.php

@@ -8,9 +8,9 @@
  * @property string $plan_type Use this property to update the client account billing plan to a different billing plan. After changing the <code>plan_type</code> from <code>TRIAL</code> to any other billing plan type, you cannot change it back to <code>TRIAL</code>.
  * <ul>
  * <li><code>TRIAL</code>: A non-billable account with an expiration date that allows clients to try Constant Contact product features.</li>
-  * <li><code>GOLD</code>: A billable client account plan.</li>
-  * <li><code>SILVER</code>: A billable client account plan.</li>
-  * <li><code>BRONZE</code>: A billable client account plan.</li>
+ * <li><code>GOLD</code>: A billable client account plan.</li>
+ * <li><code>SILVER</code>: A billable client account plan.</li>
+ * <li><code>BRONZE</code>: A billable client account plan.</li>
  * </ul>
  * @property int $plan_group_id Updates an existing client account billing plan group to a new billing plan group. If you don't know the `plan_group_id` to use, contact our API support team.
  * @property int $billing_day_of_month This property is required if a client account is not set up to use single billing. You can choose to enter a specific day of the month or accept the default value, which is the day on which the <code>plan_type</code> value changes from a <code>TRIAL</code> plan to a different <code>plan_type</code>. For trial accounts, the value defaults to null. You can only change the <code>billing_day_of_month</code> when changing the <code>plan_type</code> value from <code>TRIAL</code> to a different <code>plan_type</code>, otherwise the value you enter is ignored.

src/ConstantContact/Definition/PlanTiersObject.php

@@ -7,7 +7,7 @@
 /**
  * @property string $plan_type The billing plan that is associated with a client's Constant Contact account. The billing plan determines which Constant Contact product features that the client account can access. If you are not on the latest billing plan, contact the Constant Contact Partner Team. However, older billing plans and <code>plan_type</code> enum values will continue to be supported. <ul>
  * <li><code>TRIAL</code>: Provides limited product features for a non-billed account and the account has an expiration date.</li>
- * <li><code>BRONZE</code>: Billable plan that provides basic email and marketing tools.</li>  
+ * <li><code>BRONZE</code>: Billable plan that provides basic email and marketing tools.</li>
  * <li><code>SILVER</code>: Billable plan that provides all features available in the <code>BRONZE</code> plan, and adds some additional email campaign to features, such as contact segmentation and social media ads integration.</li>
  * <li><code>GOLD</code>: Billable plan that provides all available product features.</li> * </ul>
  * @property array<\PHPFUI\ConstantContact\Definition\TierObject> $current_tiers Lists the billing plan tiers that are currently associated with a client account.