Search by

arraypress / wp-register-importers

arraypress

This package is abandoned and no longer maintained. No replacement package was suggested.

Declarative CSV import screens for WordPress plugins: field mapping, validation, dry runs and batch processing.

Package info

github.com/arraypress/wp-register-importers

pkg:composer/arraypress/wp-register-importers

Statistics

Installs: 6

Dependents: 0

Suggesters: 0

Stars: 2

Open Issues: 0

v1.0.0 2026-08-25 18:02 UTC

This package is auto-updated.

Last update: 2026-11-18 10:54:05 UTC


README

This library has moved. It is now part of sugarcommerce/importers (namespace SugarCommerce\Importers, PHP 8.3+). That package's README has a "Moving from arraypress/wp-*" table. This repository is archived and read-only.

Register Importers

A CSV import screen: column mapping, validation, a dry run and batching, from a description of the fields.

What it does

Importing a CSV properly is more work than it sounds. The columns are never in the order you expect, so they have to be mapped. The values are strings, so they have to be validated and converted. A file of ten thousand rows will time out, so it has to be batched. And a mistake found on row 4,000 is a mess to undo, so it needs a dry run first.

This is all of that, generated from a list of fields and one callback that handles a single row.

Features

  • Let the user map their columns to your fields, in whatever order they came
  • Validate and convert values by type — numbers, booleans, dates, terms
  • Create a missing term during import, rather than failing the row
  • Run the whole file without writing anything, and report what would happen
  • Import in batches, so a large file does not time out
  • Report failures per row and carry on, instead of stopping at the first
  • Put several importers behind one screen, as tabs

Installation

composer require arraypress/wp-register-importers

Quick start

add_action( 'init', function () {
	register_importers( 'myplugin-import', [
		'parent_slug' => 'tools.php',
		'page_title'  => __( 'Import', 'my-plugin' ),
		'operations'  => [
			'products' => [
				'title'  => __( 'Products', 'my-plugin' ),
				'fields' => [
					'sku'   => [ 'label' => __( 'Code', 'my-plugin' ), 'required' => true ],
					'name'  => __( 'Name', 'my-plugin' ),
					'price' => [ 'label' => __( 'Price', 'my-plugin' ), 'type' => 'number', 'minimum' => 0 ],
				],
				'process_callback' => function ( array $row ) {
					// One row, already mapped and converted.
				},
			],
		],
	] );
} );

process_callback gets a row that has been mapped, validated and converted. Everything before that point is not yours to write.

Register on init. The upload and batch requests go through the REST API, which never fires admin_menu, so a screen registered only there has a page but nothing behind it. A screen registered from inside admin_menu (or after it) still gets its menu page, at once.

Functions

Function Returns
register_importers( $id, $config ) The Importer, or null when it has no operations
get_registered_importers( $id ) The registered Importer, or null
get_registered_importers_url( $id, $tab = '' ) The screen's admin URL, for linking to it; '' when there is none
unregister_importers( $id ) Whether there was one to forget

The getter is not get_importers(): WordPress core declares that in wp-admin/includes/import.php.

Icons

A tab and an operation each take an icon, drawn before the label, in either of two forms:

register_importers( 'myplugin-import', [
	'tabs'       => [
		'catalog'   => [ 'label' => __( 'Catalog', 'my-plugin' ), 'icon' => 'heroicons-outline:shopping-bag' ],
		'customers' => [ 'label' => __( 'Customers', 'my-plugin' ), 'icon' => 'groups' ], // a Dashicon
	],
	'operations' => [
		'products' => [
			'tab'  => 'catalog',
			'icon' => 'heroicons-outline:cube', // or 'products', or 'dashicons-products'
			// ...
		],
	],
] );

A set:name value — heroicons-outline:*, heroicons-solid:*, or any set wp-field-kit knows — is drawn as inline SVG in the text's colour; a bare Dashicons name, with or without the dashicons- prefix, as the Dashicon. An operation that names no icon gets heroicons-outline:arrow-up-tray. wp-field-kit is suggested rather than required: without it a set:name icon draws nothing, a Dashicons name draws as it always has, and the default is the upload Dashicon.

The screen's own icon, for a top-level menu (parent_slug set to ''), is drawn by WordPress's admin menu, so it stays a Dashicons class, a URL or a data:image/svg+xml;base64, URI; it defaults to dashicons-upload.

Requirements

  • PHP 8.3 or later
  • WordPress 7.1 or later

License

GPL-2.0-or-later