<?php

/**

* Base class for comment objects.

* Known issues:

* - creatorid is not set when logged user posts a comment from client area

* - when creating User comment through API, exception is thrown by Kayako (NewsItem and TroubleshooterStep)

*

* @author Tomasz Sawicki (https://github.com/Furgas)

* @since Kayako version 4.51.1891

* @package Object\Base

*

* @noinspection PhpDocSignatureInspection

*/

abstract class kyCommentBase extends kyObjectBase {

/**

* Comment creator type - Staff.

* @var int

*/

const CREATOR_TYPE_STAFF = 1;

/**

* Comment creator type - User.

* @var int

*/

const CREATOR_TYPE_USER = 2;

/**

* Comment status - Pending approval.

* @var int

*/

const STATUS_PENDING = 1;

/**

* Comment status - Approved.

* @var int

*/

const STATUS_APPROVED = 2;

/**

* Comment status - Marked as spam.

* @var int

*/

const STATUS_SPAM = 3;

/**

* Comment identifier.

* @apiField

* @var int

*/

protected $id;

/**

* Type of this comment creator.

* @apiField required_create=true

* @var int

*/

protected $creator_type;

/**

* Identifier of this comment creator.

* @apiField

* @var int

*/

protected $creator_id;

/**

* Staff creator of this comment (if applicable).

* @var kyStaff

*/

protected $creator_staff;

/**

* User creator of this comment (if applicable).

* @var kyUser

*/

protected $creator_user;

/**

* Fullname of this comment creator.

* @apiField name=fullname

* @var string

*/

protected $creator_fullname;

/**

* E-mail of this comment creator.

* @apiField name=email

* @var string

*/

protected $creator_email;

/**

* IP address of machine where this comment originated from.

* @apiField

* @var string

*/

protected $ip_address;

/**

* Timestamp of when the comment was created.

* @apiField

* @var int

*/

protected $dateline;

/**

* Identifier of parent comment (comment that this comment is a reply to).

* @apiField

* @var int

*/

protected $parent_comment_id;

/**

* Parent comment (comment that this comment is a reply to).

* @var kyCommentBase

*/

protected $parent_comment;

/**

* Status of this comment.

* @apiField name=commentstatus

* @var int

*/

protected $status;

/**

* Information about browser on which this comment was created.

* @apiField

* @var string

*/

protected $user_agent;

/**

* URL of page on which this comment was created.

* @apiField

* @var string

*/

protected $referrer;

/**

* URL of commented item.

* @apiField

* @var string

*/

protected $parent_url;

/**

* Contents of this comment.

* @apiField required_create=true

* @var string

*/

protected $contents;

protected function parseData($data) {

$this->id = ky_assure_positive_int($data['id']);

$this->creator_type = ky_assure_positive_int($data['creatortype']);

$this->creator_id = ky_assure_positive_int($data['creatorid']);

$this->creator_fullname = ky_assure_string($data['fullname']);

$this->creator_email = ky_assure_string($data['email']);

$this->ip_address = ky_assure_string($data['ipaddress']);

$this->dateline = ky_assure_positive_int($data['dateline']);

$this->parent_comment_id = ky_assure_positive_int($data['parentcommentid']);

$this->status = ky_assure_positive_int($data['commentstatus']);

$this->user_agent = ky_assure_string($data['useragent']);

$this->referrer = ky_assure_string($data['referrer']);

$this->parent_url = ky_assure_string($data['parenturl']);

$this->contents = ky_assure_string($data['contents']);

}

public function buildData($create) {

$this->checkRequiredAPIFields($create);

$data = array();

if ($this->creator_type === self::CREATOR_TYPE_STAFF) {

if ($this->creator_id == null) {

throw new kyException("Value for API field 'creatorid' is required for this operation to complete.");

}

$this->buildDataNumeric($data, 'creatorid', $this->creator_id);

} elseif ($this->creator_type === self::CREATOR_TYPE_USER) {

if ($this->creator_id == null && $this->creator_fullname == null) {

throw new kyException("Value for API fields 'creatorid' or 'fullname' is required for this operation to complete.");

}

if ($this->creator_id != null) {

$this->buildDataNumeric($data, 'creatorid', $this->creator_id);

} else {

$this->buildDataString($data, 'fullname', $this->creator_fullname);

}

}

$this->buildDataString($data, 'contents', $this->contents);

$this->buildDataNumeric($data, 'creatortype', $this->creator_type);

$this->buildDataString($data, 'email', $this->creator_email);

$this->buildDataNumeric($data, 'parentcommentid', $this->parent_comment_id);

return $data;

}

public function toString() {

return sprintf("%s%s (author: %s, status: %d)", strtr(substr($this->getContents(), 0, 20), "\n", " "), strlen($this->getContents()) > 20 ? "..." : "", $this->getCreatorFullname(), $this->getStatus());

}

public function getId($complete = false) {

return $complete ? array($this->id) : $this->id;

}

/**

* Returns creator type of the comment.

*

* @see kyCommentBase::CREATOR_TYPE constants.

*

* @return int

* @filterBy

* @orderBy

*/

public function getCreatorType() {

return $this->creator_type;

}

/**

* Sets creator type of the comment.

*

* Automatically resets creator fullname to null when set to Staff.

*

* @see kyCommentBase::CREATOR_TYPE constants.

*

* @param int $creator_type Creator type of the comment.

* @return $this

*/

public function setCreatorType($creator_type) {

$this->creator_type = ky_assure_constant($creator_type, $this, 'CREATOR_TYPE');

switch ($this->creator_type) {

case self::CREATOR_TYPE_STAFF:

$this->creator_fullname = null;

$this->creator_user = null;

break;

case self::CREATOR_TYPE_USER:

$this->creator_staff = null;

break;

}

return $this;

}

/**

* Returns identifier of creator of this comment.

*

* @return int

* @filterBy

* @orderBy

*/

public function getCreatorId() {

return $this->creator_id;

}

/**

* Sets identifier of creator of this comment.

*

* Automatically resets creator fullname to null.

*

* @param int $creator_id Identifier of creator of this comment.

* @return $this

*/

public function setCreatorId($creator_id) {

$this->creator_id = ky_assure_positive_int($creator_id);

$this->creator_fullname = null;

return $this;

}

/**

* Returns the creator of this comment.

*

* Result is cached until the end of script.

*

* @param bool $reload True to reload data from server. False to use the cached value (if present).

* @return kyUser|kyStaff

* @filterBy

*/

public function getCreator($reload = false) {

switch ($this->creator_type) {

case self::CREATOR_TYPE_STAFF:

if ($this->creator_staff !== null && !$reload)

return $this->creator_staff;

if ($this->creator_id === null)

return null;

$this->creator_staff = kyStaff::get($this->creator_id);

return $this->creator_staff;

case self::CREATOR_TYPE_USER:

if ($this->creator_user !== null && !$reload)

return $this->creator_user;

if ($this->creator_id === null)

return null;

$this->creator_user = kyUser::get($this->creator_id);

return $this->creator_user;

}

return null;

}

/**

* Sets the creator of this comment.

*

* @param kyUser|kyStaff|string $creator Creator (staff object, user object or user fullname) of this comment.

* @return $this

*/

public function setCreator($creator) {

if ($creator instanceof kyStaff) {

$this->creator_staff = $creator;

$this->creator_id = $this->creator_staff->getId();

$this->creator_type = self::CREATOR_TYPE_STAFF;

$this->creator_user = null;

} elseif ($creator instanceof kyUser) {

$this->creator_user = $creator;

$this->creator_id = $this->creator_user->getId();

$this->creator_type = self::CREATOR_TYPE_USER;

$this->creator_staff = null;

} elseif (is_string($creator) && strlen($creator) > 0) {

$this->setCreatorFullname($creator);

} else {

$this->creator_id = null;

$this->creator_type = null;

$this->creator_staff = null;

$this->creator_user = null;

}

return $this;

}

/**

* Returns fullname of creator of this comment.

*

* @return string

* @filterBy

* @orderBy

*/

public function getCreatorFullname() {

return $this->creator_fullname;

}

/**

* Sets fullname of creator of this comment.

*

* Automatically changes creator type to User and resets creator identifiers to null.

*

* @param string $fullname Fullname of creator of this comment.

* @return $this

*/

public function setCreatorFullname($fullname) {

$this->creator_fullname = $fullname;

$this->creator_type = self::CREATOR_TYPE_USER;

$this->creator_id = null;

$this->creator_user = null;

$this->creator_staff = null;

return $this;

}

/**

* Returns email of creator of this comment.

*

* @return string

* @filterBy

* @orderBy

*/

public function getCreatorEmail() {

return $this->creator_email;

}

/**

* Sets email of creator of this comment.

*

* @param string $email Email of creator of this comment.

* @return $this

*/

public function setCreatorEmail($email) {

$this->creator_email = ky_assure_string($email);

return $this;

}

/**

* Returns IP address of machine where this comment originated from.

*

* @return string

* @filterBy

* @orderBy

*/

public function getIPAddress() {

return $this->ip_address;

}

/**

* Returns date and time when the comment was created.

*

* @see http://www.php.net/manual/en/function.date.php

*

* @param string $format Output format of the date. If null the format set in client configuration is used.

* @return string

* @filterBy

* @orderBy

*/

public function getDateline($format = null) {

if ($this->dateline == null)

return null;

if ($format === null) {

$format = kyConfig::get()->getDatetimeFormat();

}

return date($format, $this->dateline);

}

/**

* Returns identifier of parent comment (comment that this comment is a reply to).

*

* @return int

* @filterBy

* @orderBy

*/

public function getParentCommentId() {

return $this->parent_comment_id;

}

/**

* Sets identifier of parent comment (comment that this comment is a reply to).

*

* @param int $parent_comment_id Identifier of parent comment (comment that this comment is a reply to).

* @return $this

*/

public function setParentCommentId($parent_comment_id) {

$this->parent_comment_id = ky_assure_positive_int($parent_comment_id);

$this->parent_comment = null;

return $this;

}

/**

* Returns parent comment (comment that this comment is a reply to).

*

* Result is cached until the end of script.

*

* @param bool $reload True to reload data from server. False to use the cached value (if present).

* @return kyCommentBase

* @filterBy

* @orderBy

*/

public function getParentComment($reload = false) {

if ($this->parent_comment !== null && !$reload)

return $this->parent_comment;

if ($this->parent_comment_id === null)

return null;

$this->parent_comment = kyNewsComment::get($this->parent_comment_id);

return $this->parent_comment;

}

/**

* Sets the parent comment (comment that this comment is a reply to).

*

* @param kyCommentBase $parent_comment Parent comment (comment that this comment is a reply to).

* @return $this

*/

public function setParentComment($parent_comment) {

$this->parent_comment = ky_assure_object($parent_comment, get_class($this));

$this->parent_comment_id = $this->parent_comment !== null ? $this->parent_comment->getId() : null;

return $this;

}

/**

* Returns status of this comment.

*

* @see kyCommentBase::STATUS constants.

*

* @return int

* @filterBy

* @orderBy

*/

public function getStatus() {

return $this->status;

}

/**

* Returns information about browser on which this comment was created.

*

* @return string

* @filterBy

*/

public function getUserAgent() {

return $this->user_agent;

}

/**

* Returns URL of page on which this comment was created.

*

* @return string

* @filterBy

*/

public function getReferrer() {

return $this->referrer;

}

/**

* Returns URL of commented item.

*

* @return string

*/

public function getParentURL() {

return $this->parent_url;

}

/**

* Returns contents of this comment.

*

* @return int

* @filterBy

*/

public function getContents() {

return $this->contents;

}

/**

* Sets contents of this comment.

*

* @param string $contents Contents of this comment.

* @return $this

*/

public function setContents($contents) {

$this->contents = ky_assure_string($contents);

return $this;

}

/**

* Creates a new comment.

* WARNING: Data is not sent to Kayako unless you explicitly call create() on this method's result.

*

* @param kyUser|kyStaff|string $creator Creator (staff object, user object or user fullname) of this comment.

* @param string $contents Contents of this comment.

* @return static

*/

static public function createNew($creator, $contents) {

/** @var $new_comment kyCommentBase */

$new_comment = new static();

$new_comment->setCreator($creator);

$new_comment->setContents($contents);

return $new_comment;

}

}