Show:

Streams_Stream Class

Extends Base_Streams_Stream
Module: Streams

Class representing 'Stream' rows in the 'Streams' database You can create an object of this class either to access its non-static methods, or to actually represent a stream row in the Streams database.

Methods

__set_state

(
  • $array
)
Streams_Stream

Implements the __set_state method, so it can work with with var_export and be re-imported successfully.

Parameters:

  • $array Array

Returns:

Streams_Stream:

Class instance

addPermission

(
  • $permissions
)

Parameters:

  • $permissions String

addPreloaded

(
  • $asUserId=null
)

Add this stream to the list of streams to be preloaded onto the client with the rest of the page

Parameters:

  • $asUserId=null String

    The id of the user from whose point of view the access should be calculated. If this matches the publisherId, just sets full access and calls publishedByFetcher(true). If this is '', only preloads the streams anybody can see. If this is null, the logged-in user's id is used, or '' if no one is logged in

addPreloaded

()

Remove this stream from the list of streams to be preloaded onto the client with the rest of the page

afterRemoveExcecute

(
  • $result
  • $query
)
Db_Result

Parameters:

Returns:

afterSaveExecute

(
  • $result
  • $query
)
Db_Result

Parameters:

Returns:

beforeSave

(
  • $modifiedFields
)
Array

Does necessary preparations for saving a stream in the database.

Parameters:

  • $modifiedFields Array

    The array of fields

Returns:

Array:

beforeSet_permissions

(
  • $value
)
Array

Method is called before setting the field and verifies that, if it is a string, it contains a JSON array.

Parameters:

  • $value String

Returns:

Array:

An array of field name and value

calculateAccess

(
  • $asUserId
  • [$recalculate=false]
  • [$actualPublisherId=null]
  • [$inheritAccess=true]
)
Integer static

Calculates the access for the current stream by querying the database. Modifies this object, by setting its access levels. After the function returns, you will be able to call the methods testReadLevel(), testWriteLevel() and testAdminLevel() on these streams before using them on the user's behalf.

Parameters:

  • $asUserId String

    Set this to the user relative to whom access is calculated. If this matches the publisherId, just sets full access and calls publishedByFetcher(true). If this is '', only returns the streams anybody can see. If this is null, the logged-in user's id is used, or '' if no one is logged in

  • [$recalculate=false] Boolean optional

    Pass true here to force recalculating access to streams for which access was already calculated

  • [$actualPublisherId=null] String optional

    For internal use only. Used by Streams::isAuthorizedToCreate function.

  • [$inheritAccess=true] String optional

    Set to false to skip inheriting access from other streams, even if specified

Returns:

Integer:

The number of streams that were recalculated

clearAttribute

(
  • $attributeName
)

Parameters:

  • $attributeName String

    The name of the attribute to remove

close

(
  • $asUserId
  • [$options=array()]
)
static

Closes a stream, which prevents anyone from posting messages to it unless they have WRITE_LEVEL >= "close", as well as attempting to remove all relations to other streams. A "cron job" can later go and delete closed streams. The reason you should avoid deleting streams right away is that other subscribers may still want to receive the last messages posted to the stream.

Parameters:

  • $asUserId String

    The id of the user who would be closing the stream

  • [$options=array()] Array optional

    Can include "skipAccess"

displayType

() String static

Returns the type name to display from a stream type

Returns:

String:

exportArray

(
  • $options=array()
  • [$options.asUserId]
  • [$options.skipAccess=false]
  • [$options.fields=null]
)
Array

Returns the fields and values we can export to clients. Can also contain "messageTotals", "relatedToTotals" and "relatedFromTotals".

Parameters:

  • $options=array() Array
  • [$options.asUserId] String optional

    Defaults to the logged in user, or "" if not logged in If access is not already set for the stream, it will be calculated for $asUserId.

  • [$options.skipAccess=false] String optional

    If true, skips access checks

  • [$options.fields=null] Array optional

    By default, all fields from tables used to "extend" the stream are returned. You can indicate here an array consisting of only the names of fields to export. An empty array means no extended fields will be exported.

