Streams Class

Extends Base_Streams

Defined in: platform/plugins/Streams/classes/Streams.php:8

Module: Streams

Static methods for the Streams models.

Index
Methods
Properties
Events

Item Index

Methods

`actionUrl`

(

$publisherId
$name
$what

)

String static

Defined in platform/plugins/Streams/classes/Streams.php:3798

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

Parameters:

$publisherId String

The name of the publisher
$name String

The name of the stream
$what String

Defaults to 'stream'. Can also be 'message', 'relation', etc.

Returns:

String:

The corresponding URL

`calculateAccess`

(

$asUserId
$publisherId
$streams
[$recalculate=false]
[$actualPublisherId=null]
[$inheritAccess=true]

)

Integer static

Defined in platform/plugins/Streams/classes/Streams.php:559

Calculates the access for one or more streams by querying the database Modifies the objects in the $streams array, setting their 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
$publisherId String

The id of the user publishing these streams
$streams Array

An array of streams, obtained for example by Streams::fetch
[$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

`close`

(

$asUserId
$publisherId
$streamName
[$options=array()]

)

static

Defined in platform/plugins/Streams/classes/Streams.php:3573

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
$publisherId String

The id of the user publishing the stream
$streamName String

The name of the stream
[$options=array()] Array optional

Can include "skipAccess"

`create`

(

$asUserId
$publisherId
[$type=null]
[$fields=array()]
[$relate=array()]
[&$result=null]

)

Streams_Stream static

Defined in platform/plugins/Streams/classes/Streams.php:870

Creates a new stream in the system

Parameters:

$asUserId String

The user who is attempting to create the stream.
$publisherId String

The id of the user to publish the stream.
[$type=null] String | Array optional

The type of the stream to create. Required unless you specify the name of the stream in the options, and you've specified its type in a config file listed under a config named "Streams/userStreams/$module".
[$fields=array()] Array optional

Use this to set additional fields for the stream:
- [title=null] String optional
  
  You can set the stream's title
- [icon=null] String optional
  
  You can set the stream's icon
- [title=null] String optional
  
  You can set the stream's content
- [attributes=null] String | Array optional
  
  You can set the stream's attributes directly as a JSON string
- [readLevel=null] String | Integer optional
  
  You can set the stream's read access level, see Streams::$READ_LEVEL
- [writeLevel=null] String | Integer optional
  
  You can set the stream's write access level, see Streams::$WRITE_LEVEL
- [adminLevel=null] String | Integer optional
  
  You can set the stream's admin access level, see Streams::$ADMIN_LEVEL
- [name=null] String optional
  
  Here you can specify an exact name for the stream to be created. Otherwise a unique one is generated automatically.
- [skipAccess=false] Boolean optional
  
  Skip all access checks when creating and relating the stream.
[$relate=array()] Array optional

Fill this out in order to relate the newly created stream to a category stream, and also inheritAccess from it. When using this option, a user may be authorized to create a stream they would otherwise not be authorized to create. This happens when the asUserId user has a writeLevel of at least "relate" in the existing category stream, and the publisherId user has a template for this stream type that is related to either the category stream, or a template for the category stream's type.
- [publisherId] String optional
  
  The id of the user publishing the category stream, defaults to $publisherId
- [streamName] String optional
  
  The name of the category stream
- [type] String optional
  
  The type of relation, defaults to ""
- [weight] String optional
  
  To set the weight for the relation. You can pass a numeric value here, or something like "max+1" to make the weight 1 greater than the current MAX(weight)
[&$result=null] Array optional

Optionally pass a reference here to hold the result of calling Streams::relate().

Returns:

Streams_Stream:

Returns the stream that was created.

`displayName`

(

$userId
$streams=null
$options=array()
[$options.short]
[$options.show]
[$options.html]
[$options.escape]
[$options.asUserId=Users::loggedInUser()]
[$options.fullAccess=false]
[$fallback='Someone']
[$fallback='Someone']

)

String | Null static

Defined in platform/plugins/Streams/classes/Streams.php:1333

Produce user's display name

Parameters:

$userId String | Users_User

Can be Users_User object or a string containing a user id
$streams=null Array

An array of streams fetched for this user. If it is null, we fetch them as the logged-in user.
$options=array() Array
[$options.short] Boolean optional

Show one part of the name only
[$options.show] Boolean optional

The parts of the name to show. Can have the letters "f", "l", "u" in any order.
[$options.html] Boolean optional

If true, encloses the first name, last name, username in span tags. If an array, then it will be used as the attributes of the html.
[$options.escape] Boolean optional

If true, does HTML escaping of the retrieved field
[$options.asUserId=Users::loggedInUser()] String optional

Optionally override which user to get the display name as
[$options.fullAccess=false] String optional

if true, sets the $asUserId = $userId
[$fallback='Someone'] String optional

HTML to return if there is no info to get displayName from.
[$fallback='Someone'] String | Null optional

What to return if there is no info to get displayName from.

Returns:

String | Null:

`experience`

(

[$experienceId='main']

)

Streams_Stream static

Defined in platform/plugins/Streams/classes/Streams.php:3709

Get a stream of type "Streams/experience" published by the community

Parameters:

[$experienceId='main'] String optional

Returns:

Streams_Stream:

`fetch`

(

$asUserId
$publisherId
$name
[$fields='*']
[$options=array()]

)

Array static

Defined in platform/plugins/Streams/classes/Streams.php:300

Fetches streams from the database.

Parameters:

$asUserId String

Set this to the user for which you are fetching the streams. If this matches the publisherId, just returns the streams. If this is '', only returns the streams anybody can see. Otherwise, return the streams joined with the calculated access settings. If you pass null here, then either the logged-in user's id or '' will be used.
$publisherId String

The id of the user publishing these streams
$name String | Array | Db_Range

The name of the stream to fetch. Can end in "/" for template streams. Also it can be an array of stream names, or a custom Db_Range for stream names
[$fields='*'] String optional

Comma delimited list of fields to retrieve in the stream. Must include at least "publisherId" and "name". since make up the primary key of the stream table.
[$options=array()] Array optional

Provide additional query options like 'limit', 'offset', 'orderBy', 'where' etc. See Db_Query_Mysql::options().
- [refetch] Boolean optional
  
  Ignore cache of previous calls to fetch, and save a new cache if necessary.
- [dontCache] Boolean optional
  
  Do not cache the results of fetching the streams
- [withParticipant=false] Boolean optional
  
  Additionally call ->set('participant', $p) on the stream objects, with the participant object corresponding to $asUserId, if any.
- [withMessageTotals] Array optional
  
  Pass an array of ($streamName => $messageTypes) here to additionally call ->set('messageTotals', $t) on the stream objects.
- [withRelatedToTotals] Array optional
  
  pass array('withRelatedFromTotals' => array($streamName => true)) for all rows pass array('withRelatedFromTotals' => array($streamName => array($relationType$, ...))) for particular rows to additionally call ->set('relatedToTotals', $t) on the stream objects.
- [withRelatedFromTotals] Array optional
  
  pass array('withRelatedFromTotals' => array($streamName => true)) for all rows pass array('withRelatedFromTotals' => array($streamName => array('relationType', ...))) for particular rows to additionally call ->set('relatedFromTotals', $t) on the stream objects.

Returns:

Array:

Returns an array of Streams_Stream objects with access info calculated specifically for $asUserId . Make sure to call the methods testReadLevel(), testWriteLevel() and testAdminLevel() on these streams before using them on the user's behalf.

`fetchOne`

(

$asUserId
$publisherId
$name
$fields='*'
$options=array()
[$options.refetch]
[$options.dontCache]
[$options.withParticipant]
[$options.withMessageTotals]
[$options.withRelatedToTotals]
[$options.withRelatedFromTotals]

)

Streams_Stream | Null static

Defined in platform/plugins/Streams/classes/Streams.php:488

Fetches one stream from the database.

Parameters:

$asUserId String

Set this to the user for which you are fetching the streams. If this matches the publisherId, just returns the streams. If this is '', only returns the streams anybody can see. Otherwise, return the streams joined with the calculated access settings. If you pass null here, then either the logged-in user's id or '' will be used.
$publisherId String

The id of the user publishing these streams
$name String | Array | Db_Range

The name of the stream to fetch. Can end in "/" for template streams. Also it can be an array of stream names, or a custom Db_Range for stream names
$fields='*' String | Boolean

Must include "publisherId" and "name" fields, since they make up the primary key of the stream table. Pass true here to throw an exception if the stream is missing.
$options=array() Array

Provide additional query options like 'limit', 'offset', 'orderBy', 'where' etc. See Db_Query_Mysql::options().
[$options.refetch] Boolean optional

Ignore cache of previous calls to fetch, and save a new cache if necessary.
[$options.dontCache] Boolean optional

Do not cache the results of fetching the streams
[$options.withParticipant] Boolean optional

Additionally call ->set('participant', $p) on the stream object, with the participant object corresponding to $asUserId, if any.
[$options.withMessageTotals] Array optional

Pass an array of arrays ($streamName => $messageTypes) here to additionally call ->set('messageTotals', $t) on the stream objects.
[$options.withRelatedToTotals] Array optional

pass array('withRelatedToTotals' => array('streamName' => true)) for all rows pass array('withRelatedToTotals' => array('streamName' => array('relationType', ...))) for particular rows to additionally call ->set('relatedToTotals', $t) on the stream objects.
[$options.withRelatedFromTotals] Array optional

pass array('withRelatedFromTotals' => array('streamName' => true)) for all rows pass array('withRelatedFromTotals' => array('streamName' => array('relationType', ...))) for particular rows to additionally call ->set('relatedFromTotals', $t) on the stream objects.

Returns:

Streams_Stream | Null:

Returns a Streams_Stream object with access info calculated specifically for $asUserId . Make sure to call the methods testReadLevel(), testWriteLevel() and testAdminLevel() on these streams before using them on the user's behalf.

`forUser`

(

$asUserId
$publisherId

)

Array static

Defined in platform/plugins/Streams/classes/Streams.php:1059

Get all the streams starting with "Streams/user/" for a particular user. This is cached via Streams:;fetch, so you can call it repeatedly.

Parameters:

$asUserId String

The id of the user who's supposed to be accessing the stream.
$publisherId String

The id of the user who is publishing the streams.

Returns:

Array:

`getRelations`

(

$asUserId
$toPublisherId
$toStreamName
$type
$fromPublisherId
$fromStreamName
$relatedTo
$relatedFrom
$categories
$streams
$options=array()
[$options.skipAccess=false]

)

private

Defined in platform/plugins/Streams/classes/Streams.php:1371

Gets relations. At most one of toStreamName, toStreamName can be an array.

Parameters:

$asUserId String

The user who is fetching
$toPublisherId String

The publisher of the category
$toStreamName String | Array

The name of the category. May be turned into an array.
$type String

The type of the relation.
$fromPublisherId String

The publisher of the member stream(s)
$fromStreamName String | Array

The name of the member stream(s). May be turned into an array.
$relatedTo Array

reference to array of Streams_RelatedTo to fill
$relatedFrom Array

reference to array of Streams_RelatedFrom to fill
$categories Array

reference to array of Streams_Stream to fill with categories
$streams Array

reference to array of Streams_Stream to fill with streams
$options=array() Array

An array of options that can include:
[$options.skipAccess=false] Boolean optional

If true, skips the access checks and just relates the stream to the category

`interests`

(

[$communityId=Users::communityId()]

)

Array static

Defined in platform/plugins/Streams/classes/Streams.php:3852

Get a structured, sorted array with all the interests in a community

Parameters:

[$communityId=Users::communityId()] String optional

the id of the community

Returns:

Array:

an array of $category => ($subcategory =>) $interest

`invite`

(

$publisherId
$streamName
$who
[$options=array()]

)

Array static

Defined in platform/plugins/Streams/classes/Streams.php:3159

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

Parameters:

$publisherId String

The id of the stream publisher
$streamName String

The name of the stream the user will be invited to
$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 such as an email or mobile number, 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).

