Merge branch 'release/1.8.0'

* release/1.8.0:
  Updated README and CHANGELOG for the 1.8.0 release
  Fix issue where a null response body in `checkStatus` would trigger a type violation on `getErrorMessage`
  Fix syntax issues for PHP 5.3 and 5.4
  Add validation for custom field responses
  Add support for custom fields returned via a mailbox or conversation

CHANGELOG.md

@@ -1,3 +1,7 @@
+#### 1.8.0 (February 19, 2016)
+* Added support for Custom Fields returned within a Mailbox details
+* Added support for Custom Field Responses returned with a Conversation
+
 #### 1.7.0 (February 2, 2016)
 * Deprecated "Team" reports. With the arrival of "Teams" with the new Plus Plan, the previous "Team" report has been renamed "Company" report
 * Added new reports methods: `getCompanyReport`, `getCustomersHelpedCompanyReport`, `getCompanyDrillDownReport`

README.md

@@ -2,7 +2,7 @@ Help Scout PHP Wrapper [![Build Status](https://travis-ci.org/helpscout/helpscou
 ================================================================================
 > PHP Wrapper for the Help Scout API and Webhooks implementation. More information on our [developer site](http://developer.helpscout.net).
 
-Version 1.7.0 Released
+Version 1.8.0 Released
 ---------------------
 Please see the [Changelog](https://github.com/helpscout/helpscout-api-php/blob/master/CHANGELOG.md) for details.
 
@@ -244,6 +244,91 @@ if ($webhook->isValid()) {
 }
 ```
 
+Example Usage: Custom Fields
+------------------------
+
+### Retrieving custom fields for a mailbox
+
+```php
+include 'HelpScout/ApiClient.php';
+
+use HelpScout\ApiClient;
+
+$scout = ApiClient::getInstance();
+$scout->setKey('your-api-key-here');
+
+$mailbox = $scout->getMailbox(1234);
+$customFields = $mailbox->getCustomFields();
+```
+
+### Retrieving custom fields with responses for a conversation
+
+```php
+$conversation = $scout->getConversation(1234);
+$customFields = $conversation->getCustomFields();
+
+```
+
+### Filling in a value for a field on a conversation that hasn't been filled out yet
+
+This is if the conversation hasn't had **any** fields filled out yet
+
+```php
+$conversation = $scout->getConversation(1234);
+$mailbox = $scout->getMailbox($conversation->getMailbox()->getId());
+
+$conversationFields = [];
+
+foreach ($mailbox->getCustomFields() as $customField) {
+    if ($customField->getId() == 88) {
+        $field = clone $customField;
+        $field->setValue('Foo');
+        $conversationFields[] = $field;
+    }
+}
+
+$conversation->setCustomFields($conversationFields);
+
+$scout->updateConversation($conversation);
+```
+
+### Updating a value for a field on a conversation
+
+```php
+$conversation = $scout->getConversation(1234);
+
+foreach ($conversation->getCustomFields() as $customField) {
+    if ($customField->getId() == 88) {
+        $field->setValue('Bar');
+    }
+}
+
+$scout->updateConversation($conversation);
+```
+
+### Custom Field Validation
+
+#### Date Fields (`DateFieldRef`)
+
+Must be a valid date in the format of YYYY-MM-DD (year-month-day).
+
+#### Dropdown Fields (`DropdownFieldRef`)
+
+The value must be the ID of one of the available dropdown options.
+
+#### Multi Line Fields (`MultiLineFieldRef`)
+
+The maximum string length for a multi line value is 15000 characters.
+
+#### Number Fields (`NumberFieldRef`)
+
+Number values must be numeric. Integers and Decimals (floats) are allowed (ex: 100 or 12.34).
+
+#### Single Line Fields (`SingleLineFieldRef`)
+
+The maximum string length for a single line value is 255 characters.
+
+
 Debugging
 ------------------------
 
@@ -285,7 +370,6 @@ try {
 That outputs 
 
 ```php
-Input could not be validated
 Array
 (
     [0] => Array

src/HelpScout/ApiClient.php

@@ -718,6 +718,7 @@ private function getItem($url, $params, $method, $model) {
 	 */
 	private function checkStatus($statusCode, $type, $expected = 200, $responseBody = array()) {
 		$expected = (array) $expected;
+		$responseBody = $responseBody ?: array();
 
 		if (!in_array($statusCode, $expected)) {
 			$exception = new ApiException(

src/HelpScout/CustomFieldFactory.php

@@ -0,0 +1,74 @@
+<?php
+namespace HelpScout;
+
+use HelpScout\model\ref\customfields\DateFieldRef;
+use HelpScout\model\ref\customfields\DropdownFieldRef;
+use HelpScout\model\ref\customfields\MultiLineFieldRef;
+use HelpScout\model\ref\customfields\NumberFieldRef;
+use HelpScout\model\ref\customfields\SingleLineFieldRef;
+
+class CustomFieldFactory
+{
+    public static function fromMailbox(array $attributes)
+    {
+        $map = array(
+            'fieldName' => 'name'
+        );
+
+        return static::createField(
+            $attributes['fieldType'],
+            static::mapAttributes($attributes, $map)
+        );
+    }
+
+    public static function fromConversation(array $attributes)
+    {
+        $map = array(
+            'fieldId' => 'id'
+        );
+
+        return static::createField(
+            $attributes['type'],
+            static::mapAttributes($attributes, $map)
+        );
+    }
+
+    public static function createField($type, array $attributes)
+    {
+        $attributes = (object) $attributes;
+        switch ($type) {
+            case 'SINGLE_LINE' :
+                return new SingleLineFieldRef($attributes);
+                break;
+            case 'MULTI_LINE' :
+                return new MultiLineFieldRef($attributes);
+                break;
+            case 'DROPDOWN' :
+                return new DropdownFieldRef($attributes);
+                break;
+            case 'DATE' :
+                return new DateFieldRef($attributes);
+                break;
+            case 'NUMBER' :
+                return new NumberFieldRef($attributes);
+                break;
+        }
+
+        throw new \InvalidArgumentException($type . ' is not a supported Custom Field type.');
+    }
+
+    protected static function mapAttributes(array $attributes, array $map)
+    {
+        $temp = array();
+
+        foreach ($attributes as $key => $value) {
+            if (array_key_exists($key, $map)) {
+                $temp[$map[$key]] = $value;
+            } else {
+                $temp[$key] = $value;
+            }
+        }
+
+        return $temp;
+    }
+}

src/HelpScout/ValidationException.php

@@ -0,0 +1,7 @@
+<?php
+namespace HelpScout;
+
+class ValidationException extends \Exception
+{
+
+}

src/HelpScout/descriptions/reports/conversations.php

@@ -133,7 +133,7 @@
 
     'getConversationsDrillDownByFieldReport' => array(
         'httpMethod' => 'GET',
-        'uri' => 'reports/conversations/fields-drilldown.json',
+        'uri' => 'reports/conversations/customfields-drilldown.json',
         'parameters' => array(
             'start' => array(
                 'location' => 'query',

src/HelpScout/model/Conversation.php

@@ -1,6 +1,8 @@
 <?php
 namespace HelpScout\model;
 
+use HelpScout\CustomFieldFactory;
+
 class Conversation {
 	const STATUS_ACTIVE  = 'active';
 	const STATUS_PENDING = 'pending';
@@ -33,6 +35,7 @@ class Conversation {
 	private $bccList        = null;
 	private $tags           = null;
 	private $threads        = null;
+	private $customFields   = null;
 
 	private $unassigned     = false;
 
@@ -99,6 +102,14 @@ public function __construct($data = null) {
 					}
 				}
 			}
+
+			if (isset($data->customFields)) {
+				$this->customFields = array();
+
+				foreach ($data->customFields as $field) {
+					$this->customFields[] = CustomFieldFactory::fromConversation((array) $field);
+				}
+			}
 		}
 	}
 
@@ -154,6 +165,8 @@ public function getObjectVars() {
 		}
 		$this->addThreadsToVars($vars);
 
+		$this->addCustomFieldsToVars($vars);
+
 		return $vars;
 	}
 
@@ -170,6 +183,22 @@ private function addThreadsToVars(array &$vars) {
 		$vars['threads'] = $threads;
 	}
 
+	private function addCustomFieldsToVars(array &$vars) {
+		/* @var $field \HelpScout\model\ref\customfields\AbstractCustomFieldRef */
+		$fields = array();
+
+		if ($list = $this->getCustomFields()) {
+			foreach ($list as $field) {
+				$fields[] = array(
+					'fieldId' => $field->getId(),
+					'name' => $field->getName(),
+					'value' => $field->getValue()
+				);
+			}
+		}
+		$vars['customFields'] = $fields;
+	}
+
 	public function toJSON() {
 		$vars = $this->getObjectVars();
 		return json_encode($vars);
@@ -570,4 +599,20 @@ public function getThreads($cache = true, $apiCall = true) {
 		}
 		return $this->threads;
 	}
+
+	/**
+	 * @return array|null
+	 */
+	public function getCustomFields()
+	{
+		return $this->customFields;
+	}
+
+	/**
+	 * @param array|null $customFields
+	 */
+	public function setCustomFields(array $customFields)
+	{
+		$this->customFields = $customFields;
+	}
 }

src/HelpScout/model/Mailbox.php

@@ -1,6 +1,8 @@
 <?php
 namespace HelpScout\model;
 
+use HelpScout\CustomFieldFactory;
+
 class Mailbox {
 	private $id = false;
 	private $name;
@@ -11,6 +13,8 @@ class Mailbox {
 
 	private $folders = false;
 
+	private $customFields = array();
+
 	public function __construct($data=null) {
 		if ($data) {
 			$this->id         = isset($data->id)         ? $data->id         : null;
@@ -19,6 +23,13 @@ public function __construct($data=null) {
 			$this->email      = isset($data->email)      ? $data->email      : null;
 			$this->createdAt  = isset($data->createdAt)  ? $data->createdAt  : null;
 			$this->modifiedAt = isset($data->modifiedAt) ? $data->modifiedAt : null;
+
+			if (isset($data->customFields)) {
+
+				foreach ($data->customFields as $field) {
+					$this->customFields[] = CustomFieldFactory::fromMailbox((array) $field);
+				}
+			}
 		}
 	}
 
@@ -193,4 +204,12 @@ public function toRef() {
 
 		return $ref;
 	}
+
+	/**
+	 * @return array
+	 */
+	public function getCustomFields()
+	{
+		return $this->customFields;
+	}
 }