Returns:

Array:

extendedBy

(
  • $row
)
static

Gets the stream row corresponding to a Db_Row retrieved from a table extending the stream.

Parameters:

  • $row Db_Row

    a Db_Row retrieved from a table extending the stream.

Returns:

Streams_Stream|null

getAllAttributes

() Array

Returns:

Array:

The array of all attributes set in the stream

getAllPermissions

() Array

Returns:

Array:

getAttribute

(
  • $attributeName
  • $default
)
Mixed

Parameters:

  • $attributeName String

    The name of the attribute to get

  • $default Mixed

    The value to return if the attribute is missing

Returns:

Mixed:

The value of the attribute, or the default value, or null

getConfigField

(
  • $type
  • $field
  • [$default=null]
  • [$merge=true]
)
static

Gets a value from the config corresponding to this stream type and a field name, using defaults from "Streams"/"types"/"*" and merging the value under "Streams"/"types"/$stream->type, if any.

Parameters:

  • $type String

    The type of the stream

  • $field String | Array

    The name of the field

  • [$default=null] Mixed optional

    The value to return if the config field isn't specified

  • [$merge=true] Boolean optional

    if arrays are found in both places, merge them

Returns:

mixed

getMessages

(
  • [$options=array()]
  • [options.min]
  • [options.max]
  • [options.limit=100]
  • [options.ascending]
  • [options.type]
)

Fetch messages of the stream.

Parameters:

  • [$options=array()] Array optional

    An array of options determining how messages will be fetched, which can include:

    • [skipLimiting=false] Boolean optional

      Pass true here to not cut the limit off by the getMessagesLimit from config. It's here to protect against excessively large queries.

  • [options.min] Integer optional

    Minimum ordinal of the message to select from (inclusive). Defaults to minimum ordinal of existing messages (if any).

  • [options.max] Integer optional

    Maximum ordinal of the message to select to (inclusive). Defaults to maximum ordinal of existing messages (if any). Can also be negative, then the value will be substracted from maximum number of existing messages and +1 will be added to guarantee that $max = -1 means highest message ordinal.

  • [options.limit=100] Integer optional

    Number of the messages to be selected.

  • [options.ascending] Integer optional

    Sorting of fetched messages by ordinal. If true, sorting is ascending, if false - descending. Defaults to true, but in case if 'min' option not given and only 'max' and 'limit' are given, we assuming fetching in reverse order, so 'ascending' will default to false.

  • [options.type] Integer optional

    Optional string specifying the particular type of messages to get

getParticipant

(
  • [$userId=Users::loggedInUser(true)->id]
)
Db_Row | Null

Fetch a particular participant in the stream, if it exists.

Parameters:

  • [$userId=Users::loggedInUser(true)->id] String optional

    The id of the user who may or may not be participating in the stream

Returns:

Db_Row | Null:

getParticipants

(
  • [$options=array()]
)

Fetch participants of the stream.

Parameters:

  • [$options=array()] Array optional

    An array of options determining how messages will be fetched, which can include:

    • [state] String optional

      One of "invited", "participating", "left"

    • [limit=1000] String optional

      Number of the participants to be selected.

    • [offset=0] String optional

      Number of the messages to be selected.

    • [ascending] String optional

      Sorting of fetched participants by insertedTime. If true, sorting is ascending, if false - descending. Defaults to false.

    • [type] String optional

      Optional string specifying the particular type of messages to get

    • [skipLimiting=false] Boolean optional

      Pass true here to not cut the limit off by the getParticipantsLimit from config. It's here to protect against excessively large queries.

getStreamTemplate

(
  • $publisherId
  • $streamType
  • $className
  • [$templateType=null]
)
Streams_Stream | Array static

Parameters:

  • $publisherId String

    The publisher of the stream

  • $streamType String

    The type of the stream

  • $className String

    The class extending Db_Row to fetch from the database

  • [$templateType=null] &integer optional

    Gets filled with the template type 0-4. Set to true to return all templates.

Returns:

Streams_Stream | Array:

Returns the template stream, or an array if $templateType is true