`isAuthorizedToCreate`

(

$userId
$publisherId
$streamType
[$relate=array()]

)

Streams_Stream | Boolean static

Defined in platform/plugins/Streams/classes/Streams.php:783

Calculates whether a given user is authorized by a specific publisher to create a particular type of stream.

Parameters:

$userId String

The user who would be creating the stream.
$publisherId String

The id of the user who would be publishing the stream.
$streamType String

The type of the stream that would be created
[$relate=array()] Array optional

The user would also be authorized if the stream would be related to an existing category stream, in which the user has a writeLevel of at least "relate", and the user that would be publishing this new stream has a template for this stream type that is related to either the category stream or a template matching the category stream. To test for this, pass an array with the following keys:
- publisherId String
  
  The id of the user publishing that stream, defaults to $publisherId
- streamName String
  
  The name of the stream to which the new stream would be related
- type String
  
  The type of relation, defaults to ""

Returns:

Streams_Stream | Boolean:

Returns a stream template the user must use, otherwise a boolean true/false to indicate a yes or no regardless of template.

`join`

(

$asUserId
$publisherId
$streams
[$options=array()]

)

Array static

Defined in platform/plugins/Streams/classes/Streams.php:2424

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:

$asUserId String

The id of the user that is joining. Pass null here to use the logged-in user's id.
$publisherId String

