kyObjectBase.php

<?php
/**
 * Base class for getting, creating, updating and deleting Kayako objects.
 *
 * All objects interacting with Kayako REST API should extend this class and
 * define:
 * * Kayako controller
 * * XML element name holding object's data in REST response
 * @see kyObjectBase::$controller
 * @see kyObjectBase::$object_xml_name
 *
 * @author Tomasz Sawicki (https://github.com/Furgas)
 * @link http://wiki.kayako.com/display/DEV/REST+API
 * @package Object\Base
 */
abstract class kyObjectBase {

	/**
	 * Data key for storing files to send as multipart/form-data.
	 * @var string
	 */
	const FILES_DATA_NAME = '_files';

	/**
	 * Default Kayako controller used to operate on this objects. Override in descending classes.
	 * @var string
	 */
	static protected $controller = null;

	/**
	 * Indicates the name of object element in XML response. Override in descending classes.
	 * @var string
	 */
	static protected $object_xml_name = null;

	/**
	 * Controls if the object can be created/updated/deleted. Override in descending classes.
	 * @var bool
	 */
	protected $read_only = false;

	/**
	 * Cache for available filter methods.
	 * Format:
	 * array(
	 *  '<class name>' => array(
	 * 		'<filter method name>' => '<get method name>',
	 * 		...repeat for every filtering enabled method...
	 * 	),
	 * 	...repeat for every object class...
	 * )
	 * @var string[]
	 */
	static protected $_filter_methods = array();

	/**
	 * Cache for available order methods.
	 * Format:
	 * array(
	 *  '<class name>' => array(
	 * 		'<order method name>' => '<get method name>',
	 * 		...repeat for every ordering enabled method...
	 * 	),
	 * 	...repeat for every object class...
	 * )
	 * @var string[]
	 */
	static protected $_order_methods = array();

	/**
	 * Cache for API fields.
	 * Format:
	 * array(
	 * 	'<class name>' => array(
	 * 		'<api field name>' => array(
	 * 			'property' => '<class property holding field value>',
	 * 			'description' => '<description of the field>',
	 * 			'getter' => '<value getter method or null if write-only>',
	 * 			'setter' => '<value setter method or null if read-only>',
	 * 			'required_create' => <present and true if this field is required for creating the object>,
	 * 			'required_update' => <present and true if this field is required for updating the object>
	 * 		),
	 * 		...repeat for every class api field...
	 * 	),
	 * 	...repeat for every object class...
	 * )
	 * @var array
	 */
	static private $_api_fields = null;

	/**
	 * Default constructor.
	 *
	 * @param array $data Object data from XML response converted into array.
	 */
	function __construct($data = null) {
		if ($data !== null)
			$this->parseData($data);
	}

	/**
	 * Creates new object. Compatible with method chaining.
	 */
	static public function createNew() {
		return new static();
	}

	/**
	 * Returns object controller.
	 *
	 * @return string
	 */
	static public function getController() {
		return static::$controller;
	}

	/**
	 * Should use passed data to fill object properties.
	 *
	 * @param array $data Object data from XML response.
	 */
	abstract protected function parseData($data);

	/**
	 * Should build the array of object data for creating or updating the object.
	 * Values must be set in format accepted by REST API.
	 *
	 * @param bool $create Indicates if the result will be used to create (true) or update (false) an object.
	 * @return array
	 */
	public function buildData($create) {
		$this->checkRequiredAPIFields($create);
		return array();
	}

	/**
	 * Adds numeric field to object data array only if its value is proper number.
	 *
	 * @param array $data Data used to create or update the object.
	 * @param string $field_name Field name.
	 * @param mixed $field_value Field value.
	 */
	protected function buildDataNumeric(&$data, $field_name, $field_value) {
		if (is_numeric($field_value))
			$data[$field_name] = $field_value;
	}

	/**
	 * Adds string field to object data array only if its value is non-empty.
	 *
	 * @param array $data Data used to create or update the object.
	 * @param string $field_name Field name.
	 * @param mixed $field_value Field value.
	 */
	protected function buildDataString(&$data, $field_name, $field_value) {
		if (strlen($field_value) > 0)
			$data[$field_name] = $field_value;
	}