getSubscriptionTemplate

(
  • $publisherId
  • $streamType
  • $className
  • $ofUserId
  • [$templateType=null]
)
Streams_Subscription | Array static

Parameters:

  • $publisherId String

    The publisher of the stream

  • $streamType String

    The type of the stream

  • $className String

    The class extending Db_Row to fetch from the database

  • $ofUserId String

    The id of the possible subscriber

  • [$templateType=null] &integer optional

    Gets filled with the template type 0-4. Set to true to return all templates.

Returns:

Streams_Subscription | Array:

Returns the template subscription, or an array if $templateType is true

hasPermission

(
  • $permission
)
Boolean

Parameters:

  • $permission String

Returns:

Boolean:

inheritAccess

() Boolean

Inherits access from any streams specified in the inheritAccess field.

Returns:

Boolean:

Returns whether the access potentially changed.

inheritAccessAdd

(
  • [$publisherId]
  • [$streamName]
)
Boolean

Inherit access from a specific stream. Pushes it onto the stack.

Parameters:

  • [$publisherId] String optional

    Publisher id of the stream from which to inherit access

  • [$streamName] String optional

    Name of the stream from which to inherit access

Returns:

Boolean:

Whether it was already there before

inheritAccessRemove

(
  • [$publisherId]
  • [$streamName]
)
Boolean

Stop inheriting access from a specific stream. Splices it from the stack.

Parameters:

  • [$publisherId] String optional

    Publisher id of the stream from which to stop inheriting access

  • [$streamName] String optional

    Name of the stream from which to stop inheriting access

Returns:

Boolean:

Whether it was already there before

invite

(
  • $who
  • [$options=array()]
)
Array static

Invites a user (or a future user) to this stream

Parameters:

  • $who Array

    Array that can contain the following keys:

    • [userId] String | Array optional

      user id or an array of user ids

    • [platform] String optional

      platform for which uids are passed

    • [uid] String | Array optional

      platform uid or array of uids

    • [label] String | Array optional

      label or an array of labels, or tab-delimited string

    • [identifier] String | Array optional

      identifier or an array of identifiers, or tab-delimited string

    • [newFutureUsers] Integer optional

      the number of new Users_User objects to create via Users::futureUser in order to invite them to this stream. This typically is used in conjunction with passing the "html" option to this function.

    • [token=false] Boolean optional

      pass true here to save a Streams_Invite row with empty userId, which is used whenever someone shows up with the token and presents it via "Q.Streams.token" querystring parameter. See the Streams/before/Q_objects.php hook for more information.

  • [$options=array()] Array optional
    • [addLabel] String | Array optional

      label or an array of ($label => array($title, $icon)) for adding publisher's contacts

    • [addMyLabel] String | Array optional

      label or an array of ($label => array($title, $icon)) for adding asUserId's contacts

    • [readLevel] String | Integer optional

      the read level to grant those who are invited

    • [writeLevel] String | Integer optional

      the write level to grant those who are invited

    • [adminLevel] String | Integer optional

      the admin level to grant those who are invited

    • [permissions] Array optional

      array of additional permissions to grant

    • [displayName] String optional

      the display name to use to represent the inviting user

    • [appUrl] String optional

      Can be used to override the URL to which the invited user will be redirected and receive "Q.Streams.token" in the querystring.

    • [html] Array optional

      an array of ($template, $batchName) such as ("MyApp/foo.handlebars", "foo") for generating html snippets which can then be viewed from and printed via the action Streams/invitations?batchName=$batchName&invitingUserId=$asUserId&limit=$limit&offset=$offset

    • [asUserId=Users::loggedInUser(true)->id] String optional

      Invite as this user id, defaults to logged-in user

    • [skipAccess] Boolean optional

      whether to skip access checks when adding labels and contacts

Returns:

Array:

Returns array with keys "success", "userIds", "statuses", "identifierTypes", "alreadyParticipating". The userIds array contains userIds from "userId" first, then "identifiers", "uids", "label", then "newFutureUsers". The statuses is an array of the same size and in the same order. The identifierTypes array is in the same order as well. If the "token" option was set to true, the array also contains the "invite" key pointing to a Streams_Invite object that was saved in the database (whose userId field is empty because anyone with the token may accept this invite).

