WP Report Studio — developer guide

How to extend WP Report Studio from your own plugin, theme or mu-plugin without modifying it: add data sources and columns, react to report activity, and tune behaviour. Everything here is an ordinary WordPress hook or a small PHP contract.

A complete, working example plugin is reproduced in Example extension. It is also available as an installable zip (wrs-example-extension.zip) from the Developers page of the WP Report Studio website.

Compatibility policy

Anything not listed in this guide (classes, methods, option names, table layouts, AJAX actions, JavaScript globals) is internal and can change in any release.

Every hook name starts with vrb_. All PHP API is available after plugins_loaded.

Lifecycle actions (Beta)

Fired after the outcome is final, so a listener can record or react but can’t veto. Use filters to change behaviour. Several of these run from WP-Cron or WP-CLI, so don’t assume a browser request or a logged-in user. If a listener throws, WP Report Studio catches and logs it (Report Studio → Diagnostics), the download or job carries on, and listeners after it on that action don’t run. Keep listeners fast; push slow work (HTTP calls) to a background job.

add_action( 'vrb_schedule_failed', function ( $report_id, $schedule, $error ) {
	wp_mail( get_option( 'admin_email' ), 'Scheduled report failed',
		get_the_title( $report_id ) . ': ' . $error->get_error_message() );
}, 10, 3 );

Filters (Stable)

Data and discovery

Limits and caching

Exports

Permissions and bulk actions

Tuning

Internal (not supported)

Extension contracts

Virtual columns

A virtual provider adds fields whose values come from SQL you supply. They appear in the field tree, and sort, filter, total and export like any other field. Providers are classes with four static methods, registered by class name through vrb_virtual_providers:

This SQL is compiled into the report query as trusted code. Build it only from constants and $wpdb->prefix; never interpolate request data or field values. Filters a user applies to the column are escaped by WP Report Studio.

Field sources

To integrate a custom-fields plugin (the way ACF, Meta Box and Pods are supported), implement VRB_Field_Source and add an instance through vrb_field_sources:

interface VRB_Field_Source {
	public function id();         // 'my-fields'
	public function is_active();  // true only when your plugin is loaded
	public function discover( $post_type, array &$tree, array &$claimed_keys, array &$repeater_roots );
}

discover() appends field nodes for $post_type to $tree, marks the meta keys it owns in $claimed_keys (key => true) so the raw postmeta scan doesn’t list them twice, and lists repeater root keys in $repeater_roots. Postmeta-stored fields need no query code. Data in a custom table or join table is described with a storage descriptor; follow includes/class-source-pods.php, the reference implementation for both. Field sources are Stable as an interface; the storage descriptor shape is Beta.

Field nodes

A field node is an array:

Capabilities

Access is controlled by five capabilities (constants on VRB_Capabilities): vrb_view_reports (VIEW), vrb_edit_reports (EDIT), vrb_export_reports (EXPORT), vrb_run_bulk_actions (BULK), vrb_manage_schedules (SCHEDULE). Grant them to custom roles with add_cap(). By default edit_posts implies all five; turn that off with vrb_grant_caps_via_edit_posts.

Custom bulk actions

Not yet a supported API. The built-in actions use an internal registry whose snapshot/undo contract is still changing; if you need one, tell us what it should do.

Example extension

The example adds an “Approved comments” column to every post type, records lifecycle activity (inspect it with wp wrs-example activity), and includes scheduled posts in reports.

<?php
/**
 * Plugin Name: WP Report Studio — Example Extension
 * Requires Plugins: wp-report-studio
 */

class WRS_Example_Comment_Count_Provider {
	public static function is_available() {
		return true;
	}

	public static function fields( $post_type ) {
		return array(
			array(
				'type'      => 'virtual',
				'provider'  => __CLASS__,
				'key'       => 'approved_comments',
				'label'     => 'Approved comments',
				'data_type' => 'number',
			),
		);
	}

	public static function sql_join( $field_key ) {
		return '';
	}

	public static function sql_expr( $field_key ) {
		global $wpdb;
		return "(SELECT COUNT(*) FROM {$wpdb->comments} wrs_c WHERE wrs_c.comment_post_ID = p_root.ID AND wrs_c.comment_approved = '1')";
	}
}

add_filter( 'vrb_virtual_providers', function ( $providers ) {
	$providers[] = 'WRS_Example_Comment_Count_Provider';
	return $providers;
} );

add_action( 'vrb_export_completed', function ( $report_id, $format, $rows, $context ) {
	error_log( sprintf( 'Report %d exported: %d rows as %s (%s)', $report_id, $rows, $format, $context['destination'] ) );
}, 10, 4 );

add_filter( 'vrb_query_post_statuses', function ( $statuses ) {
	$statuses[] = 'future';
	return array_unique( $statuses );
} );

Testing your integration

• Run your listener against real activity: open a report, export it, and check the action fired (the example’s wp wrs-example activity shows how).
• Assert on hook arguments in your own tests with did_action() or a recording listener; argument shapes are documented above.
• A WordPress Playground blueprint is the quickest disposable test site. WP Report Studio’s own SQLite parity harness (tests/playground/ in the source) shows the pattern.

Reporting gaps

If you need a hook that isn’t here, or an argument you can’t get, open a support request describing the integration. Lifecycle actions are Beta precisely so they can change in response.