arraypress / wp-register-importers
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
Requires
- php: >=8.3
- arraypress/wp-composer-assets: 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
- arraypress/wp-countries: Checks that a country column holds a real ISO 3166-1 code.
- arraypress/wp-money: Checks that a currency column holds a real ISO 4217 code.
Provides
None
Conflicts
None
Replaces
None
README
This library has moved. It is now part of
sugarcommerce/importers(namespaceSugarCommerce\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