isRequired

() Boolean

Returns whether the stream is required for the user, and thus shouldn't be deleted, even if it has been marked closed.

Returns:

Boolean:

join

(
  • $options=array()
  • [$options.subscribed]
  • [$options.posted]
  • [$options.extra]
  • [$options.userId]
  • [$options.noVisit]
  • [$options.skipAccess]
)
Streams_Participant | Null

If the user is not participating in the stream yet, inserts a participant record and posts a "Streams/join" or "Streams/visit" type message to the stream, depending on whether the user is already participating in the stream. Otherwise updates the participant record's timestamp and other things. Also relates every stream joined to streams named under the config field "Streams"/"types"/$streamType/"participating"

Parameters:

  • $options=array() Array

    An associative array of options.

  • [$options.subscribed] Boolean optional

    If true, the user is set as subscribed

  • [$options.posted] Boolean optional

    If true, the user is set as subscribed

  • [$options.extra] Array optional

    Any extra information to tree-merge for the participant

  • [$options.userId] String optional

    The user who is joining the stream. Defaults to the logged-in user.

  • [$options.noVisit] Boolean optional

    If user is already participating, don't post a "Streams/visited" message

  • [$options.skipAccess] Boolean optional

    If true, skip access check for whether user can join

Returns:

leave

(
  • $options=array()
  • [$options.userId]
  • [$options.extra]
  • [$options.skipAccess]
  • $participant=null
)
Streams_Participant | Null

If the user is participating in the stream, sets state of participant row as "left" and posts a "Streams/leave" type message to the stream. Also unrelates every stream left to streams named under the config field "Streams"/"types"/$streamType/"participating"

Parameters:

  • $options=array() Array

    An associative array of options.

  • [$options.userId] String optional

    The user who is leaving the stream. Defaults to the logged-in user.

  • [$options.extra] Array optional

    Any extra information to tree-merge for the participant

  • [$options.skipAccess] String optional

    If true, skip access check for whether user can join

  • $participant=null Reference

    Optional reference to a participant object that will be filled to point to the participant object, if any.

Returns:

lowerAdminLevel

()

Calculate admin level to correspond to Streams::$ADMIN_LEVEL Primarily used by apps which invite a user to a stream and giving them a slightly lower admin level.

numericAdminLevel

(
  • $level
)
static

Parameters:

  • $level Integer | String

Returns:

integer

numericReadLevel

(
  • $level
)
static

Parameters:

  • $level Integer | String

Returns:

integer

numericWriteLevel

(
  • $level
)
static

Parameters:

  • $level Integer | String

Returns:

integer

post

(
  • [$asUserId=null]
  • [$messageType='Streams/changed']
  • [$fieldNames=null]
)
Array

Take actions to reflect the stream has changed: save it and post a message.

Parameters:

  • [$asUserId=null] String optional

    The user to post as. Defaults to the logged-in user.

  • [$messageType='Streams/changed'] String optional

    The type of the message.

  • [$fieldNames=null] Array optional

    The names of the fields to check for changes. By default, checks all the standard stream fields.

Returns:

Array:

The array of results - successfully posted messages or false if post failed

post

(
  • $asUserId
  • $message
  • $skipAccess=false
  • $options=array()
)
Array

Post a message to stream

Parameters:

  • $asUserId String

    The user to post as

  • $message Array

    The fields of the message. Also may include 'streamNames' field which is an array of additional names of the streams to post message to.

  • $skipAccess=false Booleam

    If true, skips the access checks and just posts the message.

  • $options=array() Array

Returns:

Array:

The array of results - successfully posted messages or false if post failed

publishedByFetcher

(
  • $new_value=null
)
Boolean

Checks or sets wheather stream was published by fetcher

Parameters:

  • $new_value=null Boolean

    Optional. The value to set

Returns:

Boolean:

register

(
  • $what
)
String static

A convenience method to get the URL of the streams-related action