	/**
	 * Adds boolean field to object data array only if its value is non-empty.
	 *
	 * @param array $data Data used to create or update the object.
	 * @param string $field_name Field name.
	 * @param mixed $field_value Field value.
	 */
	protected function buildDataBool(&$data, $field_name, $field_value) {
		if ($field_value !== null)
			$data[$field_name] = $field_value ? 1 : 0;
	}

	/**
	 * Adds array field to object data array only if its value is proper array and is non-empty.
	 *
	 * @param array $data Data used to create or update the object.
	 * @param string $field_name Field name.
	 * @param mixed $field_value Field value.
	 */
	protected function buildDataList(&$data, $field_name, $field_value) {
		if (is_array($field_value) && count($field_value) > 0)
			$data[$field_name] = implode(',', $field_value);
	}

	/**
	 * Returns whether the object is new and not yet saved on the server.
	 *
	 * @return bool
	 */
	public function isNew() {
		return $this->getId() === null;
	}

	/**
	 * Returns whether this object is read only.
	 *
	 * @return bool
	 */
	public function isReadOnly() {
		return $this->read_only;
	}

	/**
	 * Sets whether this object is read only.
	 *
	 * @param bool $read_only Read only flag.
	 * @return bool
	 */
	public function setReadOnly($read_only) {
		$this->read_only = $read_only;
	}

	/**
	 * Should return object identifier or complete list of identifiers as needed by API to identify the object (ex. ticket identifier and ticket post identifier in case of TicketPost).
	 *
	 * @param bool $complete True to return complete list of identifiers as needed by API to identify the object.
	 * @return int|array
	 */
	abstract public function getId($complete = false);

	/**
	 * Should return short (one line) description of the object (it's title, name, etc.).
	 *
	 * @return string
	 */
	abstract public function toString();

	/**
	 * Returns REST client.
	 *
	 * @return kyRESTClientInterface
	 */
	static protected function getRESTClient() {
		return kyConfig::get()->getRESTClient();
	}

	/**
	 * Fetches objects from server.
	 *
	 * @param array $search_parameters Optional. Additional search parameters.
	 * @return kyResultSet
	 */
	static public function getAll($search_parameters = array()) {
		$result = self::getRESTClient()->get(static::$controller, $search_parameters);
		$objects = array();
		if (array_key_exists(static::$object_xml_name, $result)) {
			foreach ($result[static::$object_xml_name] as $object_data) {
				$objects[] = new static($object_data);
			}
		}
		return new kyResultSet($objects);
	}

	/**
	 * Fetches the object from server.
	 *
	 * @param int|array $id Object identifier or list of identifiers (ex. ticket identifier and ticket post identifier when fetching TicketPost).
	 * @return kyObjectBase
	 */
	static public function get($id) {
		if (!is_array($id))
			$id = array($id);
		$result = self::getRESTClient()->get(static::$controller, $id);
		if (count($result) === 0)
			return null;
		return new static($result[static::$object_xml_name][0]);
	}

	/**
	 * Refreshes the object data from server.
	 *
	 * @throws BadMethodCallException
	 * @return kyObjectBase
	 */
	public function refresh() {
		if ($this->isNew())
			throw new BadMethodCallException("Object is not yet saved on server. Save it before refreshing.");

		$result = self::getRESTClient()->get(static::$controller, $this->getId(true));

		/**
		 * Clear all object properties.
		 */
   		foreach ($this as $key => $value) {
		   	$this->$key = null;
	   	}

		$this->parseData($result[static::$object_xml_name][0]);
		return $this;
	}

	/**
	 * Creates an object on the server and refreshes its local data.
	 *
	 * @throws BadMethodCallException
	 * @throws kyException
	 * @return kyObjectBase
	 */
	public function create() {
		if ($this->read_only)
			throw new BadMethodCallException(sprintf("You can't create new objects of type %s.", get_called_class()));

		$result = self::getRESTClient()->post(static::$controller, array(), $this->buildData(true));

		if (count($result) === 0)
			throw new kyException("No data returned by the server after creating the object.");

		$this->parseData($result[static::$object_xml_name][0]);
		return $this;
	}

