arraypress / wp-register-reports
WordPress library for registering report pages with charts, tiles, tables, and CSV export functionality.
Requires
- php: >=8.3
- arraypress/wp-composer-assets: dev-main
- arraypress/wp-date-utils: dev-main
- arraypress/wp-field-kit: dev-main
Requires (Dev)
- phpcompatibility/phpcompatibility-wp: ^2.1
- phpunit/phpunit: ^12.0
- squizlabs/php_codesniffer: ^3.13.5
- wp-coding-standards/wpcs: ^3.4
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
This library has moved. It is now part of
sugarcommerce/reports(namespaceSugarCommerce\Reports, PHP 8.3+). That package's README has a "Moving from arraypress/wp-*" table. This repository is archived and read-only.
Register Reports
An analytics screen — tiles, charts, tables and a date range — from a description of what to show.
What it does
A reports page is the same furniture every time: a date-range control, tabs, filters, a row of headline figures, some charts and a table or two, all reloading together when the range changes.
None of that is the interesting part. This builds it, and asks you only for the callbacks that fetch the numbers.
Features
- Get a reports screen with a date-range picker and comparison periods
- Show headline figures as tiles, with the change against the previous period
- Add line, bar and pie charts without touching a charting library
- Draw money, counts on a second axis, bars and a line together, with a figure and a sentence above
- Show a funnel: steps side by side, with how many carried on from each
- Put a sentence across a tab that takes no room when it has nothing to say
- Add a data table, sortable and paged, beside them
- Group everything into tabs, each with its own filters
- Refresh in place when the range or a filter changes, without a page load
- Offer a CSV export of what is on screen, batched so it does not time out
- Let each person hide the components they do not read, per tab, from Screen Options
Installation
composer require arraypress/wp-register-reports
Quick start
register_reports( 'my-analytics', [ 'page_title' => __( 'Analytics', 'my-plugin' ), 'menu_title' => __( 'Analytics', 'my-plugin' ), 'parent_slug' => 'tools.php', 'tabs' => [ 'overview' => [ 'label' => __( 'Overview', 'my-plugin' ) ], ], 'components' => [ 'revenue' => [ 'type' => 'tile', 'tab' => 'overview', 'title' => __( 'Revenue', 'my-plugin' ), 'value_format' => 'currency', 'data_callback' => '\MyPlugin\get_revenue', ], ], ] );
data_callback is handed the date range and the active filters, and returns
a number. The tile, its formatting and the comparison against the previous
period are not yours to build.
Charts
A chart's data_callback returns labels and datasets, as Chart.js has
them. Datasets builds the datasets the way the report draws them, and the
keys on the component build the options:
use ArrayPress\RegisterReports\Datasets; 'sales' => [ 'type' => 'chart', 'tab' => 'overview', 'title' => __( 'Net revenue', 'my-plugin' ), 'height' => 280, 'value_format' => 'currency', // Money up the side and in the tooltip. 'currency' => 'GBP', 'secondary_axis' => true, // A count on the right, for datasets with yAxisID y1. 'show_period' => false, // No "— Last 30 days" after the title. 'headline' => 'my_plugin_sales_headline', // [ 'value' => '£1,204', 'change' => '12% vs previous period', 'direction' => 'up' ] 'caption' => 'my_plugin_sales_caption', // A sentence under the figure. 'data_callback' => function ( array $range ): array { $series = my_plugin_sales_series( $range ); return [ 'labels' => $series['labels'], 'datasets' => [ Datasets::line( __( 'Net revenue', 'my-plugin' ), Datasets::so_far( $series['net'], $series['starts'] ), '#3858e9' ), Datasets::line( __( 'Orders', 'my-plugin' ), Datasets::so_far( $series['orders'], $series['starts'] ), '#9aa0a6', [ 'yAxisID' => 'y1' ] ), ], ]; }, ],
Two lines over each other each fade from their own colour. The legend is
drawn for two series and not for one (show_legend: auto, true or
false).
value_formatiscurrency(withcurrency, formatted by the browser, which knows a yen has no pence) orinteger; anything else is a plain number. Chart values are amounts as they are read -- 49.99, not 4999.secondary_axisistruefor a count, or[ 'value_format' => ..., 'label' => ... ].headlineandcaptionare values or callables handed the range and the component. A caption replacesdescriptionwhen it has something to say.chart_typemay beauto: bars for up tobars_maxbuckets (12), a line for more. A first dataset that names its owntypedecides the chart instead, which is howDatasets::over_time()makes the choice and how bars and a line are drawn together.optionsis laid over everything the keys built, keyed arrays merged and lists replaced, so any Chart.js option is one key away:'options' => [ 'scales' => [ 'y' => [ 'max' => 100 ] ] ].
Datasets:
| Method | What it returns |
|---|---|
line( $label, $data, $colour = '', $extra = [] ) |
A monotone line; the script fades the area under it from $colour. |
bars( $label, $data, $colour = '', $extra = [] ) |
Bars, in one colour or a colour per bar. |
highlight( $data, $colour, $tint ) |
A colour per bar: the tallest in $colour, the rest in $tint, all $tint when every bar is nought. |
over_time( $label, $data, [ 'colour', 'bars_max', 'starts', 'now' ] ) |
Bars while they can be counted, a line once there are more. |
so_far( $data, $starts, $now = null ) |
The values with buckets that have not started set to null, so a line stops at today rather than falling to the floor. |
A colour given per bar keeps its colour under the pointer, and a refresh draws the colours the new data gives: the best bar this time, not last time's.
Funnels
How many of those who started something went on to finish it: baskets to orders, sign-ups to paid.
'basket_to_order' => [ 'type' => 'funnel', 'tab' => 'overview', 'title' => __( 'From basket to order', 'my-plugin' ), 'width' => 'full', 'colour' => '#3858e9', // The bars; the admin colour scheme's otherwise. 'data_callback' => function ( array $range ): array { return [ 'steps' => [ [ 'label' => __( 'Baskets', 'my-plugin' ), 'count' => 200 ], [ 'label' => __( 'Checkouts', 'my-plugin' ), 'count' => 50, 'next' => __( '%s were paid for', 'my-plugin' ) ], [ 'label' => __( 'Orders', 'my-plugin' ), 'count' => 40 ], ], 'headline' => [ 'value' => '20%', 'change' => '3% vs previous period', 'direction' => 'up' ], 'description' => __( 'Of 200 baskets, 40 were paid for.', 'my-plugin' ), 'foot' => [ __( '12 left at checkout', 'my-plugin' ), __( 'Average basket £30', 'my-plugin' ) ], ]; }, ],
Each step is a bar against the first, and under it the share that reached
the next: in its own words with note, as a format with next ("%s were
paid for"), or "62% continued". The last step says nothing unless it has a
note. Without a headline the figure is the whole way through, last
step over first. The callback may return just the list of steps.
A funnel whose first step is nought, or that has no steps, draws nothing: a card of noughts would tell a shop with no baskets it had lost every sale. It is drawn with the page and not refreshed in place.
Notes and HTML
An html component prints content -- markup, or a callable handed the
range and the component -- or whatever its render_callback prints.
'when_to_post' => [ 'type' => 'html', 'tab' => 'timing', 'title' => '', 'width' => 'full', 'appearance' => 'note', // A sentence in a card of its own. 'markup' => false, // Plain text, escaped. Markup goes through wp_kses_post(). 'hide_when_empty' => true, // Nothing to say, no room taken. 'content' => fn( array $range ): string => my_plugin_best_hour_sentence( $range ), ],
hide_when_empty is off by default, because an empty box is also what a
script fills in later. A component with ajax_refresh false is left out of
the in-place refresh.
Whose days: UTC or the site's
A date range reaches every data_callback as start and end in UTC, for a
column that stores UTC. Where "today" starts is a separate question, and by
default it is midnight UTC. A report whose days should be the site's says so:
register_reports( 'my-analytics', [ 'timezone' => 'site', // 'utc' (default), 'site', or a DateTimeZone 'week_starts' => null, // 0 Sunday to 6 Saturday; null is Monday for // 'utc' and the site's own setting otherwise ] );
With 'site', Today is the site's midnight to its next midnight -- 23 or 25
hours on the day the clocks change -- two picked dates are the site's days,
and This Week starts on the day set under Settings > General. The page, the
REST refresh and the exports all resolve a period through
Reports::resolve_range(), so they agree. Needs wp-date-utils 2.1.0; with an
older one the days stay UTC's.
Layout: tabs or a sidebar
The sections of a report are tabs across the top while there are few of them, and a list down the left once there are many. Nothing has to be set: the report counts its tabs.
register_reports( 'my-analytics', [ 'layout' => 'auto', // 'auto', 'tabs' or 'sidebar' 'sidebar_after' => 6, // 'auto' is a sidebar above this many tabs 'tabs' => [ 'overview' => [ 'label' => __( 'Overview', 'my-plugin' ), 'icon' => 'heroicons-outline:chart-bar' ], 'export' => [ 'label' => __( 'Export', 'my-plugin' ), 'position' => 100 ], 'payouts' => [ 'label' => __( 'Payouts', 'my-plugin' ), 'icon' => 'dashicons-bank', 'group' => __( 'Add-ons', 'my-plugin' ), 'position' => 60, ], ], ] );
positionorders the tabs in either layout. Tabs that name none sit at 10, 20, 30 and so on in the order they were written, so there is room between any two.groupis a heading in the sidebar. Tabs without one are listed first, then each group under its heading. The tab bar has no headings and ignores it.iconis drawn in the sidebar and not on a tab, as in WordPress itself. Either form in Icons:heroicons-outline:chart-barordashicons-bank.
The body carries reports-layout--tabs or reports-layout--sidebar. Below
782px the sidebar becomes a single row of links above the report that
scrolls sideways, and the tab bar scrolls the same way when its tabs do not
fit, so neither wraps onto a second line.
Icons
Everywhere a report takes an icon, it takes one of two forms:
set:name, from the field kit's icon sets --heroicons-outline:key,heroicons-solid:star,wordpress:...-- drawn as inline SVG in the colour of the text around it. The Heroicons names are the ones on heroicons.com.- A Dashicons name,
admin-networkordashicons-admin-network, drawn as the Dashicons span it always was. A report written before there were icon sets looks as it did.
Either way the element carries the class arraypress-icon, which is what the
stylesheet sizes. A value that is neither -- a typo, an icon no set has --
draws nothing. Needs wp-field-kit 1.6.0 (Icons::render()).
'tabs' => [ 'licenses' => [ 'label' => __( 'Licences', 'my-plugin' ), 'icon' => 'heroicons-outline:key' ], 'products' => [ 'label' => __( 'Products', 'my-plugin' ), 'icon' => 'dashicons-products' ], ], 'components' => [ 'issued' => [ 'type' => 'tile', 'tab' => 'licenses', 'title' => __( 'Licences issued', 'my-plugin' ), 'icon' => 'heroicons-outline:key', 'icon_color' => 'blue', 'data_callback' => 'my_plugin_licences_issued', ], 'countries' => [ 'type' => 'breakdown', 'tab' => 'licenses', 'title' => __( 'Activations by country', 'my-plugin' ), 'data_callback' => static fn(): array => [ 'rows' => [ [ 'label' => 'Japan', 'value' => 12, 'icon' => 'https://example.com/flags/jp.svg' ], [ 'label' => 'Elsewhere', 'value' => 3, 'icon' => 'heroicons-outline:globe-alt' ], ], ], ], ],
- A tab's
iconis drawn in the sidebar. - A tile's
icondefaults toheroicons-outline:chart-bar. The stylesheet keeps a tile's icon box hidden -- a tile is a number and its change -- so it is there for a stylesheet that shows it. - A breakdown or stat list row's
iconis a picture's URL (a flag, a thumbnail) or aset:nameicon, drawn at 16px before the label. A bare word there is a relative URL, not a Dashicon. - The library's own -- the arrow beside a change, the caret on the date picker, the calendar under the exports and the empty screen's chart -- are Heroicons outline.
- The report's own
icon, for a top-level menu entry, is passed toadd_menu_page()and so takes what core takes: a Dashicons class (defaultdashicons-chart-area), a URL or a base64 SVG.
Adding to a report from another plugin
Three ways, depending on when your code runs.
Before the report is registered, filter its configuration. The hook is
reports_register for a plain Composer install; in a copy prefixed by
Strauss it carries the prefix (myplugin_reports_register), and
Runtime::hook( 'register' ) gives the name either way.
add_filter( 'reports_register', function ( array $config, string $id ): array { if ( 'my-analytics' === $id ) { $config['tabs']['payouts'] = [ 'label' => 'Payouts', 'group' => 'Add-ons' ]; $config['components']['paid_out'] = [ 'type' => 'tile', 'tab' => 'payouts', 'title' => 'Paid out', 'data_callback' => 'my_addon_paid_out', ]; } return $config; }, 10, 2 );
After it is registered, add to the report itself:
add_action( 'init', function (): void { $report = get_reports( 'my-analytics' ); if ( $report ) { $report ->add_tab( 'payouts', [ 'label' => 'Payouts', 'position' => 60 ] ) ->add_component( 'paid_out', [ 'type' => 'tile', 'tab' => 'payouts', 'data_callback' => 'my_addon_paid_out' ] ) ->add_export( 'payouts', [ 'tab' => 'payouts', 'data_callback' => 'my_addon_payout_rows', 'total_callback' => 'my_addon_payout_count' ] ); } }, 20 );
Either way, do it on every request and not only in the admin: the figures are fetched over REST, and a component added only where the page is drawn is one the REST request has never heard of.
A component of a type the library does not have is drawn by a filter,
reports_render_component (prefixed the same way): return true from it once
you have printed the component.
Requirements
- PHP 8.3 or later
- WordPress 7.1 or later
License
GPL-2.0-or-later