PHPackages                             arraypress/wp-register-reports - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. arraypress/wp-register-reports

ActiveLibrary[Utility & Helpers](/categories/utility)

arraypress/wp-register-reports
==============================

WordPress library for registering report pages with charts, tiles, tables, and CSV export functionality.

15PHP

Since Feb 5Pushed 4mo agoCompare

[ Source](https://github.com/arraypress/wp-register-reports)[ Packagist](https://packagist.org/packages/arraypress/wp-register-reports)[ RSS](/packages/arraypress-wp-register-reports/feed)WikiDiscussions main Synced today

READMEChangelogDependenciesVersions (1)Used By (0)

WordPress Reports Registration Library
======================================

[](#wordpress-reports-registration-library)

A comprehensive WordPress library for creating beautiful, feature-rich admin report pages with tiles, charts, tables, and CSV exports.

Features
--------

[](#features)

- **Tiles** - Display key metrics with icons, colors, and auto-calculated comparison percentages
- **Charts** - Line, bar, pie, doughnut charts powered by Chart.js
- **Tables** - Sortable, paginated tables with row actions (edit, view, delete)
- **Exports** - Batched CSV exports with filters and progress tracking
- **Tab Filters** - Per-tab filters (dropdowns, checkboxes) that affect all components
- **Date Picker** - Preset ranges (Today, This Week, This Month, etc.) or custom dates
- **AJAX Refresh** - Manual refresh button or auto-refresh at configurable intervals
- **Modern Header** - Full-width header with optional logo, refresh controls, and date picker

Requirements
------------

[](#requirements)

- PHP 7.4+
- WordPress 5.8+

Installation
------------

[](#installation)

```
composer require arraypress/wp-register-reports
```

Quick Start
-----------

[](#quick-start)

```
register_reports( 'my-analytics', [
	'page_title'   => 'Analytics Dashboard',
	'menu_title'   => 'Analytics',
	'parent_slug'  => 'tools.php',
	'show_refresh' => true,

	'tabs' => [
		'overview' => [
			'label' => 'Overview',
			'icon'  => 'dashicons-dashboard',
		],
		'sales'    => [
			'label'   => 'Sales',
			'icon'    => 'dashicons-cart',
			'filters' => [
				'status' => [
					'type'    => 'select',
					'label'   => 'Status',
					'options' => [
						''          => 'All',
						'completed' => 'Completed',
						'pending'   => 'Pending',
					],
				],
			],
		],
	],

	'components' => [
		'revenue' => [
			'type'          => 'tile',
			'title'         => 'Total Revenue',
			'tab'           => 'overview',
			'icon'          => 'money-alt',
			'icon_color'    => 'green',
			'value_format'  => 'currency',
			'data_callback' => 'my_get_revenue',
		],

		'revenue_chart' => [
			'type'          => 'chart',
			'title'         => 'Revenue Trend',
			'tab'           => 'overview',
			'chart_type'    => 'line',
			'height'        => 300,
			'data_callback' => 'my_get_revenue_chart',
		],
	],
] );

// Tile callback - return value and previous_value for auto-calculated change %
function my_get_revenue( array $date_range, array $config ): array {
	return [
		'value'          => 150000,  // In cents for currency
		'previous_value' => 120000,  // Auto-calculates +25% change
	];
}

// Chart callback
function my_get_revenue_chart( array $date_range, array $config ): array {
	return [
		'labels'   => [ 'Jan', 'Feb', 'Mar', 'Apr', 'May' ],
		'datasets' => [
			[
				'label' => 'Revenue',
				'data'  => [ 1200, 1900, 3000, 5000, 4000 ],
			],
		],
	];
}
```

Configuration Options
---------------------

[](#configuration-options)

### Report-Level Options

[](#report-level-options)

```
register_reports( 'my-reports', [
	// Basic
	'page_title'       => 'My Reports',
	'menu_title'       => 'Reports',
	'menu_slug'        => 'my-reports',
	'capability'       => 'manage_options',
	'parent_slug'      => '',                // Empty = top-level menu
	'icon'             => 'dashicons-chart-area',
	'position'         => null,

	// Header
	'show_title'       => true,
	'header_title'     => '',                // Override page_title in header
	'logo'             => '',                // URL to logo image

	// Features
	'show_tabs'        => true,
	'show_date_picker' => true,
	'show_refresh'     => true,              // Manual refresh button
	'auto_refresh'     => 0,                 // Seconds between auto-refresh (0 = disabled)

	// Exports
	'exports_columns'  => 4,                 // Number of export cards per row

	// Date presets
	'date_presets'     => [
		'today'      => 'Today',
		'yesterday'  => 'Yesterday',
		'this_week'  => 'This Week',
		'this_month' => 'This Month',
		'custom'     => 'Custom Range',
	],
	'default_preset'   => 'this_month',

	// Help screen
	'help_tabs'        => [
		'overview' => [
			'title'   => 'Overview',
			'content' => 'Help content here...',
		],
	],

	// Data
	'tabs'             => [],
	'components'       => [],
	'exports'          => [],
] );
```

### Tab Options with Filters

[](#tab-options-with-filters)

Tabs can have filters that appear in a bar below the tabs. Filter values are passed to all component callbacks via `$date_range['filters']`.

```
'tabs' => [
	'overview'  => [
		'label' => 'Overview',
		'icon'  => 'dashicons-dashboard',
	],
	'sales'     => [
		'label'           => 'Sales',
		'icon'            => 'dashicons-chart-bar',
		'filters'         => [
			'category'    => [
				'type'    => 'select',
				'label'   => 'Category',
				'default' => '',
				'options' => [
					''            => 'All Categories',
					'electronics' => 'Electronics',
					'clothing'    => 'Clothing',
				],
			],
			'status'      => [
				'type'    => 'select',
				'label'   => 'Status',
				'options' => [
					''          => 'All',
					'completed' => 'Completed',
					'pending'   => 'Pending',
				],
			],
			'exclude_tax' => [
				'type'  => 'checkbox',
				'label' => 'Exclude Tax',
			],
		],
		'exports_columns' => 3,  // Override exports columns for this tab
	],
	'customers' => [
		'label'   => 'Customers',
		'icon'    => 'dashicons-groups',
		'filters' => [
			'country' => [
				'type'    => 'select',
				'label'   => 'Country',
				'options' => [
					''   => 'All Countries',
					'US' => 'United States',
					'UK' => 'United Kingdom',
				],
			],
			'type'    => [
				'type'    => 'select',
				'label'   => 'Type',
				'options' => [
					''          => 'All',
					'new'       => 'New Customers',
					'returning' => 'Returning',
				],
			],
		],
	],
],
```

**Filter Types:**

- `select` - Dropdown with options
- `checkbox` - Toggle checkbox
- `text` - Text input with optional placeholder

**Accessing Filters in Callbacks:**

```
function my_callback( array $date_range, array $config ): array {
	$filters  = $date_range['filters'] ?? [];
	$category = $filters['category'] ?? '';
	$status   = $filters['status'] ?? '';

	// Adjust query based on filters...

	return [ 'value' => $result ];
}
```

### Tile Component

[](#tile-component)

```
'my_tile' => [
	'type'          => 'tile',
	'title'         => 'Total Users',
	'tab'           => 'overview',
	'icon'          => 'admin-users',      // Shorthand or 'dashicons-admin-users'
	'icon_color'    => 'blue',             // blue, green, red, orange, purple, gray
	'value_format'  => 'number',           // number, currency, percentage, decimal, text
	'currency'      => 'USD',              // For currency format
	'data_callback' => 'my_callback',
],
```

**Tile Callback - Auto-calculated change:**

```
function my_callback( array $date_range, array $config ): array {
	return [
		'value'          => 1500,
		'previous_value' => 1200,  // Auto-calculates +25% up
	];
}
```

**Tile Callback - Manual change:**

```
function my_callback( array $date_range, array $config ): array {
	return [
		'value'            => 1500,
		'change'           => 25,        // Percentage
		'change_direction' => 'up',      // 'up', 'down', 'neutral'
	];
}
```

### Tiles Group Component

[](#tiles-group-component)

Group multiple tiles with a shared title:

```
'key_metrics' => [
	'type'    => 'tiles_group',
	'title'   => 'Key Metrics',
	'tab'     => 'overview',
	'columns' => 4,  // 2, 3, or 4
	'tiles'   => [
		'users'   => [
			'title'         => 'Total Users',
			'icon'          => 'admin-users',
			'icon_color'    => 'blue',
			'value_format'  => 'number',
			'data_callback' => 'get_total_users',
		],
		'revenue' => [
			'title'         => 'Revenue',
			'icon'          => 'money-alt',
			'icon_color'    => 'green',
			'value_format'  => 'currency',
			'currency'      => 'GBP',
			'data_callback' => 'get_revenue',
		],
	],
],
```

### Chart Component

[](#chart-component)

```
'my_chart' => [
	'type'          => 'chart',
	'title'         => 'Sales Over Time',
	'tab'           => 'overview',
	'chart_type'    => 'line',   // line, bar, pie, doughnut
	'height'        => 300,
	'stacked'       => false,    // For bar charts
	'data_callback' => 'my_chart_callback',
],
```

**Chart Callback:**

```
function my_chart_callback( array $date_range, array $config ): array {
	return [
		'labels'   => [ 'Jan', 'Feb', 'Mar' ],
		'datasets' => [
			[
				'label' => 'Sales',
				'data'  => [ 100, 200, 150 ],
			],
			[
				'label' => 'Returns',
				'data'  => [ 10, 15, 8 ],
			],
		],
	];
}
```

### Table Component with Row Actions

[](#table-component-with-row-actions)

```
'my_table' => [
	'type'          => 'table',
	'title'         => 'Recent Orders',
	'tab'           => 'overview',
	'sortable'      => true,
	'paginated'     => true,
	'per_page'      => 10,
	'columns'       => [
		'id'       => 'Order ID',
		'customer' => 'Customer',
		'total'    => [
			'label'  => 'Total',
			'format' => 'currency',
		],
		'status'   => 'Status',
	],
	'row_actions'   => [
		'view'   => [
			'label' => 'View',
			'url'   => admin_url( 'admin.php?page=orders&id={id}' ),
		],
		'edit'   => [
			'label'        => 'Edit',
			'url_callback' => function ( $row ) {
				return get_edit_post_link( $row['post_id'] );
			},
		],
		'delete' => [
			'label'   => 'Delete',
			'url'     => '#',
			'class'   => 'delete',      // Red styling
			'confirm' => 'Are you sure?',
			'target'  => '_blank',      // Optional
		],
	],
	'data_callback' => 'my_table_callback',
],
```

**Row Actions Features:**

- `url` - URL template with `{column}` placeholders
- `url_callback` - Function receiving `$row` array, returns URL
- `class` - CSS class (`delete` or `trash` = red styling)
- `confirm` - JavaScript confirm dialog message
- `target` - Link target (`_blank` for new tab)

**Table Callback:**

```
function my_table_callback( array $date_range, array $config ): array {
	return [
		[ 'id' => 1, 'customer' => 'John', 'total' => 9900, 'status' => 'Completed' ],
		[ 'id' => 2, 'customer' => 'Jane', 'total' => 15000, 'status' => 'Pending' ],
	];
}
```

### Export Configuration

[](#export-configuration)

```
'exports' => [
	'orders_export' => [
		'title'          => 'Export Orders',
		'description'    => 'Download all orders as CSV.',
		'tab'            => 'exports',
		'filename'       => 'orders',  // Or use callback
		'headers'        => [
			'id'       => 'Order ID',
			'customer' => 'Customer',
			'total'    => 'Total',
		],
		'filters'        => [
			'status' => [
				'type'    => 'select',
				'label'   => 'Status',
				'options' => [
					''          => 'All',
					'completed' => 'Completed',
					'pending'   => 'Pending',
				],
			],
		],
		'total_callback' => 'get_total_orders',
		'data_callback'  => 'get_orders_batch',
	],
],
```

**Dynamic Filename:**

```
'filename' => function ( array $date_range, array $config ): string {
	return 'orders-' . $date_range['start_local'] . '-to-' . $date_range['end_local'];
},
```

**Export Callbacks:**

```
function get_total_orders( array $args ): int {
	$filters = $args['filters'] ?? [];

	// Return total count
	return 1000;
}

function get_orders_batch( array $args ): array {
	$offset  = $args['offset'];
	$limit   = $args['limit'];
	$filters = $args['filters'] ?? [];

	// Return batch of rows
	return [
		[ 'id' => 1, 'customer' => 'John', 'total' => '$99.00' ],
		// ...
	];
}
```

Date Range
----------

[](#date-range)

The `$date_range` array passed to callbacks:

```
[
	'start'       => '2024-01-01 00:00:00',  // UTC
	'end'         => '2024-01-31 23:59:59',  // UTC
	'start_local' => '2024-01-01',           // Local Y-m-d
	'end_local'   => '2024-01-31',           // Local Y-m-d
	'preset'      => 'this_month',           // Selected preset
	'filters'     => [                       // Tab filter values
		'category' => 'electronics',
		'status'   => '',
	],
]
```

Value Formats
-------------

[](#value-formats)

FormatDescriptionExample`number`Integer with commas1,234`decimal`Two decimal places1,234.56`currency`Currency (value in cents)$12.34`percentage`With % symbol12.3%`text`Raw textActiveIcon Colors
-----------

[](#icon-colors)

- `blue` - #2271b1
- `green` - #00a32a
- `red` - #d63638
- `orange` - #dba617
- `purple` - #8b5cf6
- `gray` - #646970

Auto-Refresh
------------

[](#auto-refresh)

```
register_reports( 'live-dashboard', [
	'auto_refresh' => 30,   // Refresh every 30 seconds
	'show_refresh' => true, // Also show manual button
] );
```

- Components refresh via AJAX without page reload
- "Last updated: Xs ago" timestamp in header
- Auto-refresh pauses when browser tab is hidden
- Manual refresh resets the timer

Chart.js
--------

[](#chartjs)

Charts require Chart.js v4.5.1 at `assets/js/chart.umd.min.js`.

Download:

License
-------

[](#license)

GPL-2.0-or-later

Credits
-------

[](#credits)

Developed by [ArrayPress](https://arraypress.com/)

###  Health Score

19

—

LowBetter than 9% of packages

Maintenance50

Moderate activity, may be stable

Popularity5

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity12

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/cd6eb8aff0903d87eb674d1ba3c5f3653899c0d7661504eb0deb7798ed86b643?d=identicon)[arraypress](/maintainers/arraypress)

---

Top Contributors

[![arraypress](https://avatars.githubusercontent.com/u/22668877?v=4)](https://github.com/arraypress "arraypress (22 commits)")

### Embed Badge

![Health badge](/badges/arraypress-wp-register-reports/health.svg)

```
[![Health](https://phpackages.com/badges/arraypress-wp-register-reports/health.svg)](https://phpackages.com/packages/arraypress-wp-register-reports)
```

###  Alternatives

[cerdic/css-tidy

CSSTidy is a CSS minifier

2112.1M6](/packages/cerdic-css-tidy)[fusic/maintenance

Maintenance plugin for CakePHP

4259.2k](/packages/fusic-maintenance)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)