The id of the user publishing all the streams
$streams Array

An array of Streams_Stream objects or stream names
[$options=array()] Array optional

An associative array of options.
- [subscribed] Boolean optional
  
  If true, the user is set as subscribed
- [posted] Boolean optional
  
  If true, the user is set as subscribed
- [extra] Array optional
  
  Any extra information to tree-merge for the participants
- [noVisit] Boolean optional
  
  If user is already participating, don't post a "Streams/visited" message
- [skipAccess] Boolean optional
  
  If true, skip access check for whether user can join
- [skipRelationMessages=true] Boolean optional
  
  if true, skip posting messages on the stream about being related to the Streams/participating streams of the joining user with id asUserId's

Returns:

Array:

Returns an array of (streamName => Streams_Participant) pairs. The newly inserted rows will have wasInserted() return true.

`leave`

(

$asUserId
$publisherId
$streams
[$options=array()]

)

Array static

Defined in platform/plugins/Streams/classes/Streams.php:2607

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

Parameters:

$asUserId String

The id of the user that is joining. Pass null here to use the logged-in user's id.
$publisherId String

The id of the user publishing all the streams
$streams Array

An array of Streams_Stream objects or stream names
[$options=array()] Array optional

An associative array of options.
- [extra] Array optional
  
  Any extra information to tree-merge for the participants
- [skipAccess] Boolean optional
  
  If true, skip access check for whether user can join
- [skipRelationMessages=true] Boolean optional
  
  if true, skip posting messages on the stream about being unrelated to the joining asUserId's Streams/participating streams.

Returns:

Array:

Returns an array of (streamName => Streams_Participant) pairs

`lookup`

(

$publisherId
$types
$title

)

static

Defined in platform/plugins/Streams/classes/Streams.php:3823

Look up stream by types and title filter

Parameters:

$publisherId String

The id of the publisher whose streams to look through
$types String | Array

The possible stream type, or an array of types
$title String

A string to compare titles by using SQL's "LIKE" statement

`my`

(

$field='content'
[$escape=false]

)

Mixed static

Defined in platform/plugins/Streams/classes/Streams.php:1078

A shorthand to get a stream whose name starts with "Streams/user/".

Parameters:

$field='content' String | Array

Optional. Defaults to "content". Can be an array of fields, in which case the function returns an array.
[$escape=false] Boolean optional

If true, escapes as HTML

Returns:

Mixed:

Returns the value of the field, or an array of values, depending on whether $field is an array or a string

`participating`

(

[$options.type]
[$options=array()]

)

Array static

Defined in platform/plugins/Streams/classes/Streams.php:3083

Gets the streams related by relation of type "Streams/participating" to the given category stream. Typically, these relations are added and removed when the user joins or leaves the related streams, which is done automatically by the Streams plugin with the streams named in under the config field "Streams"/"types"/$streamType/"participating", which is an array of stream names.

Parameters:

[$options.type] String | Array | Db_Range optional

Filter the type(s) of the streams to return, that the user is participating in.
[$options=array()] Array optional

options you can pass to Streams::relate() method
- [publisherId=Users::loggedInUser(true)->id] String optional
  
  the publisher of the category stream
- [categoryName='Streams/participating'] String optional
  
  the name of the category stream
- [asUserId=Users::loggedInUser(true)->id] String optional
  
  the user to fetch as

Returns:

Array:

Returns array($relations, $relatedStreams, $stream). However, if $streamName wasn't a string or ended in "/" then the third parameter is an array of streams. Also, if $options['streamsOnly'] or $options['relationsOnly'] is set, then returns only $relatedStreams or $relations.

`register`

(

$fullName
$identifier
[$icon=true]
[$options=array()]

)

Users_User static

Defined in platform/plugins/Streams/classes/Streams.php:3722

Registers a user. Can be hooked to 'Users/register' before event so it can override standard functionality. Method ensures user registration based on full name and also handles registration of invited user

Parameters:

$fullName Array | String

A string, or an array with keys
- first String
  
  The first name
- last String
  
  The last name
$identifier String | Array