	/**
	 * Updates the object on the server and refreshes its local data.
	 *
	 * @throws BadMethodCallException
	 * @throws kyException
	 * @return kyObjectBase
	 */
	public function update() {
		if ($this->read_only)
			throw new BadMethodCallException(sprintf("You can't update objects of type %s.", get_called_class()));

		if ($this->isNew())
			throw new BadMethodCallException(sprintf("You can't update object before it was created. Create it first.", get_called_class()));

		$result = self::getRESTClient()->put(static::$controller, $this->getId(true), $this->buildData(false));

		if (count($result) === 0)
			throw new kyException("No data returned by the server after updating the object.");

		$this->parseData($result[static::$object_xml_name][0]);
		return $this;
	}

	/**
	 * Saves (creates or updates) the object to the server.
	 *
	 * @return kyObjectBase
	 */
	public function save() {
		if ($this->isNew()) {
			return $this->create();
		} else {
			return $this->update();
		}
	}

	/**
	 * Deletes the object on the server.
	 */
	public function delete() {
		if ($this->read_only)
			throw new BadMethodCallException(sprintf("You can't delete object of type %s.", get_called_class()));

		self::getRESTClient()->delete(static::$controller, $this->getId(true));
	}

	/**
	 * Builds API fields list.
	 *
	 * Scans protected and private properties of called class, searches for
	 * @apiField [name=field name]{0,1} [alias=field name alias]* [accessor=setter/getter name]{0,1} [getter=getter name]{0,1} [setter=setter name]{0,1} [required_create=true if field if required when creating object]{0,1} [required_update=true if field if required when udpating object]{0,1} [required=true if field if required when creating or updating object]{0,1}
	 * and builds API field list with property name, description, setter and getter method names, and required flags.
	 * @see kyObjectBase::$_api_fields
	 */
	static private function initAPIFieldsAccessors() {
		$classname = get_called_class();

		if (self::$_api_fields === null || !array_key_exists($classname, self::$_api_fields)) {
			self::$_api_fields[$classname] = array();
			$class = new ReflectionClass($classname);
			foreach ($class->getProperties(ReflectionProperty::IS_PROTECTED|ReflectionProperty::IS_PUBLIC) as $property) {
				/* @var $property ReflectionProperty */
				$comment = $property->getDocComment();
				$comment_lines = explode("\n", $comment);
				$short_description = trim(next($comment_lines), " *\t\n\r");

				$parameters = ky_get_tag_parameters($comment, 'apiField');
				if ($parameters === false)
					continue;

				$api_field = null;
				$accessor = null;
				$setter = null;
				$getter = null;
				if (array_key_exists('name', $parameters)) {
					$api_field = $parameters['name'];
				}

				if (strlen($api_field) === 0) {
					$api_field = str_replace('_', '', $property->getName());
				}

				if (array_key_exists($api_field, self::$_api_fields[$classname]))
					continue;

				if (array_key_exists('accessor', $parameters)) {
					$accessor = $parameters['accessor'];
					$getter = sprintf('get%s', $accessor);
					$setter = sprintf('set%s', $accessor);
				}

				if (array_key_exists('getter', $parameters)) {
					$getter = $parameters['getter'];
				}

				if (array_key_exists('setter', $parameters)) {
					$setter = $parameters['setter'];
				}

				if (strlen($getter) === 0 && strlen($setter) === 0 ) {
					$name_parts = explode('_', $property->getName());
					foreach ($name_parts as $name_part) {
						$accessor .= ucfirst($name_part);
					}
					$getter = sprintf('get%s', $accessor);
					$setter = sprintf('set%s', $accessor);
				}

				if (!method_exists($classname, $setter)) {
					$setter = null;
				}

				if (!method_exists($classname, $getter)) {
					$getter = null;
				}

				if (strlen($getter) === 0 && strlen($setter) === 0)
					continue;

				$required_create = (array_key_exists('required', $parameters) && $parameters['required'] === 'true') || (array_key_exists('required_create', $parameters) && $parameters['required_create'] === 'true');
				$required_update = (array_key_exists('required', $parameters) && $parameters['required'] === 'true') || (array_key_exists('required_update', $parameters) && $parameters['required_update'] === 'true');

				$aliases = array();
				if (array_key_exists('alias', $parameters)) {
					if (!is_array($parameters['alias'])) {
						$aliases = array($parameters['alias']);
					} else {
						$aliases = $parameters['alias'];
					}
				}

				self::$_api_fields[$classname][$api_field] = array(
						'property' => $property->getName(),
						'description' => $short_description,
						'setter' => $setter,
						'getter' => $getter,
						'required_create' => $required_create,
						'required_update' => $required_update,
						'aliases' => $aliases
					);
			}
		}
	}

