Cybo Advanced Field EngineCyboweb Technologies · Documentation · v1.0.2

cafe_import_object()

Purpose

Creates or updates one WordPress object (post, term, user or the Settings Page values) together with its CAFE values: the building block for your own migration code. It does what CAFE → Migration does for each record:

  1. finds the object imported earlier from the same source record, so running your code twice updates instead of creating duplicates,
  2. checks every WordPress field and every CAFE value; nothing is written when anything is invalid,
  3. writes everything in one database transaction.

You never touch CAFE's database tables: values go through CAFE's public API.

Syntax

cafe_import_object( array $data, array $options = [] ): array|WP_Error

Parameters

Parameter Type Default Description
$data['object_type'] string 'post' 'post', 'term', 'user' or 'option' (Settings Page values).
$data['post_type'] / $data['taxonomy'] string 'post' Post type or taxonomy of the object.
$data['source'] string - A name for where the data comes from, e.g. 'legacy-properties'. With source_id, the object remembers its record.
$data['source_id'] string|int - The record's ID in the old system.
$data['object_id'] int - Update exactly this object instead of looking it up.
$data['wp'] array [] WordPress fields: post_title, post_content, post_excerpt, post_status, post_date, post_author, post_parent, post_name, menu_order, featured_image (attachment ID), terms:{taxonomy} (term IDs); for terms name, slug, description, parent; for users display_name, first_name, last_name, nickname, description, user_url, and user_email to find the user. With WPML: language and translation_of (source ID of the original).
$data['fields'] array [] CAFE values by field name or key, in the shapes cafe_save_values() accepts.
$options['mode'] string 'create_update' 'create_update', 'create_only' (existing objects are skipped) or 'update_only' (new records are skipped).
$options['dry_run'] bool false Only check; write nothing.
$options['default_status'] string 'draft' Status of new posts when post_status is not given.

Return value

An array:

[
	'status'    => 'created', // 'created', 'updated', 'skipped' or 'failed' (in a dry run: what would happen)
	'object_id' => 123,
	'problems'  => [ [ 'field' => 'price', 'message' => 'Price must be a number.' ] ],
	'warnings'  => [],
	'dry_run'   => false,
]

A WP_Error only for an unknown object type, post type or taxonomy.

Example

Properties with their team members from two old tables:

global $wpdb;

$rows = $wpdb->get_results( "SELECT id, title, description, price, agent_id, status FROM {$wpdb->prefix}old_properties" );

foreach ( $rows as $row ) {
	$team = $wpdb->get_results(
		$wpdb->prepare( "SELECT name, role FROM {$wpdb->prefix}old_property_team WHERE property_id = %d", $row->id ),
		ARRAY_A
	);

	$result = cafe_import_object(
		[
			'post_type' => 'property',
			'source'    => 'legacy-properties',
			'source_id' => $row->id,
			'wp'        => [
				'post_title'   => $row->title,
				'post_content' => $row->description,
				'post_status'  => 'publish',
			],
			'fields'    => [
				'price'        => (float) $row->price,
				'agent'        => cafe_imported_object_id( 'legacy-agents', $row->agent_id ),
				'status'       => '1' === $row->status ? 'available' : 'sold',
				'team_members' => $team, // [ [ 'name' => …, 'role' => … ], … ]
			],
		]
	);

	if ( 'failed' === $result['status'] ) {
		error_log( "Property {$row->id}: " . $result['problems'][0]['message'] );
	}
}

The full walkthrough (batches, media, relationships, WP-CLI) is in Custom PHP migrations.

Notes

  • No permission check: like wp_insert_post(). Run it from WP-CLI, from an admin action with your own capability and nonce checks, or from a cron job.
  • The source ID is remembered in the object's own meta (_cafe_source:{source}:{id}), never in CAFE tables. Find it again with cafe_imported_object_id().
  • Users are never created: a user must exist (give object_id or wp.user_email).
  • For many records, read them in batches (for example 200 at a time) and call cafe()->flush_runtime_cache() between batches so memory stays flat.
  • An empty value ('', null, []) removes the saved CAFE value; leave the key out to keep it.
  • Rollback is recorded only for runs of CAFE → Migration. For your own code, run with dry_run first and keep a database backup.
  • Since 0.13.0.