Can be an email address or mobile number. Or it could be an array of $type => $info
- [identifier] String optional
  
  an email address or phone number
- [device] Array optional
  
  an array with keys "deviceId", "platform", "appId", "version", "formFactor" to store in the Users_Device table for sending notifications
- [app] Array optional
  
  an array with "platform" key, and optional "appId"
[$icon=true] Array | String | True optional

By default, the user icon is "default". But you can pass here an array of filename => url pairs, or a gravatar url to download the various sizes from gravatar. Finally, you can pass true to generate an icon instead of using the default icon. If $identifier['app']['platform'] is specified, and $icon==true, then an attempt will be made to download the icon from the user's account on the platform.
[$options=array()] Array optional

An array of options that could include:
- [activation] String optional
  
  The key under "Users"/"transactional" config to use for sending an activation message. Set to false to skip sending the activation message for some reason.

Returns:

Users_User:

`relate`

(

$asUserId
$toPublisherId
$toStreamName
$type
$fromPublisherId
$fromStreamName
$options=array()
[$options.skipAccess=false]
[$options.skipMessageTo=false]
[$options.skipMessageFrom=false]
[$options.weight]
[$options.extra]

)

Array | Boolean static

Defined in platform/plugins/Streams/classes/Streams.php:1510

Make the stream a member of category or other aggregating stream, First parameter set - where to add, Second parameter set - what to add NOTE: this currently only works when fromPublisherId and toPublisherId are on same Q cluster

Parameters:

$asUserId String

The user who is making aggreagtor operation on the stream (add stream to category)
$toPublisherId String

The user who has published the category stream
$toStreamName String | Array

The name of the category stream. Pass an array of strings to relate a single stream to multiple categories, but in that case make sure fromStreamName is a string.
$type String

The type of the relation
$fromPublisherId String

The user who has published the related stream
$fromStreamName String

The name of the related stream. Pass an array of strings to relate multiple streams to a single category, but in that case make sure toStreamName is a string.
$options=array() Array

An array of options that can include:
[$options.skipAccess=false] Boolean optional

If true, skips the access checks and just relates the stream to the category
[$options.skipMessageTo=false] Boolean optional

If true, skips posting the Streams/relatedFrom message to the "to" streams
[$options.skipMessageFrom=false] Boolean optional

If true, skips posting the Streams/relatedFrom message to the "from" streams
[$options.weight] Double | String optional

Pass a numeric value here, or something like "max+1" to make the weight 1 greater than the current MAX(weight)
[$options.extra] Array optional

Can be array of ($streamName => $extra) info to save in the "extra" field.

Returns:

Array | Boolean:

Returns false if the operation was canceled by a hook Returns true if relation was already there Otherwise returns array with keys "messagesFrom" and "messageTo" and values of type Streams_Message

`related`

(

$asUserId
$publisherId
$streamName
$isCategory=true
$options=array()
[$options.orderBy=false]
[$options.limit]
[$options.offset]
[$options.min]
[$options.max]
[$options.type]
[$options.weight]
[$options.prefix]
[$options.title]
[$options.where]
[$options.fetchOptions]
[$options.relationsOnly]
[$options.streamsOnly]
[$options.streamFields]
[$options.filter]
[$options.skipFields]
[$options.skipTypes]
[$options.includeTemplates]

)

Array static

Defined in platform/plugins/Streams/classes/Streams.php:2035

Fetch all the streams which are related to, or from, a given stream. Right now, all the streams that are fetched have to be from the same publisher. So, if there are relations to streams from other publishers, you have to additionally go ahead and fetch them yourself.

Parameters:

$asUserId String

The user who is fetching
$publisherId String

The publisher of the stream
$streamName String | Array | Db_Range

The name of the stream which is presumably related to/from other streams
$isCategory=true Mixed

If false, returns the categories that this stream is related to. If true, returns all the streams this related to this category. If a string, returns all the streams related to this category with names prefixed by this string.
$options=array() Array
[$options.orderBy=false] Boolean optional

Defaults to false, which means order by decreasing weight. True means order by increasing weight.
[$options.limit] Integer optional

number of records to fetch
[$options.offset] Integer optional

offset to start from
[$options.min] Double optional

the minimum orderBy value (inclusive) to filter by, if any
[$options.max] Double optional

the maximum orderBy value (inclusive) to filter by, if any
[$options.type] String | Array | Db_Range optional

if specified, this filters the type of the relation. Can be useful for implementing custom indexes using relations and varying the value of "type".
[$options.weight] String | Array | Db_Range optional

if specified, this filters the weight of the relation. Can be useful for implementing custom indexes using relations and varying the weight ranges. Only used if $options.isCategory is true.
[$options.prefix] String optional

if specified, this filters by the prefix of the related streams
[$options.title] String optional

if specified, this filters the titles of the streams with a LIKE condition
[$options.where] Array optional

you can also specify any extra conditions here
[$options.fetchOptions] Array optional

An array of any options to pass to Streams::fetch when fetching streams
[$options.relationsOnly] Array optional

If true, returns only the relations to/from stream, doesn't fetch the other data. Useful if publisher id of relation objects is not the same as provided by publisherId.
[$options.streamsOnly] Array optional

If true, returns only the streams related to/from stream, doesn't return the other data.
[$options.streamFields] Array optional

If specified, fetches only the fields listed here for any streams.
[$options.filter] Callable optional

Optional function to call to filter the relations. It should return a filtered array of relations.
[$options.skipFields] Array optional

Optional array of field names. If specified, skips these fields when fetching streams
[$options.skipTypes] Array optional

Optional array of ($streamName => $relationTypes) to skip when fetching relations.
[$options.includeTemplates] Array optional

Defaults to false. Pass true here to include template streams (whose name ends in a slash) among the related streams.

Returns:

Array:

Returns array($relations, $relatedStreams, $stream). However, if $streamName wasn't a string or ended in "/" then the third parameter is an array of streams. Also, if you passed "relationsOnly" or "streamsOnly", then it returns the $relations or $relatedStreams array by itself, respectively.

`relatedFromTotals`

(

$publisherId
$options

)

Array static

Defined in platform/plugins/Streams/classes/Streams.php:4140

Get info about relations FROM streams

Parameters:

$publisherId String

Stream publisher id
$options Array

Can be: array('withRelatedFromTotals' => array('streamName' => true)) for all rows array('withRelatedFromTotals' => array('streamName' => array('relationType', ...))) for particular rows

Returns:

Array:

Returns array('relationType_1' => array('fromStreamType' => relationCount), 'relationType_2' => ...)

`relatedToTotals`

(

$publisherId
$name
$options

)

Array static

Defined in platform/plugins/Streams/classes/Streams.php:4062

Get info about relations TO streams

Parameters:

$publisherId String

Stream publisher id
$name String | Array

Stream name or array of names
$options Array

Can be: array('withRelatedToTotals' => array('streamName' => true)) for all rows array('withRelatedToTotals' => array('streamName' => array('relationType', ...))) for particular rows

Returns:

Array:

Returns array('relationType_1' => array('fromStreamType' => relationCount), 'relationType_2' => ...)

`request`

(

$publisherId
$streamName
[$options=array()]

)

Streams_Request static

Defined in platform/plugins/Streams/classes/Streams.php:3472

Each user is allowed at most one request per stream. If a request already exists, then this function returns it, even if it has different parameters. Otherwise, it inserts a request for upgrading access to a stream, and schedules actions to be taken automatically if the request is granted. It also posts a "Streams/request" message to the stream, so that someone with the adminLevel >= invite and adequate readLevel, writeLevel and permissions can grant the request.

Parameters:

$publisherId String

The id of the stream publisher
$streamName String

The name of the stream the request is about
[$options=array()] Array optional

All of these are optional
- [userId=Users::loggedInUser()->id] String optional
  
  The id of the user requesting the upgraded access.
- [readLevel] String | Integer optional
  
  upgrade to read level being requested
- [writeLevel] String | Integer optional
  
  upgrade to write level being requested
- [adminLevel] String | Integer optional
  
  upgrade to admin level being requested
- [permissions] Array optional
  
  array of additional permissions to request
- [actions] Array optional
  
  array of actions to take automatically right after a request is granted, e.g. "Streams/join" or "Streams/subscribe". These can be interpreted in the "after" hook for "Streams/request" event.

Returns:

Streams_Request:

The request row that has been inserted into the database

`requestedField`

(

$field
$throwIfMissing=false
$default=null

)

String static

Defined in platform/plugins/Streams/classes/Streams.php:1271

Get the stream field from the request, if it can't be deduced throws error

Parameters:

$field String

The fiels name
$throwIfMissing=false Boolean

Optional. If true, throws an exception if the stream field cannot be deduced
$default=null Mixed

Is returned if field is not set

Returns:

String:

The value of the field

`requestedFields`

() Array | String static

Defined in platform/plugins/Streams/classes/Streams.php:1308

Get the fields that have been requested in the request, otherwise '*'

Returns:

Array | String:

An array or string of fields to select

`requestedMessageType`

(

$throwIfMissing=false

)

String static

Defined in platform/plugins/Streams/classes/Streams.php:1241

Get the message type from the request, if it can be deduced

Parameters:

$throwIfMissing=false Boolean

Optional. If true, throws an exception if the message type cannot be deduced

Returns:

String:

The type of the message

`requestedName`

(

$throwIfMissing=false
[$returnAs='string']
[$uri=Q_Dispatcher::uri()]

)

String static

Defined in platform/plugins/Streams/classes/Streams.php:1151

Get the stream name from the request, if it can be deduced. Checks $_REQUEST['streamName'], then tries $_REQUEST['name']. If both are empty, tries Q_Dispatcher::uri() and returns "{$uri->name_prefix}{$uri->name}", which is useful when the URL contains just the last part of a stream's name.

Parameters:

$throwIfMissing=false Boolean

Optional. If true, throws an exception if the stream name cannot be deduced
[$returnAs='string'] String optional

Can be "array" or "string".
[$uri=Q_Dispatcher::uri()] Array | String optional

An array or string representing a uri to use instead of the Q_Dispatcher::uri()

Returns:

String:

The name of the stream

`requestedPublisherId`

(

$throwIfMissing=false
[$uri=Q_Dispatcher::uri()]

)

Integer static

Defined in platform/plugins/Streams/classes/Streams.php:1102

Get the publisher id from the request, if it can be deduced

Parameters:

$throwIfMissing=false Boolean

Optional. If true, throws an exception if the publisher id cannot be deduced
[$uri=Q_Dispatcher::uri()] Array | String optional

An array or string representing a uri to use instead of the Q_Dispatcher::uri()

Returns:

Integer:

The id of the publisher user

`requestedType`

(

$throwIfMissing=false

)

String static

Defined in platform/plugins/Streams/classes/Streams.php:1211

Get the stream type from the request, if it can be deduced

Parameters:

$throwIfMissing=false Boolean

Optional. If true, throws an exception if the stream type cannot be deduced

Returns:

String:

The type of the stream

`splitFullName`

(

$fullName

)

Array static

Defined in platform/plugins/Streams/classes/Streams.php:3679

Get first and last name out of full name

Parameters:

$fullName String

The string representing full name

Returns:

Array:

array containing 'first' and 'last' properties

`subscribe`

(

$asUserId
$publisherId
$streams
[$options=array()]

)

Array static

Defined in platform/plugins/Streams/classes/Streams.php:2749

Subscribe to one or more streams, to start receiving notifications. Posts "Streams/subscribe" message to the streams. Also posts "Streams/subscribed" messages to user's "Streams/participating" stream. If options are not given check the subscription templates:

1. generic publisher id and generic user
2. exact publisher id and generic user
3. generic publisher id and exact user
default is to subscribe to ALL messages.
If options are supplied - skip templates and use options.

Using subscribe if subscription is already active will modify existing subscription - change type(s) or modify notifications

Parameters:

$asUserId String

The id of the user that is joining. Pass null here to use the logged-in user's id.
$publisherId String

The id of the user publishing all the streams
$streams Array

An array of Streams_Stream objects or stream names
[$options=array()] Array optional

Options for the subscribe() and join() methods
- [filter] Array optional
  
  optional array with two keys
  - [types] Array optional
    array of message types, if this is empty then subscribes to all types
  - [notifications=0] Array optional
    limit number of notifications, 0 means no limit
- [untilTime=null] Datetime optional
  
  time limit, if any for subscription
- [rule=array()] Array optional
  
  optionally override the rule for new subscriptions
  - [deliver=array('to'] Array optional
    under "to" key, named the field under Streams/rules/deliver config, which will contain the names of destinations, which can include "email", "mobile", "email+pending", "mobile+pending"
  - [readyTime] Datetime optional
    time from which user is ready to receive notifications again
  - [filter] Array optional
    optionally set a filter for the rules to add
- [skipRules=false] Boolean optional
  
  if true, do not attempt to create rules for new subscriptions
- [skipAccess=false] Boolean optional
  
  if true, skip access check for whether user can join and subscribe
- [skipMessage=false] Boolean optional
  
  if true, skip posting the "Streams/subscribe" message to the stream

Returns:

Array:

An array of Streams_Participant rows from the database.

`take`

(

$streams
$name
$readLevel
$field='content'
[$escape=false]

)

Mixed static

Defined in platform/plugins/Streams/classes/Streams.php:1014

Takes some information out of an existing set of streams

Parameters:

$streams Array
$name String
$readLevel String

Test each stream for at least this read level. If the test fails, return null in its stead.
$field='content' String | Array

Optional. Defaults to "content". Can be an array of fields, in which case the function returns an array.
[$escape=false] Boolean optional

Defaults to false. If true, escapes the values as HTML

Returns:

Mixed:

Returns the value of the field, or an array of values, depending on whether $field is an array or a string

`unrelate`

(

$asUserId
$toPublisherId
$toStreamName
$type
$fromPublisherId
$fromStreamName
$options=array()
[$options.skipAccess=false]
[$options.skipMessageTo=false]
[$options.skipMessageFrom=false]
[$options.adjustWeights=false]

)

Boolean static

Defined in platform/plugins/Streams/classes/Streams.php:1849

Remove a relation where a member stream is related to a category stream. Can only remove one relation at a time. Adjusts weights after removal.

Parameters:

$asUserId String

The user who is making unrelate operation on the stream (remove stream from category)
$toPublisherId String

The user who has published the category stream
$toStreamName String | Array

The name of the category stream. Pass an array of strings to relate a single stream to multiple categories, but in that case make sure fromStreamName is a string.
$type String

The type of the relation
$fromPublisherId String

The user who has publishes the related stream
$fromStreamName String

The name of the related stream. Pass an array of strings to relate multiple streams to a single category, but in that case make sure toStreamName is a string.
$options=array() Array

An array of options that can include:
[$options.skipAccess=false] Boolean optional

If true, skips the access checks and just unrelates the stream from the category
[$options.skipMessageTo=false] Boolean optional

If true, skips posting the Streams/unrelatedTo message to the "to" streams
[$options.skipMessageFrom=false] Boolean optional

If true, skips posting the Streams/unrelatedFrom message to the "from" streams
[$options.adjustWeights=false] Boolean optional

If true, also decrements all following relations' weights by one.

Returns:

Boolean:

Whether the relation was removed

`unsubscribe`

(

$asUserId
$publisherId
$streams
[$options=array()]

)

Array static

Defined in platform/plugins/Streams/classes/Streams.php:2978

Unsubscribe from one or more streams, to stop receiving notifications. Pooststs "Streams/unsubscribe" message to the streams. Also posts "Streams/unsubscribed" messages 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:

$asUserId String

The id of the user that is joining. Pass null here to use the logged-in user's id.
$publisherId String

The id of the user publishing all the streams
$streams Array

An array of Streams_Stream objects or stream names
[$options=array()] Array optional
- [leave=false] Boolean optional
  
  set to true to also leave the streams
- [skipAccess=false] Boolean optional
  
  if true, skip access check for whether user can join and subscribe
- [skipMessage=false] Boolean optional
  
  if true, skip posting the "Streams/unsubscribe" message to the stream

Returns:

Array:

Returns an array of Streams_Participant rows, if any were in the database.

Properties

`$ACCESS_SOURCES`

Array

Defined in platform/plugins/Streams/classes/Streams.php:244

Access sources

`$ACCESS_SOURCES['contact']`

Integer final

Defined in platform/plugins/Streams/classes/Streams.php:256

From contact

Default: 1

`$ACCESS_SOURCES['direct']`

Integer final

Defined in platform/plugins/Streams/classes/Streams.php:263

Direct access

Default: 2

`$ACCESS_SOURCES['inherited_contact']`

Integer final

Defined in platform/plugins/Streams/classes/Streams.php:277

Inherited from contact

Default: 4

`$ACCESS_SOURCES['inherited_direct']`

Integer final

Defined in platform/plugins/Streams/classes/Streams.php:284

Inherited direct access

Default: 5

`$ACCESS_SOURCES['inherited_public']`

Integer final

Defined in platform/plugins/Streams/classes/Streams.php:270

Inherited public access

Default: 3

`$ACCESS_SOURCES['public']`

Integer final

Defined in platform/plugins/Streams/classes/Streams.php:249

Public access

Default: 0

`$ADMIN_LEVEL`

Array

Defined in platform/plugins/Streams/classes/Streams.php:188

Admin levels

`$ADMIN_LEVEL['invite']`

Integer final

Defined in platform/plugins/Streams/classes/Streams.php:207

Able to create invitations for others, granting access and permissions up to what they themselves have

Default: 20

`$ADMIN_LEVEL['manage']`

Integer final

Defined in platform/plugins/Streams/classes/Streams.php:215

Can approve posts, and give people any adminLevel < 'manage'

Default: 30

`$ADMIN_LEVEL['max']`

Integer final

Defined in platform/plugins/Streams/classes/Streams.php:229

Max admin level

Default: 40

`$ADMIN_LEVEL['none']`

Integer final

Defined in platform/plugins/Streams/classes/Streams.php:193

Cannot do anything related to admin / users

Default: 0

`$ADMIN_LEVEL['own']`

Integer final

Defined in platform/plugins/Streams/classes/Streams.php:222

Can give people any adminLevel <= 'own'

Default: 40

`$ADMIN_LEVEL['tell']`

Integer final

Defined in platform/plugins/Streams/classes/Streams.php:200

Can prove things about the stream's content or participants

Default: 10

`$cache`

Array static

Defined in platform/plugins/Streams/classes/Streams.php:4224

`$dontCache`

String static

Defined in platform/plugins/Streams/classes/Streams.php:4249

You can set this to true to prevent caching for a while, e.g. during installer scripts, but make sure to set it back to false when done.

`$fetch`

Array protected static

Defined in platform/plugins/Streams/classes/Streams.php:4217

`$followedInvite`

Streams_Invite

Defined in platform/plugins/Streams/classes/Streams.php:4230

`$READ_LEVEL`

Array

Defined in platform/plugins/Streams/classes/Streams.php:21

Read levels

`$READ_LEVEL['content']`

Integer final

Defined in platform/plugins/Streams/classes/Streams.php:40

Can see the stream's content

Default: 20

`$READ_LEVEL['max']`

Integer final

Defined in platform/plugins/Streams/classes/Streams.php:68

Max read level

Default: 40

`$READ_LEVEL['messages']`

Integer final

Defined in platform/plugins/Streams/classes/Streams.php:61

Can play stream in a player

Default: 40

`$READ_LEVEL['none']`

Integer final

Defined in platform/plugins/Streams/classes/Streams.php:26

Can't see the stream

Default: 0

`$READ_LEVEL['participants']`

Integer final

Defined in platform/plugins/Streams/classes/Streams.php:54

Can see participants in the stream

Default: 30

`$READ_LEVEL['relations']`

Integer final

Defined in platform/plugins/Streams/classes/Streams.php:47

Can see relations to other streams

Default: 25

`$READ_LEVEL['see']`

Integer final

Defined in platform/plugins/Streams/classes/Streams.php:33

Can see icon and title

Default: 10

`$requestedName_override`

String static

Defined in platform/plugins/Streams/classes/Streams.php:4241

`$requestedPublisherId_override`

String static

Defined in platform/plugins/Streams/classes/Streams.php:4235

`$WRITE_LEVEL`

Array

Defined in platform/plugins/Streams/classes/Streams.php:84

Write levels

`$WRITE_LEVEL['close']`

Integer final

Defined in platform/plugins/Streams/classes/Streams.php:159

Don't delete, just prevent any new changes to stream however, joining and leaving is still ok

Default: 40

`$WRITE_LEVEL['closePending']`

Integer final

Defined in platform/plugins/Streams/classes/Streams.php:152

Can post a message requesting to close the stream

Default: 35

`$WRITE_LEVEL['edit']`

Integer final

Defined in platform/plugins/Streams/classes/Streams.php:145

Can post messages to edit stream content immediately

Default: 30

`$WRITE_LEVEL['join']`

Integer final

Defined in platform/plugins/Streams/classes/Streams.php:96

Can become a participant, chat, and leave

Default: 10

`$WRITE_LEVEL['max']`

Integer final

Defined in platform/plugins/Streams/classes/Streams.php:167

Max write level

Default: 40

`$WRITE_LEVEL['none']`

Integer final

Defined in platform/plugins/Streams/classes/Streams.php:89

Cannot affect stream or participants list

Default: 0

`$WRITE_LEVEL['post']`

Integer final

Defined in platform/plugins/Streams/classes/Streams.php:117

Can post messages which appear immediately

Default: 20

`$WRITE_LEVEL['postPending']`

Integer final

Defined in platform/plugins/Streams/classes/Streams.php:110

Can post messages, but manager must approve

Default: 15

`$WRITE_LEVEL['suggest']`

Integer final

Defined in platform/plugins/Streams/classes/Streams.php:138

Can post messages requesting edits of stream

Default: 28

`WRITE_LEVEL['relate']`

Integer final

Defined in platform/plugins/Streams/classes/Streams.php:124

Can post messages relating other streams to this one

Default: 23

`WRITE_LEVEL['relations']`

Integer final

Defined in platform/plugins/Streams/classes/Streams.php:131

Can update properties of relations directly

Default: 25

`WRITE_LEVEL['vote']`

Integer final

Defined in platform/plugins/Streams/classes/Streams.php:103

Can vote for a relation message posted to the stream.

Default: 13

Events

`Streams/fetch/$streamType`

After

Defined in platform/plugins/Streams/classes/Streams.php:467

Event Payload:

streams &array
asUserId String
publisherId String
name String
criteria Array
fields String
options Array

`Streams/invite`

After

Defined in platform/plugins/Streams/classes/Streams.php:3458

Event Payload:

success String
userIds Array
identifiers Array
identifierTypes Array
alreadyParticipating Array
invite Streams_Invite

`Streams/register`

Before

Defined in platform/plugins/Streams/classes/Streams.php:3758

Event Payload:

username String
identifier String | Array
icon String

`Streams/register`

After

Defined in platform/plugins/Streams/classes/Streams.php:3783

Event Payload:

username String
identifier String | Array
icon String
'user' Users_User

`Streams/relateFrom/$streamType`

Before

Defined in platform/plugins/Streams/classes/Streams.php:1634

Event Payload:

relatedTo Array
relatedFrom Array
asUserId String
category Streams_Stream
stream Streams_Stream

`Streams/relateFrom/$streamType`

After

Defined in platform/plugins/Streams/classes/Streams.php:1810

Event Payload:

relatedTo String
relatedFrom String
asUserId String
extra Array
category Streams_Stream
stream Streams_Stream

`Streams/relateTo/$categoryType`

After

Defined in platform/plugins/Streams/classes/Streams.php:1824

Event Payload:

relatedTo String
relatedFrom String
asUserId String
category Streams_Stream
stream Streams_Stream

`Streams/relateTo/$categoryType`

Before

Defined in platform/plugins/Streams/classes/Streams.php:1618

Event Payload:

relatedTo Array
relatedFrom Array
asUserId String
category Streams_Stream
stream Streams_Stream

`Streams/request`

After

Defined in platform/plugins/Streams/classes/Streams.php:3564

Event Payload:

request Streams_Request

`Streams/request`

Before

Defined in platform/plugins/Streams/classes/Streams.php:3549

Event Payload:

request Streams_Request

`Streams/unrelateFrom/$streamType`

Before

Defined in platform/plugins/Streams/classes/Streams.php:1931

Event Payload:

relatedTo String
relatedFrom String
asUserId String

`Streams/unrelateFrom/$streamType`

After

Defined in platform/plugins/Streams/classes/Streams.php:2008

Event Payload:

relatedTo String
relatedFrom String
asUserId String

`Streams/unrelateTo/$categoryType`

After

Defined in platform/plugins/Streams/classes/Streams.php:2020

Event Payload:

relatedTo String
relatedFrom String
asUserId String

`Streams/unrelateTo/$streamType`

Before

Defined in platform/plugins/Streams/classes/Streams.php:1916

Event Payload:

relatedTo String
relatedFrom String
asUserId String

`Streams/updateRelation/$categoryType`

After

Defined in platform/plugins/Streams/classes/Streams.php:2404

Event Payload:

relatedTo String
relatedFrom String
asUserId String
weight Double
previousWeight Double

`Streams/updateRelation/$streamType`

Before

Defined in platform/plugins/Streams/classes/Streams.php:2347

Event Payload:

relatedTo String
relatedFrom String
asUserId String
weight Double
previousWeight Double

APIs

Streams Class

Item Index

Methods

Properties

Events

Methods

actionUrl

Parameters:

Returns:

calculateAccess

Parameters:

Returns:

close

Parameters:

create

Parameters:

Returns:

displayName

Parameters:

Returns:

experience

Parameters:

Returns:

fetch

Parameters:

Returns:

fetchOne

Parameters:

Returns:

forUser

Parameters:

Returns:

getRelations

Parameters:

interests

Parameters:

Returns:

invite

Parameters:

Returns:

isAuthorizedToCreate

Parameters:

Returns:

join

Parameters:

Returns:

leave

Parameters:

Returns:

lookup

Parameters:

my

Parameters:

Returns:

participating

Parameters:

Returns:

register

Parameters:

Returns:

relate

Parameters:

Returns:

related

Parameters:

Returns:

relatedFromTotals

Parameters:

Returns:

relatedToTotals

Parameters:

Returns:

request

Parameters:

Returns:

requestedField

Parameters:

Returns:

requestedFields

`actionUrl`

`calculateAccess`

`close`

`create`

`displayName`

`experience`

`fetch`

`fetchOne`

`forUser`

`getRelations`

`interests`

`invite`

`isAuthorizedToCreate`

`join`

`leave`

`lookup`

`my`

`participating`

`register`

`relate`

`related`

`relatedFromTotals`

`relatedToTotals`

`request`

`requestedField`

`requestedFields`

`requestedMessageType`

`requestedName`

`requestedPublisherId`

`requestedType`

`splitFullName`

`subscribe`

`take`

`unrelate`

`unsubscribe`

`$ACCESS_SOURCES`

`$ACCESS_SOURCES['contact']`

`$ACCESS_SOURCES['direct']`

`$ACCESS_SOURCES['inherited_contact']`

`$ACCESS_SOURCES['inherited_direct']`

`$ACCESS_SOURCES['inherited_public']`

`$ACCESS_SOURCES['public']`

`$ADMIN_LEVEL`

`$ADMIN_LEVEL['invite']`

`$ADMIN_LEVEL['manage']`

`$ADMIN_LEVEL['max']`

`$ADMIN_LEVEL['none']`

`$ADMIN_LEVEL['own']`

`$ADMIN_LEVEL['tell']`

`$cache`

`$dontCache`

`$fetch`

`$followedInvite`

`$READ_LEVEL`

`$READ_LEVEL['content']`

`$READ_LEVEL['max']`

`$READ_LEVEL['messages']`

`$READ_LEVEL['none']`

`$READ_LEVEL['participants']`

`$READ_LEVEL['relations']`

`$READ_LEVEL['see']`

`$requestedName_override`

`$requestedPublisherId_override`

`$WRITE_LEVEL`

`$WRITE_LEVEL['close']`

`$WRITE_LEVEL['closePending']`

`$WRITE_LEVEL['edit']`

`$WRITE_LEVEL['join']`

`$WRITE_LEVEL['max']`

`$WRITE_LEVEL['none']`

`$WRITE_LEVEL['post']`

`$WRITE_LEVEL['postPending']`

`$WRITE_LEVEL['suggest']`

`WRITE_LEVEL['relate']`

`WRITE_LEVEL['relations']`

`WRITE_LEVEL['vote']`