Query Reference

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.

Return

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.

Usage

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>';
}

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' ) );

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' ) );

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' ) );

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.

Order

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