Query Reference - xwp/stream GitHub Wiki

The below documentation is outdated and will not work. For correct and working instructions to edit stream query, look at this issue: Query Reference documentation Wrong

Description

WP_Stream_Query is a class defined in classes/class-wp-stream-query.php and in many ways is similar to WP_Query except it deals only with fetching activity records from WP Stream, not WordPress content.

Usage

Return Values

The Stream query will return an array of record objects.

Each record object contains these fields:

ID (string) - The record UUID.
created (string) - The datetime string of when the record was created.
site_id (int) - The network site ID.
blog_id (int) - The blog ID on the network.
object_id (int) - ID of the object the record pertains to.
author (int) - The user ID of the record author.
author_role (string) - The user role of the record author.
summary (string) - A summary of the record activity.
connector (string) - The connector associated with the record.
context (string) - The context associated with the record.
action (string) - The action associated with the record.
ip (string) - The IP address of the record author.
author_meta (object) - An object of strings containing additional author fields.
stream_meta (object) - An object of strings containing additional record fields.

Loop

You can use the wp_stream_query() helper function to query a custom set of records. This function accepts one argument, an array of query parameters.

After you have queried a set of results, you can access the data of each record using a basic foreach loop.

Example:

$args = array(
	'records_per_page' => 50,
	'author'           => 1,
	'date_after'       => '2015-01-01',
);
$records = wp_stream_query( $args );

foreach ( $records as $record ) {
	echo $record->summary . '<br>';
}

The above example will get the last 50 records that authored by user ID 1 after January 1st, 2015 and print each summary on a new line.

WP-CLI Command

See the WP-CLI Command wiki for instructions on how to query records via the command line.

Query Parameters

Author

Get records associated with certain authors.

author (int) - A user ID.
author__in (array) - An array of user IDs.
author__not_in (array) - An array of user IDs.
author_role (string) - A user role name (not the label).
author_role__in (array) - An array of user role names.
author_role__not_in (array) - An array of user role names.

Get records for one author

$records = wp_stream_query( array( 'author' => 1 ) );

Get records for multiple authors

$records = wp_stream_query( array( 'author__in' => array( 1, 2, 3 ) ) );

Get records excluding certain authors

$records = wp_stream_query( array( 'author__not_in' => array( 4, 5, 6 ) ) );

Get records from authors belonging to a certain role

$records = wp_stream_query( array( 'author_role' => 'editor' ) );

Get records from authors belonging to certain roles

$records = wp_stream_query( array( 'author_role__in' => array( 'administrator', 'editor' ) ) );

Get records from authors not belonging to certain roles

$records = wp_stream_query( array( 'author_role__not_in' => array( 'contributor', 'subscriber' ) ) );

Date

date (string) - A datetime string in Y-m-d format.
date_from (string) - A datetime string in Y-m-d format.
date_to (string) - A datetime string in Y-m-d format.
date_after (string) - A datetime string in Y-m-d or c formats.
date_before (string) - A datetime string in Y-m-d or c formats.

Read more about Date Formatting in the PHP docs.

Get records from a specific date

$records = wp_stream_query( array( 'date' => '2015-01-22' ) );

Get records from a specific date range

$records = wp_stream_query( array( 'date_from' => '2015-01-01', 'date_to' => '2015-01-31' ) );

Get records after a specific datetime

$records = wp_stream_query( array( 'date_after' => '2015-01-01T19:30:00+00:00' ) );

Get records before a specific date

$records = wp_stream_query( array( 'date_before' => '2015-01-31' ) );

IP Address

Get records associated with certain IP addresses.

ip (string) - An IP address.
ip__in (array) - An array of IP addresses.
ip__not_in (array) - An array of IP addresses.

Get records that came from an IP address

$records = wp_stream_query( array( 'ip' => '192.168.0.1' ) );

Get records that came from certain IP addresses

$records = wp_stream_query( array( 'ip__in' => array( '192.168.0.1', '127.0.0.1' ) ) );

Get records that did not come from certain IP addresses

$records = wp_stream_query( array( 'ip__not_in' => array( '192.168.0.2', '127.0.0.2' ) ) );

Connector

Get records associated with certain connectors.

connector (string) - A connectors name.
connector__in (array) - An array of connector names.
connector__not_in (array) - An array of connector names.

Get records of a specific connector

$records = wp_stream_query( array( 'connector' => 'widgets' ) );

Get records of multiple connectors

$records = wp_stream_query( array( 'connector__in' => array( 'widgets', 'posts', 'users' ) ) );

Get records not of certain connectors

$records = wp_stream_query( array( 'connector__not_in' => array( 'menus', 'installer' ) ) );

Context

Get records associated with certain contexts.

context (string) - A context name.
context__in (array) - An array of context names.
context__not_in (array) - An array of context names.

Get records of a specific context

$records = wp_stream_query( array( 'context' => 'sidebar-1' ) );

Get records of multiple contexts

$records = wp_stream_query( array( 'context__in' => array( 'plugins', 'sessions', 'post' ) ) );

Get records not of certain contexts

$records = wp_stream_query( array( 'context__not_in' => array( 'page', 'themes' ) ) );

Action

Get records associated with certain actions.

action (string) - An action name.
action__in (array) - An array of action names.
action__not_in (array) - An array of action names.

Get records of a specific action

$records = wp_stream_query( array( 'action' => 'updated' ) );

Get records of multiple actions

$records = wp_stream_query( array( 'action__in' => array( 'created', 'trashed', 'deactivated' ) ) );

Get records not of certain actions

$records = wp_stream_query( array( 'action__not_in' => array( 'login', 'logout', 'sorted' ) ) );

Search

search (string) - A search word or phrase.
search_field (string) - Which field should be searched. Defaults to summary.

Get records that have these words in the summary

$records = wp_stream_query( array( 'search' => 'plugin deactivated' ) );

Records

record (string) - A record UUID.
record__in (array) - An array or record UUIDs.
record__not_in (array) - An array or record UUIDs.

Pagination

records_per_page (int) - The number of records to display on each page. Defaults to the posts_per_page setting in WordPress.
paged (int) - Which page number to show results for. Defaults to 1.

Get the latest 25 records

$records = wp_stream_query( array( 'records_per_page' => 25 ) );

Order

order (string) - The direction in which to order the records. Defaults to desc.
orderby (string) - What field to order the records by. Defaults to date.

Get the latest records ordered by connector

$records = wp_stream_query( array( 'orderby' => 'connector', 'order' => 'asc' ) );

Get the latest records ordered by author role

$records = wp_stream_query( array( 'orderby' => 'author_role', 'order' => 'asc' ) );

Fields

fields (array) - An array of field names.

Use the fields parameter to return only the portions of the record that you are interested in. All other fields will not be included in the results.

This can improve the performance of your query and page load time when you only need a few pieces of data from a record and not the entire record itself.

It's also important to note that these fields will appear in the record object in the same order that you place them in the query.

Get the created date of the latest records

$records = wp_stream_query( array( 'fields' => array( 'created' ) ) );

Get the summary, created date and author ID of the latest 25 records

$records = wp_stream_query( array( 'records_per_page' => 25, 'fields' => array( 'summary', 'created', 'author' ) ) );