	/**
	 * Returns array of API fields.
	 *
	 * Format of returned array:
	 * <pre>
	 * array(
	 * 	'<api field name>' => Field description. (getter: <getter name>, setter: <setter name>),
	 * 	...repeat...
	 * )
	 * </pre>
	 *
	 * @return string[]
	 */
	static public function getAPIFields() {
		static::initAPIFieldsAccessors();
		$classname = get_called_class();

		$api_fields = array();
		foreach (self::$_api_fields[$classname] as $api_field => $api_field_parameters) {
			$required = array();
			if ($api_field_parameters['required_create'])
				$required[] = 'create';
			if ($api_field_parameters['required_update'])
				$required[] = 'update';

			$api_fields[$api_field] = sprintf("%s (getter: %s, setter: %s, required: %s, aliases: %s)",
					strlen($api_field_parameters['description']) > 0 ? $api_field_parameters['description'] : 'no description',
					strlen($api_field_parameters['getter']) > 0 ? $api_field_parameters['getter'] : 'no getter',
					strlen($api_field_parameters['setter']) > 0 ? $api_field_parameters['setter'] : 'no setter',
					count($required) > 0 ? implode(', ', $required) : 'no',
					count($api_field_parameters['aliases']) > 0 ? implode(', ', $api_field_parameters['aliases']) : 'none'
				);
		}

		return $api_fields;
	}

	/**
	 * Returns list of required API fields for objects of this class.
	 *
	 * @param bool $create True when object will be created. False when object will be updated.
	 * @return string[]
	 */
	static public function getRequiredAPIFields($create) {
		static::initAPIFieldsAccessors();
		$classname = get_called_class();

		$required_fields = array();
		foreach (self::$_api_fields[$classname] as $api_field => $api_field_parameters) {
			if (($create && $api_field_parameters['required_create'] === false) || (!$create && $api_field_parameters['required_update'] === false))
				continue;

			$required_fields[] = $api_field;
		}

		return $required_fields;
	}

	/**
	 * Checks wheter this object has all required fields set.
	 *
	 * @param bool $create True when object will be created. False when object will be updated.
	 * @param bool $throw_exception True to throw an exception on missing fields. False to return list of missing fields or true when there are none.
	 * @throws kyException When there are missing field values and $throw_exception is true.
	 * @return string[]|bool List of missing API fields or true when there are none.
	 */
	public function checkRequiredAPIFields($create, $throw_exception = true) {
		$classname = get_class($this);
		/** @noinspection PhpUndefinedMethodInspection */
		$classname::initAPIFieldsAccessors();

		$missing_fields = array();
		foreach (self::$_api_fields[$classname] as $api_field => $api_field_parameters) {
			if (($create && $api_field_parameters['required_create'] === false) || (!$create && $api_field_parameters['required_update'] === false))
				continue;

			$property = $api_field_parameters['property'];
			$property_value = $this->$property;
			if ($property_value === null || (is_array($property_value) && count($property_value) === 0)) {
				$missing_fields[] = $api_field;
			}
		}

		if (count($missing_fields) > 0) {
			if ($throw_exception)
				throw new kyException(sprintf("Values for API fields '%s' is required for this operation to complete.", implode(', ', $missing_fields)));

			return $missing_fields;
		}

		return true;
	}

	/**
	 * Returns API field value.
	 *
	 * Returns API field value based on API field name used by Kayako.
	 * @link http://wiki.kayako.com/display/DEV/REST+API+Reference
	 *
	 * @param string $api_field_name API field name.
	 * @return mixed
	 */
	public function __get($api_field_name) {
		static::initAPIFieldsAccessors();
		$classname = get_class($this);

		foreach (self::$_api_fields[$classname] as $api_field => $api_field_parameters) {
			if ($api_field !== $api_field_name && !in_array($api_field_name, $api_field_parameters['aliases']))
				continue;

			$api_field_getter = $api_field_parameters['getter'];
			if ($api_field_getter !== null) {
				return $this->$api_field_getter();
			} else {
				return null;
			}
		}

		trigger_error(sprintf('Undefined property: %s::$%s', $classname, $api_field_name), E_USER_NOTICE);
		return null;
	}