Parameters:

  • $what String

    Defaults to 'stream'. In the future, can be 'message', 'relation', etc.

Returns:

String:

The corresponding URL

removePermission

(
  • $permission
)

Parameters:

  • $permission String

restrictedFromClient

(
  • $streamType
  • $fieldName
  • [$whenCreating=false]
)
Boolean static

Find out whether a certain field is restricted from being edited by clients via the regular Streams REST API.

Parameters:

  • $streamType String
  • $fieldName String
  • [$whenCreating=false] String optional

Returns:

Boolean:

setAttribute

(
  • $attributeName
  • $value
)

Parameters:

  • $attributeName String | Array

    The name of the attribute to set, or an array of $attributeName => $attributeValue pairs

  • $value Mixed

    The value to set the attribute to

Returns:

Streams_Stream

setUp

()

The setUp() method is called the first time an object of this class is constructed.

testAdminLevel

(
  • $level
)
Boolean

Verifies whether the user has at least a certain admin level in the Stream

Parameters:

  • $level String | Integer

    String describing the level (see Streams::$ADMIN_LEVEL) or integer

Returns:

Boolean:

testPermission

(
  • $permission
)
Boolean

Verifies whether the user has at least the given permission

Parameters:

  • $permission String | Array

    The name of the permission

Returns:

Boolean:

testReadLevel

(
  • $level
)
Boolean

Verifies whether the user has at least a certain read level for the Stream

Parameters:

  • $level String | Integer

    String describing the level (see Streams::$READ_LEVEL) or integer

Returns:

Boolean:

testWriteLevel

(
  • $level
)
Boolean

Verifies whether the user has at least a certain write level for the Stream

Parameters:

  • $level String | Integer

    String describing the level (see Streams::$WRITE_LEVEL) or integer

Returns:

Boolean:

unsubscribe

(
  • $options=array()
  • [$options.leave]
  • [$options.userId]
  • [$options.skipAccess]
)
Streams_Participant | Null

Unsubscribe from a stream, to stop receiving notifications. Posts a "Streams/unsubscribe" message to the stream. Also posts a "Streams/unsubscribed" message to user's "Streams/participating" stream. Does not change the actual subscription, but only the participant row. (When subscribing again, the existing subscription will be used.)

Parameters:

  • $options=array() Array
  • [$options.leave] Boolean optional

    set to true to also leave the streams

  • [$options.userId] Boolean optional

    the user who is unsubscribing from the stream. Defaults to the logged-in user.

  • [$options.skipAccess] Boolean optional

    if true, skip access check for whether user can join and subscribe

Returns:

Properties

$DEFAULTS

Array static

Defaults for stream

$publishedByFetcher

Boolean protected

Whether stream was published by fetcher

$rows

Array

Any fetched database rows that extend the stream

Attributes

$DEFAULTS['adminLevel']

String final

Default: Streams::$ADMIN_LEVEL['invite']

$DEFAULTS['attributes']

String final

Default: empty

$DEFAULTS['content']

String final

Default: empty

$DEFAULTS['icon']

String final

Default: empty

$DEFAULTS['invitedCount']

Integer final

Default: 0

$DEFAULTS['leftCount']

Integer final

Default: 0

$DEFAULTS['messageCount']

Integer final

Default: 0

$DEFAULTS['participatingCount']

Integer final

Default: 0

$DEFAULTS['readLevel']

String final

Default: Streams::$READ_LEVEL['messages']

$DEFAULTS['title']

String final

Default: empty

$DEFAULTS['type']

String final

Default: 'chat'

$DEFAULTS['writeLevel']

String final

Default: Streams::$WRITE_LEVEL['join']

Events

Streams/create/$streamType

After

Event Payload:

Streams/remove/$streamType

Before

Event Payload:

Streams/remove/$streamType

After

Event Payload:

Streams/Stream/retrieve/$streamType

Before

Event Payload:

Streams/Stream/save/$streamType

Before

Event Payload:

  • stream Streams_Stream
  • modifiedFields Array

    reference to modifiedFields array

Streams/Stream/save/$streamType

After

Event Payload: