Catalog Health Scanner Developer Reference

Every extension point in Catalog Health Scanner for WooCommerce Pro uses the wpfchs_ prefix: filters for the check library, applicability, thresholds and meta keys, actions around scans and fixes, three custom database tables, and a small set of post meta keys. This page lists them as they exist in version 1.0.0, verified against the shipped source.

Classes use the WPFCHS_ prefix, the text domain is catalog-health-scanner-for-woocommerce, and everything is reachable from the global accessor wpfchs().

Getting at the plugin #

wpfchs() returns the singleton main class. Its core property holds every subsystem:

Useful methods on the main class and on core:

Filters #

Core behaviour #

Applicability #

Meta keys and taxonomies the checks read #

These let you point Catalog Health Scanner at the fields your store actually uses, without touching the checks themselves.

Scanning, fixing, and recommendations #

The recommendation map ships deliberately small: a recommendation only appears where the recommended plugin genuinely solves the finding. As of 1.0.0 it covers gtin_missing, the three cost and margin checks, and the three tax checks. Each entry is an array of plugin, url, and text.

Actions #

$trigger is either manual or scheduled. $items is an object ID to { before, after } map, which is exactly what undo replays.

Cron events #

Adding your own check #

Hook wpfchs_checks and push a definition array. A definition understands the keys below; anything you leave out takes its default.

add_filter( 'wpfchs_checks', function ( $defs ) {
	$defs[] = array(
		'id'          => 'my_missing_care_label',
		'category'    => 'content',
		'label'       => __( 'Missing care label', 'my-plugin' ),
		'explanation' => __( 'Garment pages without a care label generate avoidable returns.', 'my-plugin' ),
		'severity'    => 'medium',
		'applies'     => function ( $product ) {
			return $product->is_type( array( 'simple', 'variable' ) );
		},
		'check'       => function ( $product ) {
			$value = get_post_meta( $product->get_id(), '_care_label', true );
			return ( '' === $value ? __( 'No care label', 'my-plugin' ) : false );
		},
	);
	return $defs;
} );

Your check appears in the settings tick boxes, in custom profile builders, in the category tab, in exports and the PDF report, and in the score at its severity weight, exactly like a shipped one.

Database tables #

Three tables are created on activation and on every version update, all with the site table prefix. None of them hold customer data.

The tables are not dropped on deactivation or uninstall, so history survives a plugin update or a temporary deactivation.

Post meta keys #

Transients #

AJAX endpoints #

All admin AJAX actions are nonce-protected and require the capability from wpfchs_capability. They are listed for debugging; they are not a public API and their payloads may change between releases.

wpfchs_scan_start, wpfchs_scan_step, wpfchs_scan_control, wpfchs_group_products, wpfchs_ignore_issue, wpfchs_restore_issue, wpfchs_ignore_bulk, wpfchs_restore_bulk, wpfchs_fix_preview, wpfchs_fix_apply, wpfchs_fix_undo, wpfchs_fix_all_quick_wins, wpfchs_preview_quick_wins, wpfchs_dismiss_rec.

Notes on writing extensions safely #

• Register your filters on wpfchs_core_loaded or earlier. The check registry builds itself lazily on first use, and the built list is cached for the request.
• A per-product check callback runs once per product per scan. Keep it free of remote calls, or cache them in a transient the way the download URL check does.
• Catalog passes run once at the end of a scan and are scored against the total published product count, so return only genuine failures.
• Returning an empty string, null, or false from a check all count as a pass. Return a short offending value instead of true where you can: it is stored on the issue and shown in the UI, the CSV export, and the PDF report.

Related reading #

• Check library: all 70 checks, for every shipped check ID
• Settings reference, for the options behind these filters
• How the health score is calculated

Need help? #

If you are extending Catalog Health Scanner and a hook does not behave as expected, contact Catalog Health Scanner support with the hook name and a short code sample.