	/**
	 * Sets API field value.
	 *
	 * Sets API field value based on API field name used by Kayako.
	 * @link http://wiki.kayako.com/display/DEV/REST+API+Reference
	 *
	 * @param string $api_field_name API field name.
	 * @param mixed $value API field value.
	 * @return mixed
	 */
	public function __set($api_field_name, $value) {
		static::initAPIFieldsAccessors();
		$classname = get_class($this);

		foreach (self::$_api_fields[$classname] as $api_field => $api_field_parameters) {
			if ($api_field !== $api_field_name && !in_array($api_field_name, $api_field_parameters['aliases']))
				continue;

			$api_field_setter = $api_field_parameters['setter'];
			if ($api_field_setter !== null) {
				$this->$api_field_setter($value);
			} else {
				trigger_error(sprintf('Read-only property: %s::$%s', $classname, $api_field_name), E_USER_NOTICE);
			}
			return;
		}

		trigger_error(sprintf('Undefined property: %s::$%s', $classname, $api_field_name), E_USER_NOTICE);
	}

	/**
	 * Returns list of available filter methods for use in result sets with objects of this type.
	 * Optionaly you can return get method names used to filter objects.
	 *
	 * @param bool $filter_names_only True (default) to return array('filterByXXX', 'filterByYYY', ...). False to return array('filterByXXX' => 'getXXX', 'filterByYYY' => 'YYY', ...).
	 * @return array
	 */
	static public function getAvailableFilterMethods($filter_names_only = true) {
		$class_name = get_called_class();
		if (!array_key_exists($class_name, self::$_filter_methods)) {
			$filter_methods = array();

			//get public methods in the class and search for @filterBy name=filter_name in doc comment
			$class = new ReflectionClass($class_name);
			foreach ($class->getMethods(ReflectionMethod::IS_PUBLIC) as $method) {
				/** @var $method ReflectionMethod */
				$get_method_name = $method->getName();
				$method_comment = $method->getDocComment();
				$parameters = ky_get_tag_parameters($method_comment, 'filterBy');
				if ($parameters === false)
					continue;

				if (array_key_exists('name', $parameters)) {
					$filter_method_name = $parameters['name'];
				} else {
					$filter_method_name = preg_replace('/^get/', '', $get_method_name);
				}
				$filter_methods[kyResultSet::FILTER_PREFIX . $filter_method_name] = $get_method_name;
			}

			self::$_filter_methods[$class_name] = $filter_methods;
		}

		return $filter_names_only ? array_keys(self::$_filter_methods[$class_name]) : self::$_filter_methods[$class_name];
	}

	/**
	 * Returns list of available order methods for use in result sets with objects of this type.
	 * Optionaly you can return get method names used to order objects.
	 *
	 * @param bool $order_names_only True (default) to return array('orderByXXX', 'orderByYYY', ...). False to return array('orderByXXX' => 'getXXX', 'orderByYYY' => 'YYY', ...).
	 * @return array
	 */
	static public function getAvailableOrderMethods($order_names_only = true) {
		$class_name = get_called_class();
		if (!array_key_exists($class_name, self::$_order_methods)) {
			$order_methods = array();

			//get public methods in the class and search for @orderBy order_method_name in doc comment
			$class = new ReflectionClass($class_name);
			foreach ($class->getMethods(ReflectionMethod::IS_PUBLIC) as $method) {
				/** @var $method ReflectionMethod */
				$get_method_name = $method->getName();
				$method_comment = $method->getDocComment();
				$parameters = ky_get_tag_parameters($method_comment, 'orderBy');
				if ($parameters === false)
					continue;

				if (array_key_exists('name', $parameters)) {
					$order_method_name = $parameters['name'];
				} else {
					$order_method_name = preg_replace('/^get/', '', $get_method_name);
				}
				$order_methods[kyResultSet::ORDER_PREFIX . $order_method_name] = $get_method_name;
			}

			self::$_order_methods[$class_name] = $order_methods;
		}

		return $order_names_only ? array_keys(self::$_order_methods[$class_name]) : self::$_order_methods[$class_name];
	}

	/**
	 * Returns object description with it's type and identifier.
	 * Calls toString() method to get the object description.
	 *
	 * @return string
	 */
	public function __toString() {
		return sprintf("%s (id: %s): %s\n", get_class($this), implode(', ', $this->getId(true)), $this->toString());
	}
}