Kayako PHP API Library
Back to top  

Kayako NewsItem object.

Known issues: - could not create NewsItem with PUBLIC and PRIVATE type (http://dev.kayako.com/browse/SWIFT-3108) - fields customemailsubject and fromname are ignored (http://dev.kayako.com/browse/SWIFT-3111)

author Tomasz Sawicki (https://github.com/Furgas)
link http://wiki.kayako.com/display/DEV/REST+-+NewsItem
since Kayako version 4.51.1891
package Object\News

 Methods

Returns whether this news item is expired.

IsExpired() : bool

filterBy name=IsExpired
orderBy name=IsExpired

Returns

bool

Default constructor.

__construct(array $data) 
Inherited

inherited_from \kyObjectBase::__construct()

Parameters

$data

array

Object data from XML response converted into array.

Returns API field value.

__get(string $api_field_name) : mixed
Inherited

Returns API field value based on API field name used by Kayako.

link http://wiki.kayako.com/display/DEV/REST+API+Reference
inherited_from \kyObjectBase::__get()

Parameters

$api_field_name

string

API field name.

Returns

mixed

Sets API field value.

__set(string $api_field_name, mixed $value) : mixed
Inherited

Sets API field value based on API field name used by Kayako.

link http://wiki.kayako.com/display/DEV/REST+API+Reference
inherited_from \kyObjectBase::__set()

Parameters

$api_field_name

string

API field name.

$value

mixed

API field value.

Returns

mixed

Returns object description with it's type and identifier.

__toString() : string
Inherited

Calls toString() method to get the object description.

inherited_from \kyObjectBase::__toString()

Returns

string

Adds category to the list of this news item categories.

addCategory(\kyNewsCategory $category, bool $clear) : \kyNewsItem

Parameters

$category

\kyNewsCategory

News category.

$clear

bool

Clear the list before adding.

Returns

\kyNewsItem

Add staff group to the list of groups that this news item will be visible to.

addStaffGroup(\kyStaffGroup $staff_group, bool $clear) : \kyNewsItem

Automatically sets custom staff visibility flag to True.

Parameters

$staff_group

\kyStaffGroup

Staff group that this news item will be visible to.

$clear

bool

Clear the list before adding.

Returns

\kyNewsItem

Add user group to the list of groups that this news item will be visible to.

addUserGroup(\kyUserGroup $user_group, bool $clear) : \kyNewsItem

Automatically sets custom user visibility flag to True.

Parameters

$user_group

\kyUserGroup

User group that this news item will be visible to.

$clear

bool

Clear the list before adding.

Returns

\kyNewsItem

Should build the array of object data for creating or updating the object.

buildData(bool $create) : array

Values must be set in format accepted by REST API.

Parameters

$create

bool

Indicates if the result will be used to create (true) or update (false) an object.

Returns

array

Checks wheter this object has all required fields set.

checkRequiredAPIFields(bool $create, bool $throw_exception) : string[] | bool
Inherited

inherited_from \kyObjectBase::checkRequiredAPIFields()

Parameters

$create

bool

True when object will be created. False when object will be updated.

$throw_exception

bool

True to throw an exception on missing fields. False to return list of missing fields or true when there are none.

Exceptions

\kyException When there are missing field values and $throw_exception is true.

Returns

string[]boolList of missing API fields or true when there are none.

Creates an object on the server and refreshes its local data.

create() : \kyObjectBase
Inherited

inherited_from \kyObjectBase::create()

Exceptions

\BadMethodCallException
\kyException

Returns

\kyObjectBase

Creates a news item.

createNew(string $subject, string $contents, \kyStaff $staff) : \kyNewsItem

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

Parameters

$subject

string

Subject of news item.

$contents

string

Contents of news item.

$staff

\kyStaff

Author (staff) of news item.

Returns

\kyNewsItem

Deletes the object on the server.

delete() 
Inherited

inherited_from \kyObjectBase::delete()

Fetches the object from server.

get(int | array $id) : \kyObjectBase
Inherited

inherited_from \kyObjectBase::get()

Parameters

$id

intarray

Object identifier or list of identifiers (ex. ticket identifier and ticket post identifier when fetching TicketPost).

Returns

\kyObjectBase

Returns array of API fields.

getAPIFields() : string[]
Inherited

Format of returned array:

array(
    '' => Field description. (getter: , setter: ),
    ...repeat...
)

inherited_from \kyObjectBase::getAPIFields()

Returns

string[]

Fetches objects from server.

getAll($category) : \kyResultSet

Parameters

$category

Returns

\kyResultSet

Returns whether clients are permitted to comment on this news item.

getAllowComments() : bool

filterBy
orderBy

Returns

bool

Returns full name of author.

getAuthor() : string

filterBy
orderBy

Returns

string

Returns email of author.

getAuthorEmail() : string

filterBy
orderBy

Returns

string

Returns list of available filter methods for use in result sets with objects of this type.

getAvailableFilterMethods(bool $filter_names_only) : array
Inherited

Optionaly you can return get method names used to filter objects.

inherited_from \kyObjectBase::getAvailableFilterMethods()

Parameters

$filter_names_only

bool

True (default) to return array('filterByXXX', 'filterByYYY', ...). False to return array('filterByXXX' => 'getXXX', 'filterByYYY' => 'YYY', ...).

Returns

array

Returns list of available order methods for use in result sets with objects of this type.

getAvailableOrderMethods(bool $order_names_only) : array
Inherited

Optionaly you can return get method names used to order objects.

inherited_from \kyObjectBase::getAvailableOrderMethods()

Parameters

$order_names_only

bool

True (default) to return array('orderByXXX', 'orderByYYY', ...). False to return array('orderByXXX' => 'getXXX', 'orderByYYY' => 'YYY', ...).

Returns

array

Returns categories of this news item.

getCategories(bool $reload) : \kyResultSet

Result is cached until the end of script.

Parameters

$reload

bool

True to reload data from server. False to use the cached value (if present).

Returns

\kyResultSet

Returns identifiers of categories of this news item.

getCategoryIds() : array

filterBy name=CategoryId

Returns

array

Returns contents of the news item.

getContents() : string

filterBy

Returns

string

Returns object controller.

getController() : string
Inherited

inherited_from \kyObjectBase::getController()

Returns

string

Returns date and time when the news item was created.

getDateline(string $format) : string

see \global\http://www.php.net/manual/en/function.date.php
filterBy
orderBy

Parameters

$format

string

Output format of the date. If null the format set in client configuration is used.

Returns

string

Returns subject of notification email.

getEmailSubject() : string

filterBy
orderBy

Returns

string

Returns expiration date of the user or null when expiration is disabled.

getExpiry(string $format) : string

see \global\http://www.php.net/manual/en/function.date.php
filterBy
orderBy

Parameters

$format

string

Output format of the date. If null the format set in client configuration is used.

Returns

string

Should return object identifier or complete list of identifiers as needed by API to identify the object (ex.

getId(bool $complete) : int | array

ticket identifier and ticket post identifier in case of TicketPost).

Parameters

$complete

bool

True to return complete list of identifiers as needed by API to identify the object.

Returns

intarray

Returns whether this news item was downloaded (synchronised) from external RSS feed.

getIsSynced() : bool

filterBy
orderBy

Returns

bool

Returns list of required API fields for objects of this class.

getRequiredAPIFields(bool $create) : string[]
Inherited

inherited_from \kyObjectBase::getRequiredAPIFields()

Parameters

$create

bool

True when object will be created. False when object will be updated.

Returns

string[]

Gets the staff user, the creator of this news item.

getStaff(bool $reload) : \kyStaff

Parameters

$reload

bool

True to reload data from server. False to use the cached value (if present).

Returns

\kyStaff

Returns identifiers of staff groups that this news item will be visible to.

getStaffGroupIds() : array

filterBy name=StaffGroupId

Returns

array

Returns staff groups that this news item will be visible to.

getStaffGroups(bool $reload) : \kyResultSet

Result is cached until the end of script.

Parameters

$reload

bool

True to reload data from server. False to use the cached value (if present).

Returns

\kyResultSet

Returns identifier of staff user, the creator of this news item.

getStaffId() : int

filterBy
orderBy

Returns

int

Returns true to indicate that visibility of this news item is restricted to particular staff groups.

getStaffVisibilityCustom() : bool

Use getStaffGroupIds to get their identifiers or getStaffGroups to get the objects.

filterBy

Returns

bool

Returns status of the news item.

getStatus() : int

see \global\kyNewsItem::STATUS
filterBy
orderBy

Returns

int

Returns subject of the news item.

getSubject() : string

filterBy
orderBy

Returns

string

Returns total count of comments on this news item.

getTotalComments() : int

filterBy
orderBy

Returns

int

Return type of the news item.

getType() : int

see \global\kyNewsItem::TYPE
filterBy
orderBy

Returns

int

Returns identifiers of user groups that this news item will be visible to.

getUserGroupIds() : array

filterBy name=UserGroupId

Returns

array

Returns user groups that this news item will be visible to.

getUserGroups(bool $reload) : \kyResultSet

Result is cached until the end of script.

Parameters

$reload

bool

True to reload data from server. False to use the cached value (if present).

Returns

\kyResultSet

Returns true to indicate that visibility of this news item is restricted to particular user groups.

getUserVisibilityCustom() : bool

Use getUserGroupIds to get their identifiers or getUserGroups to get the objects.

filterBy

Returns

bool

Returns whether this news is in specified category.

isInCategory(\kyNewsCategory | int $category) : bool

filterBy

Parameters

$category

\kyNewsCategoryint

News category or its identifier.

Returns

bool

Returns whether the object is new and not yet saved on the server.

isNew() : bool
Inherited

inherited_from \kyObjectBase::isNew()

Returns

bool

Returns whether this object is read only.

isReadOnly() : bool
Inherited

inherited_from \kyObjectBase::isReadOnly()

Returns

bool

Returns whether this news item is visible to specified staff group.

isVisibleToStaffGroup(\kyStaffGroup | int $staff_group, bool $check_expiration) : bool

filterBy

Parameters

$staff_group

\kyStaffGroupint

Staff group or its identifier.

$check_expiration

bool

Whether to also check if news item is expired.

Returns

bool

Returns whether this news item is visible to specified user group.

isVisibleToUserGroup(\kyUserGroup | int $user_group, bool $check_expiration) : bool

filterBy

Parameters

$user_group

\kyUserGroupint

User group or its identifier.

$check_expiration

bool

Whether to also check if news item is expired.

Returns

bool

Refreshes the object data from server.

refresh() : \kyObjectBase
Inherited

inherited_from \kyObjectBase::refresh()

Exceptions

\BadMethodCallException

Returns

\kyObjectBase

Saves (creates or updates) the object to the server.

save() : \kyObjectBase
Inherited

inherited_from \kyObjectBase::save()

Returns

\kyObjectBase

Sets whether clients are permitted to comment on this news item.

setAllowComments(bool $allow_comments) : \kyNewsItem

Parameters

$allow_comments

bool

True to allow clients to comment on this news item.

Returns

\kyNewsItem

Sets categories (using their identifiers) for this news item.

setCategoryIds(int[] $category_ids) : \kyNewsItem

Parameters

$category_ids

int[]

Identifiers of categories for this news item.

Returns

\kyNewsItem

Sets contents of the news item.

setContents(string $contents) : \kyNewsItem

Parameters

$contents

string

Contents of the news item.

Returns

\kyNewsItem

Sets staff user, the editor of this news item update.

setEditedStaff(\kyStaff $staff) : \kyNewsItem

Parameters

$staff

\kyStaff

Staff user.

Returns

\kyNewsItem

Sets identifier of staff user, the editor of this news item update.

setEditedStaffId(int $staff_id) : \kyNewsItem

Parameters

$staff_id

int

Staff user identifier.

Returns

\kyNewsItem

Sets address of notification email sender.

setEmail(string $email) : \kyNewsItem

Parameters

$email

string

The From Email address that will be used for the emails sent out to subscribers. Please note that this may be the address users reply back to (if they reply to the news article email).

Returns

\kyNewsItem

Sets subject of notification email.

setEmailSubject(string $email_subject) : \kyNewsItem

see \global\http://dev.kayako.com/browse/SWIFT-3111

Parameters

$email_subject

string

Subject for the mass email that will be send out to the subscribers for this news article. If no subject is specified, the subject of the news article will be used instead.

Returns

\kyNewsItem

Sets expiration date of the news item.

setExpiry(string | int | null $expiry) : \kyNewsItem

see \global\http://www.php.net/manual/en/function.strtotime.php

Parameters

$expiry

stringintnull

Date and time when the news item will expire (timestamp or string format understood by PHP strtotime). Null to disable expiration.

Returns

\kyNewsItem

Sets name of notification email sender.

setFromName(string $from_name) : \kyNewsItem

see \global\http://dev.kayako.com/browse/SWIFT-3111

Parameters

$from_name

string

The From Name email header that will be used for the emails sent out to subscribers.

Returns

\kyNewsItem

Sets whether this object is read only.

setReadOnly(bool $read_only) : bool
Inherited

inherited_from \kyObjectBase::setReadOnly()

Parameters

$read_only

bool

Read only flag.

Returns

bool

Sets whether to send notification email to subscribers when creating or updating this news item.

setSendEmail(bool $send_email) : \kyNewsItem

Parameters

$send_email

bool

True to send notification email to subscribers when creating or updating this news item. False otherwise.

Returns

\kyNewsItem

Sets staff user, the creator of this news item.

setStaff(\kyStaff $staff) : \kyNewsItem

Parameters

$staff

\kyStaff

Staff user.

Returns

\kyNewsItem

Sets staff groups (using their identifiers) that this news item will be visible to.

setStaffGroupIds(int[] $staff_group_ids) : \kyNewsItem

Parameters

$staff_group_ids

int[]

Identifiers of staff groups that this news item will be visible to.

Returns

\kyNewsItem

Sets identifier of staff user, the creator of this news item.

setStaffId(int $staff_id) : \kyNewsItem

Parameters

$staff_id

int

Staff user identifier.

Returns

\kyNewsItem

Sets wheter to restrict visibility of this news item to particular staff groups.

setStaffVisibilityCustom(bool $staff_visibility_custom) : \kyNewsItem

Use setStaffGroupIds to set these groups using identifiers or addStaffGroup to set them using objects. Automatically clears staff groups when set to false.

Parameters

$staff_visibility_custom

bool

True to restrict visibility of this news item to particular staff groups. False otherwise.

Returns

\kyNewsItem

Sets status of the news item.

setStatus(int $status) : \kyNewsItem

see \global\kyNewsItem::STATUS

Parameters

$status

int

Status of the news item.

Returns

\kyNewsItem

Sets subject of the news item.

setSubject(string $subject) : \kyNewsItem

Parameters

$subject

string

Subject of the news item.

Returns

\kyNewsItem

Sets type of the news item.

setType(int $type) : \kyNewsItem

see \global\kyNewsItem::TYPE
see \global\http://dev.kayako.com/browse/SWIFT-3108

Parameters

$type

int

Type of the news item.

Returns

\kyNewsItem

Sets user groups (using their identifiers) that this news item will be visible to.

setUserGroupIds(int[] $user_group_ids) : \kyNewsItem

Parameters

$user_group_ids

int[]

Identifiers of user groups that this news item will be visible to.

Returns

\kyNewsItem

Sets wheter to restrict visibility of this news item to particular user groups.

setUserVisibilityCustom(bool $user_visibility_custom) : \kyNewsItem

Use setUserGroupIds to set these groups using identifiers or addUserGroup to set them using objects. Automatically clears user groups when set to false.

Parameters

$user_visibility_custom

bool

True to restrict visibility of this news item to particular user groups. False otherwise.

Returns

\kyNewsItem

Should return short (one line) description of the object (it's title, name, etc.).

toString() : string

Returns

string

Updates the object on the server and refreshes its local data.

update() : \kyObjectBase
Inherited

inherited_from \kyObjectBase::update()

Exceptions

\BadMethodCallException
\kyException

Returns

\kyObjectBase

Adds boolean field to object data array only if its value is non-empty.

buildDataBool(array $data, string $field_name, mixed $field_value) 
Inherited

inherited_from \kyObjectBase::buildDataBool()

Parameters

$data

array

Data used to create or update the object.

$field_name

string

Field name.

$field_value

mixed

Field value.

Adds array field to object data array only if its value is proper array and is non-empty.

buildDataList(array $data, string $field_name, mixed $field_value) 
Inherited

inherited_from \kyObjectBase::buildDataList()

Parameters

$data

array

Data used to create or update the object.

$field_name

string

Field name.

$field_value

mixed

Field value.

Adds numeric field to object data array only if its value is proper number.

buildDataNumeric(array $data, string $field_name, mixed $field_value) 
Inherited

inherited_from \kyObjectBase::buildDataNumeric()

Parameters

$data

array

Data used to create or update the object.

$field_name

string

Field name.

$field_value

mixed

Field value.

Adds string field to object data array only if its value is non-empty.

buildDataString(array $data, string $field_name, mixed $field_value) 
Inherited

inherited_from \kyObjectBase::buildDataString()

Parameters

$data

array

Data used to create or update the object.

$field_name

string

Field name.

$field_value

mixed

Field value.

Returns REST client.

getRESTClient() : \kyRESTClientInterface
Inherited

inherited_from \kyObjectBase::getRESTClient()

Returns

\kyRESTClientInterface

Should use passed data to fill object properties.

parseData(array $data) 

Parameters

$data

array

Object data from XML response.

Builds API fields list.

initAPIFieldsAccessors() 
Inherited

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 \global\kyObjectBase::$_api_fields
inherited_from \kyObjectBase::initAPIFieldsAccessors()

 Properties

 

Cache for available filter methods.

$_filter_methods : string[]
Inherited

Format: array( '' => array( '' => '', ...repeat for every filtering enabled method... ), ...repeat for every object class... )

inherited_from \kyObjectBase::$$_filter_methods
 

Cache for available order methods.

$_order_methods : string[]
Inherited

Format: array( '' => array( '' => '', ...repeat for every ordering enabled method... ), ...repeat for every object class... )

inherited_from \kyObjectBase::$$_order_methods
 

Whether to allow comments.

$allow_comments : bool

apiField
 

Author's fullname.

$author : string

apiField
 

Author's email.

$author_email : string

 

Identifiers of news categories this news item belongs to.

$category_ids : int[]

apiField name=categories
 

News item contents.

$contents : string

apiField required=true
 

Default Kayako controller used to operate on this objects.

$controller : string

Override in descending classes.

 

Timestamp of when the news item was created.

$dateline : int

apiField
 

Editor (staff) identifier.

$edited_staff_id : int

apiField required_update=true
 

Address of email notification sender.

$email : string

apiField
 

Email subject.

$email_subject : string

apiField alias=customemailsubject
 

Timestamp of when this news item will expire.

$expiry : int

apiField
 

Name of email notification sender.

$from_name : string

 

News item identifier.

$id : int

apiField
 

Whether this news item was downloaded (synchronised) from external RSS feed.

$is_synced : bool

apiField
 

Indicates the name of object element in XML response.

$object_xml_name : string

Override in descending classes.

 

Controls if the object can be created/updated/deleted.

$read_only : bool
Inherited

Override in descending classes.

inherited_from \kyObjectBase::$$read_only
 

Whether to send email.

$send_email : bool

apiField
 

User group identifiers this news item is visible to.

$staff_group_ids : int[]

apiField name=staffgroupidlist
 

Creator (staff) identifier.

$staff_id : int

apiField required_create=true
 

If this news item is visible to specific staff groups only.

$staff_visibility_custom : bool

see \global\kyNewsItem::$staff_group_ids
apiField
 

News item status.

$status : int

apiField name=newsstatus
 

News item subject.

$subject : string

apiField
 

Total count of news item comments.

$total_comments : int

apiField
 

News item type.

$type : int

apiField name=newstype
 

User group identifiers this news item is visible to.

$user_group_ids : int[]

apiField name=usergroupidlist
 

If this news item is visible to specific user groups only.

$user_visibility_custom : bool

see \global\kyNewsItem::$user_group_ids
apiField
 

Cache for API fields.

$_api_fields : array
Inherited

Format: array( '' => array( '' => array( 'property' => '', 'description' => '', 'getter' => '', 'setter' => '', 'required_create' => , 'required_update' => ), ...repeat for every class api field... ), ...repeat for every object class... )

inherited_from \kyObjectBase::$$_api_fields
 

News categories this news item belongs to.

$categories : \kyNewsCategory[]

 

Editor (staff).

$edited_staff : \kyStaff

 

Creator (staff).

$staff : \kyStaff

 

User groups this news item is visible to.

$staff_groups : \kyStaffGroup[]

 

User groups this news item is visible to.

$user_groups : \kyUserGroup[]

 Constants

 

Data key for storing files to send as multipart/form-data.

FILES_DATA_NAME : string
Inherited

inherited_from \kyObjectBase::FILES_DATA_NAME
 

News status - Draft.

STATUS_DRAFT : int

 

News status - Published.

STATUS_PUBLISHED : int

 

News type - Global.

TYPE_GLOBAL : int

The news articles classified as Global are visible in both the client support center and the staff control panel.

 

News type - Private.

TYPE_PRIVATE : int

The news article classified as Private are only visible in the staff control panel.

 

News type - Public.

TYPE_PUBLIC : int

The news articles classified as Public are visible only in the client support center.