Search by

arraypress / wp-inline-sync

arraypress

Lightweight WordPress library for inline batch sync operations with progress UI. Register sync operations that run directly on existing admin screens.

Package info

github.com/arraypress/wp-inline-sync

Homepage

pkg:composer/arraypress/wp-inline-sync

Statistics

Installs: 31

Dependents: 0

Suggesters: 1

Stars: 1

Open Issues: 0

v1.0.0 2026-08-25 19:00 UTC

This package is auto-updated.

Last update: 2026-11-18 10:52:03 UTC


README

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

Inline Sync

Pull a few thousand records from an API into WordPress, from a button on an admin screen, without the request timing out.

What it does

Importing anything sizeable means batching: fetch a page, process it, report progress, fetch the next — and doing that from an admin screen means a REST endpoint, a nonce, a JavaScript loop, a progress bar and somewhere to keep the cursor between calls.

This is that loop, written once. You supply two callbacks — one that fetches a page, one that handles a single record — and the batching, the progress UI and the error reporting are handled.

Features

  • Import in batches from a button, without a request that can time out
  • Show progress as it goes, with the name of the record being worked on
  • Resume from a cursor, so a paginated API is walked properly
  • Carry on where a closed browser stopped, with the page reached saved as it goes
  • Remember what failed and why, and try it all again from one button
  • Report a failure on one record without abandoning the rest of the run
  • Put the button on one admin screen, rather than everywhere
  • Keep two prefixed copies of the library from fighting over one endpoint

Installation

composer require arraypress/wp-inline-sync

Quick start

register_sync( 'stripe_prices', [
	'hook_suffix'      => 'toplevel_page_sugarcart',
	'title'            => __( 'Sync Prices', 'my-plugin' ),
	'button_label'     => __( 'Sync from Stripe', 'my-plugin' ),
	'container'        => '.wp-list-table',
	'data_callback'    => 'MyPlugin\fetch_prices',
	'process_callback' => 'MyPlugin\process_price',
	'name_callback'    => fn( $item ) => $item->product->name ?? $item->id,
] );

Then, on the screen itself:

render_sync_button( 'stripe_prices' );

data_callback is handed a cursor and returns a page plus the next one. process_callback gets one record at a time and does whatever the import means — the loop between them is not yours to write.

Register on init, not admin_init. The button is an admin thing, but the work happens over REST, and admin_init does not run on a REST request — a sync registered there has a button and no endpoint behind it.

Carrying on after a closed browser

A long import is hundreds of requests from a browser that can be closed at any of them. Register the sync with resume and it writes down where it has got to, in an option of its own (not autoloaded):

register_sync( 'shop_import_orders', [
	'hook_suffix'      => $hook,
	'title'            => __( 'Orders', 'my-plugin' ),
	'resume'           => true,
	'data_callback'    => 'MyPlugin\orders_page',   // ( string $cursor ): array
	'process_callback' => 'MyPlugin\import_order',  // ( $item ): 'created'|'updated'|'skipped'|WP_Error
	'id_callback'      => fn( $item ) => $item['id'], // keys its failure; default the item's `id`
] );
  • The cursor of a page is saved before the page is read, so a page that never finished is the one to start again from. Once a page is processed the cursor moves on to the next.
  • Started again with an empty cursor (the button always starts that way), the sync carries on from the saved cursor.
  • A browser closed half-way through a page reads that page again, so the process callback must find what it made last time — reading a page twice should cost time and nothing else.
  • After the last page is processed the sync is done, and pressing its button again does nothing until you start a new run:
get_sync( 'shop_import_orders' )->reset_progress(); // back to page one, counts and failures cleared

$progress = get_sync( 'shop_import_orders' )->progress();
$progress->get();      // cursor, done, created, updated, skipped, failed, failures, date_started, last_run
$progress->is_done();
$progress->failures(); // [ [ 'sync', 'id', 'name', 'message', 'date', 'item'? ], ... ]

progress_option names the option (default derived from the build and the sync's ID); max_failures caps the failure list (default 500, newest kept).

Trying failures again

Each failure is kept with its reason, keyed by the item's ID, so an item that fails twice is one entry and one that succeeds later is struck off. A retry sync is one more button that tries every failure of the syncs you name, each through the sync it came from:

use ArrayPress\InlineSync\Retry;

Retry::register( 'shop_import_retry', [ 'shop_import_orders', 'shop_import_files' ], [
	'hook_suffix'  => $hook,
	'title'        => __( 'Trying again', 'my-plugin' ),
	'button_label' => __( 'Try Again', 'my-plugin' ),
] );

By default the item is kept with its failure and replayed as it was. When the other end may have changed — or anything in the old copy expires, a download link say — give the source sync a retry_callback that fetches a fresh copy instead; the item is then not stored:

'retry_callback' => fn( array $failure ) => MyPlugin\fetch_order( $failure['id'] ), // item or WP_Error

A fresh copy that cannot be had leaves the failure in place with the new reason.

Requirements

  • PHP 8.3 or later
  • WordPress 7.1 or later

License

GPL-2.0-or-later