Streams_Stream Class
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.
Item Index
Methods
- __set_state
- addPermission
- addPreloaded
- addPreloaded
- afterRemoveExcecute
- afterSaveExecute
- beforeSave
- beforeSet_permissions
- calculateAccess static
- clearAllAttributes
- clearAttribute
- close static
- displayType static
- exportArray
- extendedBy static
- getAllAttributes
- getAllPermissions
- getAttribute
- getConfigField static
- getMessages
- getParticipant
- getParticipants
- getStreamTemplate static
- getSubscriptionTemplate static
- hasPermission
- inheritAccess
- inheritAccessAdd
- inheritAccessRemove
- invite static
- isRequired
- join
- leave
- lowerAdminLevel
- numericAdminLevel static
- numericReadLevel static
- numericWriteLevel static
- post
- post
- publishedByFetcher
- register static
- related static
- removePermission
- restrictedFromClient static
- setAttribute
- setUp
- testAdminLevel
- testPermission
- testReadLevel
- testWriteLevel
- unsubscribe
Properties
- $DEFAULTS static
- $preloaded static
- $publishedByFetcher
- $rows
Attributes
Methods
__set_state
-
$array
Implements the __set_state method, so it can work with with var_export and be re-imported successfully.
Parameters:
-
$array
Array
Returns:
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
StringThe 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
beforeSave
-
$modifiedFields
Does necessary preparations for saving a stream in the database.
Parameters:
-
$modifiedFields
ArrayThe array of fields
Returns:
beforeSet_permissions
-
$value
Method is called before setting the field and verifies that, if it is a string, it contains a JSON array.
Parameters:
-
$value
String
Returns:
An array of field name and value
calculateAccess
-
$asUserId
-
[$recalculate=false]
-
[$actualPublisherId=null]
-
[$inheritAccess=true]
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
StringSet 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 optionalPass true here to force recalculating access to streams for which access was already calculated
-
[$actualPublisherId=null]
String optionalFor internal use only. Used by Streams::isAuthorizedToCreate function.
-
[$inheritAccess=true]
String optionalSet to false to skip inheriting access from other streams, even if specified
Returns:
The number of streams that were recalculated
clearAllAttributes
()
clearAttribute
-
$attributeName
Parameters:
-
$attributeName
StringThe name of the attribute to remove
close
-
$asUserId
-
[$options=array()]
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
StringThe id of the user who would be closing the stream
-
[$options=array()]
Array optionalCan include "skipAccess"
displayType
()
String
static
Returns the type name to display from a stream type
Returns:
exportArray
-
$options=array()
-
[$options.asUserId]
-
[$options.skipAccess=false]
-
[$options.fields=null]
Returns the fields and values we can export to clients. Can also contain "messageTotals", "relatedToTotals" and "relatedFromTotals".
Parameters:
-
$options=array()
Array -
[$options.asUserId]
String optionalDefaults 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 optionalIf true, skips access checks
-
[$options.fields=null]
Array optionalBy 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:
extendedBy
-
$row
Gets the stream row corresponding to a Db_Row retrieved from a table extending the stream.
Parameters:
-
$row
Db_Rowa Db_Row retrieved from a table extending the stream.
Returns:
Streams_Stream|null
getAllAttributes
()
Array
Returns:
The array of all attributes set in the stream
getAllPermissions
()
Array
Returns:
getAttribute
-
$attributeName
-
$default
Parameters:
-
$attributeName
StringThe name of the attribute to get
-
$default
MixedThe value to return if the attribute is missing
Returns:
The value of the attribute, or the default value, or null
getConfigField
-
$type
-
$field
-
[$default=null]
-
[$merge=true]
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
StringThe type of the stream
-
$field
String | ArrayThe name of the field
-
[$default=null]
Mixed optionalThe value to return if the config field isn't specified
-
[$merge=true]
Boolean optionalif 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 optionalAn array of options determining how messages will be fetched, which can include:
-
[skipLimiting=false]
Boolean optionalPass 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 optionalMinimum ordinal of the message to select from (inclusive). Defaults to minimum ordinal of existing messages (if any).
-
[options.max]
Integer optionalMaximum 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 optionalNumber of the messages to be selected.
-
[options.ascending]
Integer optionalSorting 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 optionalOptional string specifying the particular type of messages to get
getParticipant
-
[$userId=Users::loggedInUser(true)->id]
Fetch a particular participant in the stream, if it exists.
Parameters:
-
[$userId=Users::loggedInUser(true)->id]
String optionalThe id of the user who may or may not be participating in the stream
Returns:
getParticipants
-
[$options=array()]
Fetch participants of the stream.
Parameters:
-
[$options=array()]
Array optionalAn array of options determining how messages will be fetched, which can include:
-
[state]
String optionalOne of "invited", "participating", "left"
-
[limit=1000]
String optionalNumber of the participants to be selected.
-
[offset=0]
String optionalNumber of the messages to be selected.
-
[ascending]
String optionalSorting of fetched participants by insertedTime. If true, sorting is ascending, if false - descending. Defaults to false.
-
[type]
String optionalOptional string specifying the particular type of messages to get
-
[skipLimiting=false]
Boolean optionalPass 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]
Parameters:
-
$publisherId
StringThe publisher of the stream
-
$streamType
StringThe type of the stream
-
$className
StringThe class extending Db_Row to fetch from the database
-
[$templateType=null]
&integer optionalGets filled with the template type 0-4. Set to true to return all templates.
Returns:
Returns the template stream, or an array if $templateType is true
getSubscriptionTemplate
-
$publisherId
-
$streamType
-
$className
-
$ofUserId
-
[$templateType=null]
Parameters:
-
$publisherId
StringThe publisher of the stream
-
$streamType
StringThe type of the stream
-
$className
StringThe class extending Db_Row to fetch from the database
-
$ofUserId
StringThe id of the possible subscriber
-
[$templateType=null]
&integer optionalGets filled with the template type 0-4. Set to true to return all templates.
Returns:
Returns the template subscription, or an array if $templateType is true
hasPermission
-
$permission
Parameters:
-
$permission
String
Returns:
inheritAccess
()
Boolean
Inherits access from any streams specified in the inheritAccess field.
Returns:
Returns whether the access potentially changed.
inheritAccessAdd
-
[$publisherId]
-
[$streamName]
Inherit access from a specific stream. Pushes it onto the stack.
Parameters:
-
[$publisherId]
String optionalPublisher id of the stream from which to inherit access
-
[$streamName]
String optionalName of the stream from which to inherit access
Returns:
Whether it was already there before
inheritAccessRemove
-
[$publisherId]
-
[$streamName]
Stop inheriting access from a specific stream. Splices it from the stack.
Parameters:
-
[$publisherId]
String optionalPublisher id of the stream from which to stop inheriting access
-
[$streamName]
String optionalName of the stream from which to stop inheriting access
Returns:
Whether it was already there before
invite
-
$who
-
[$options=array()]
Invites a user (or a future user) to this stream
Parameters:
-
$who
ArrayArray that can contain the following keys:
-
[userId]
String | Array optionaluser id or an array of user ids
-
[platform]
String optionalplatform for which uids are passed
-
[uid]
String | Array optionalplatform uid or array of uids
-
[label]
String | Array optionallabel or an array of labels, or tab-delimited string
-
[identifier]
String | Array optionalidentifier or an array of identifiers, or tab-delimited string
-
[newFutureUsers]
Integer optionalthe 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 optionalpass 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 optionallabel or an array of ($label => array($title, $icon)) for adding publisher's contacts
-
[addMyLabel]
String | Array optionallabel or an array of ($label => array($title, $icon)) for adding asUserId's contacts
-
[readLevel]
String | Integer optionalthe read level to grant those who are invited
-
[writeLevel]
String | Integer optionalthe write level to grant those who are invited
-
[adminLevel]
String | Integer optionalthe admin level to grant those who are invited
-
[permissions]
Array optionalarray of additional permissions to grant
-
[displayName]
String optionalthe display name to use to represent the inviting user
-
[appUrl]
String optionalCan be used to override the URL to which the invited user will be redirected and receive "Q.Streams.token" in the querystring.
-
[html]
Array optionalan 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 optionalInvite as this user id, defaults to logged-in user
-
[skipAccess]
Boolean optionalwhether to skip access checks when adding labels and contacts
-
Returns:
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:
join
-
$options=array()
-
[$options.subscribed]
-
[$options.posted]
-
[$options.extra]
-
[$options.userId]
-
[$options.noVisit]
-
[$options.skipAccess]
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()
ArrayAn associative array of options.
-
[$options.subscribed]
Boolean optionalIf true, the user is set as subscribed
-
[$options.posted]
Boolean optionalIf true, the user is set as subscribed
-
[$options.extra]
Array optionalAny extra information to tree-merge for the participant
-
[$options.userId]
String optionalThe user who is joining the stream. Defaults to the logged-in user.
-
[$options.noVisit]
Boolean optionalIf user is already participating, don't post a "Streams/visited" message
-
[$options.skipAccess]
Boolean optionalIf true, skip access check for whether user can join
Returns:
leave
-
$options=array()
-
[$options.userId]
-
[$options.extra]
-
[$options.skipAccess]
-
$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()
ArrayAn associative array of options.
-
[$options.userId]
String optionalThe user who is leaving the stream. Defaults to the logged-in user.
-
[$options.extra]
Array optionalAny extra information to tree-merge for the participant
-
[$options.skipAccess]
String optionalIf true, skip access check for whether user can join
-
$participant=null
ReferenceOptional 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
Parameters:
-
$level
Integer | String
Returns:
integer
numericReadLevel
-
$level
Parameters:
-
$level
Integer | String
Returns:
integer
numericWriteLevel
-
$level
Parameters:
-
$level
Integer | String
Returns:
integer
post
-
[$asUserId=null]
-
[$messageType='Streams/changed']
-
[$fieldNames=null]
Take actions to reflect the stream has changed: save it and post a message.
Parameters:
-
[$asUserId=null]
String optionalThe user to post as. Defaults to the logged-in user.
-
[$messageType='Streams/changed']
String optionalThe type of the message.
-
[$fieldNames=null]
Array optionalThe names of the fields to check for changes. By default, checks all the standard stream fields.
Returns:
The array of results - successfully posted messages or false if post failed
post
-
$asUserId
-
$message
-
$skipAccess=false
-
$options=array()
Post a message to stream
Parameters:
-
$asUserId
StringThe user to post as
-
$message
ArrayThe 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
BooleamIf true, skips the access checks and just posts the message.
-
$options=array()
Array
Returns:
The array of results - successfully posted messages or false if post failed
publishedByFetcher
-
$new_value=null
Checks or sets wheather stream was published by fetcher
Parameters:
-
$new_value=null
BooleanOptional. The value to set
Returns:
register
-
$what
A convenience method to get the URL of the streams-related action
Parameters:
-
$what
StringDefaults to 'stream'. In the future, can be 'message', 'relation', etc.
Returns:
The corresponding URL
removePermission
-
$permission
Parameters:
-
$permission
String
restrictedFromClient
-
$streamType
-
$fieldName
-
[$whenCreating=false]
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:
setAttribute
-
$attributeName
-
$value
Parameters:
-
$attributeName
String | ArrayThe name of the attribute to set, or an array of $attributeName => $attributeValue pairs
-
$value
MixedThe 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
Verifies whether the user has at least a certain admin level in the Stream
Parameters:
-
$level
String | IntegerString describing the level (see Streams::$ADMIN_LEVEL) or integer
Returns:
testPermission
-
$permission
Verifies whether the user has at least the given permission
Parameters:
-
$permission
String | ArrayThe name of the permission
Returns:
testReadLevel
-
$level
Verifies whether the user has at least a certain read level for the Stream
Parameters:
-
$level
String | IntegerString describing the level (see Streams::$READ_LEVEL) or integer
Returns:
testWriteLevel
-
$level
Verifies whether the user has at least a certain write level for the Stream
Parameters:
-
$level
String | IntegerString describing the level (see Streams::$WRITE_LEVEL) or integer
Returns:
unsubscribe
-
$options=array()
-
[$options.leave]
-
[$options.userId]
-
[$options.skipAccess]
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 optionalset to true to also leave the streams
-
[$options.userId]
Boolean optionalthe user who is unsubscribing from the stream. Defaults to the logged-in user.
-
[$options.skipAccess]
Boolean optionalif true, skip access check for whether user can join and subscribe
Returns:
Properties
$DEFAULTS
Array
static
Defaults for stream
$preloaded
Array
static
$publishedByFetcher
Boolean
protected
Whether stream was published by fetcher
$rows
Array
Any fetched database rows that extend the stream
Attributes
Events
Streams/Stream/save/$streamType
Before
Event Payload:
-
stream
Streams_Stream -
modifiedFields
Arrayreference to modifiedFields array