WooCommerce Code Reference

MetaToCustomTableMigrator extends TableMigrator
in package

Base class for implementing migrations from the standard WordPress meta table to custom structured tables.

Table of Contents

$core_column_mapping  : array<string|int, mixed>
Column mapping from source table to destination custom table. See __construct for detailed config.
$meta_column_mapping  : array<string|int, mixed>
Meta config, see __construct for detailed config.
$schema_config  : array<string|int, mixed>
Config for tables being migrated and migrated from. See __construct() for detailed config.
$errors  : array<string|int, mixed>
An array of cummulated error messages.
__construct()  : mixed
MetaToCustomTableMigrator constructor.
fetch_sanitized_migration_data()  : array<string|int, array<string|int, mixed>>
Return data to be migrated for a batch of entities.
process_migration_batch_for_ids()  : array<string|int, mixed>
Migrate a batch of orders, logging any database error that could arise and the exception thrown if any.
process_migration_data()  : array<string|int, mixed>
Process migration data for a batch of entities.
verify_migrated_data()  : array<string|int, mixed>
Verify whether data was migrated properly for given IDs.
add_error()  : void
Add an error message to the errors list unless it's there already.
build_verification_query()  : string
Generate query to fetch data from both source and destination tables. Use the results in `verify_data` to verify if data was migrated properly.
clear_errors()  : void
Clear the error messages list.
db_get_results()  : mixed
Run $wpdb->get_results and add the error, if any, to the errors list.
db_query()  : mixed
Run $wpdb->query and add the error, if any, to the errors list.
get_additional_where_clause_for_get_data_to_insert_or_update()  : string
Get additional string to be appended to the WHERE clause of the SQL query used by get_data_to_insert_or_update.
get_already_existing_records()  : array<string|int, mixed>
Fetch id mappings for records that are already inserted in the destination table.
get_core_column_mapping()  : array<string|int, mixed>
Specify column config from the source table.
get_errors()  : array<string|int, mixed>
Get the list of error messages added.
get_meta_column_config()  : array<string|int, mixed>
Specify meta keys config from source meta table.
get_schema_config()  : array<string|int, mixed>
Specify schema config the source and destination table.
get_where_clause_for_verification()  : string
Helper function to generate where clause for fetching data for verification.
maybe_add_insert_or_update_error()  : void
Check if the amount of processed database rows matches the amount of orders to process, and log an error if not.
process_migration_batch_for_ids_core()  : void
Migrate a batch of entities from the posts table to the corresponding table.
verify_data()  : array<string|int, mixed>
Verify data from both source and destination tables and check if they were migrated properly.
build_entity_table_query()  : string
Helper method to build query used to fetch data from core source table.
build_meta_data_query()  : string
Helper method to build query that will be used to fetch data from source meta table.
fetch_data_for_migration_for_ids()  : array<string|int, array<string|int, mixed>>
Fetch data for migration.
fill_source_metadata()  : array<string|int, mixed>
Fill source metadata for given IDs for verification. This will return filled data in following format: [ { $source_table_$source_column: $value, ..., $destination_table_$destination_column: $value, ... meta_source_{$destination_column_name1}: $meta_value, ... }, ... ]
generate_column_clauses()  : array<string|int, mixed>
Generate values and columns clauses to be used in INSERT and INSERT..ON DUPLICATE KEY UPDATE statements.
generate_insert_sql_for_batch()  : string
Generate SQL for data insertion.
generate_update_sql_for_batch()  : string
Generate SQL for data updating.
get_destination_table_primary_id_schema()  : array<string|int, array<string|int, mixed>>
Generate schema for primary ID column of destination table.
get_type_defaults()  : mixed
Helper method to get default value of a type.
pre_process_row()  : array<string|int, mixed>
Helper method to pre-process rows to make sure we parse the correct type.
process_and_sanitize_data()  : array<string|int, array<string|int, mixed>>
Helper function to validate and combine data before we try to insert.
process_and_sanitize_entity_data()  : void
Helper method to sanitize core source table.
process_insert_batch()  : void
Process batch for insertion into destination table.
process_update_batch()  : void
Process batch for update into destination table.
processs_and_sanitize_meta_data()  : void
Helper method to sanitize soure meta data.
validate_data()  : float|int|mixed|string|WP_Error
Validate and transform data so that we catch as many errors as possible before inserting.
verify_entity_columns()  : array<string|int, mixed>
Helper method to verify and compare core columns.
verify_meta_columns()  : array<string|int, mixed>
Helper method to verify meta columns.

Properties

Methods

fetch_sanitized_migration_data()

Return data to be migrated for a batch of entities.

public fetch_sanitized_migration_data(array<string|int, mixed> $entity_ids) : array<string|int, array<string|int, mixed>>
Parameters
$entity_ids : array<string|int, mixed>

Ids of entities to migrate.

Return values
array<string|int, array<string|int, mixed>> — Data to be migrated. Would be of the form: array( 'data' => array( ... ), 'errors' => array( ... ) ).

process_migration_batch_for_ids()

Migrate a batch of orders, logging any database error that could arise and the exception thrown if any.

public process_migration_batch_for_ids(array<string|int, mixed> $entity_ids) : array<string|int, mixed>
Parameters
$entity_ids : array<string|int, mixed>

Order ids to migrate.

Tags
deprecated
8.0.0

Use fetch_sanitized_migration_data and process_migration_data instead.

Return values
array<string|int, mixed> — An array containing the keys 'errors' (array of strings) and 'exception' (exception object or null).

process_migration_data()

Process migration data for a batch of entities.

public process_migration_data(array<string|int, mixed> $data) : array<string|int, mixed>
Parameters
$data : array<string|int, mixed>

Data to be migrated. Should be of the form: array( 'data' => array( ... ) ) as returned by the fetch_sanitized_migration_data method.

Return values
array<string|int, mixed> — Array of errors and exception if any.

verify_migrated_data()

Verify whether data was migrated properly for given IDs.

public verify_migrated_data(array<string|int, mixed> $source_ids) : array<string|int, mixed>
Parameters
$source_ids : array<string|int, mixed>

List of source IDs.

Return values
array<string|int, mixed> — List of IDs along with columns that failed to migrate.

add_error()

Add an error message to the errors list unless it's there already.

protected add_error(string $error) : void
Parameters
$error : string

The error message to add.

Return values
void —

build_verification_query()

Generate query to fetch data from both source and destination tables. Use the results in `verify_data` to verify if data was migrated properly.

protected build_verification_query(array<string|int, mixed> $source_ids) : string
Parameters
$source_ids : array<string|int, mixed>

Array of IDs in source table.

Return values
string — SELECT statement.

db_get_results()

Run $wpdb->get_results and add the error, if any, to the errors list.

protected db_get_results([string|null $query = null ][, string $output = OBJECT ]) : mixed
Parameters
$query : string|null = null

The SQL query to run.

$output : string = OBJECT

Any of ARRAY_A | ARRAY_N | OBJECT | OBJECT_K constants.

Return values
mixed — Whatever $wpdb->get_results returns.

db_query()

Run $wpdb->query and add the error, if any, to the errors list.

protected db_query(string $query) : mixed
Parameters
$query : string

The SQL query to run.

Return values
mixed — Whatever $wpdb->query returns.

get_additional_where_clause_for_get_data_to_insert_or_update()

Get additional string to be appended to the WHERE clause of the SQL query used by get_data_to_insert_or_update.

protected get_additional_where_clause_for_get_data_to_insert_or_update(array<string|int, mixed> $entity_ids) : string
Parameters
$entity_ids : array<string|int, mixed>

The ids of the entities being inserted or updated.

Return values
string — Additional string for the WHERE clause, must either be empty or start with "AND" or "OR".

get_already_existing_records()

Fetch id mappings for records that are already inserted in the destination table.

protected get_already_existing_records(array<string|int, mixed> $entity_ids) : array<string|int, mixed>
Parameters
$entity_ids : array<string|int, mixed>

List of entity IDs to verify.

Return values
array<string|int, mixed> — Already migrated entities, would be of the form array( '$source_id1' => array( 'source_id' => $source_id1, 'destination_id' => $destination_id1 'modified' => 0 if it can be determined that the row doesn't need update, 1 otherwise ), ... )

get_core_column_mapping()

Specify column config from the source table.

protected abstract get_core_column_mapping() : array<string|int, mixed>
Return values
array<string|int, mixed> — Config, must be of the form: array( '$source_column_name_1' => array( // $source_column_name_1 is column name in source table, or a select statement. 'type' => 'type of value, could be string/int/date/float.', 'destination' => 'name of the column in column name where this data should be inserted in.', ), '$source_column_name_2' => array( ...... ), .... ).

get_meta_column_config()

Specify meta keys config from source meta table.

protected abstract get_meta_column_config() : array<string|int, mixed>
Return values
array<string|int, mixed> — Config, must be of the form. array( '$meta_key_1' => array( // $meta_key_1 is the name of meta_key in source meta table. 'type' => 'type of value, could be string/int/date/float', 'destination' => 'name of the column in column name where this data should be inserted in.', ), '$meta_key_2' => array( ...... ), .... ).

get_schema_config()

Specify schema config the source and destination table.

protected abstract get_schema_config() : array<string|int, mixed>
Return values
array<string|int, mixed> — Schema, must of the form: array( 'source' => array( 'entity' => array( 'table_name' => $source_table_name, 'meta_rel_column' => $column_meta, Name of column in source table which is referenced by meta table. 'destination_rel_column' => $column_dest, Name of column in source table which is refenced by destination table, 'primary_key' => $primary_key, Primary key of the source table ), 'meta' => array( 'table' => $meta_table_name, 'meta_key_column' => $meta_key_column_name, 'meta_value_column' => $meta_value_column_name, 'entity_id_column' => $entity_id_column, Name of the column having entity IDs. ), ), 'destination' => array( 'table_name' => $table_name, Name of destination table, 'source_rel_column' => $column_source_id, Name of the column in destination table which is referenced by source table. 'primary_key' => $table_primary_key, 'primary_key_type' => $type bool|int|string|decimal )

get_where_clause_for_verification()

Helper function to generate where clause for fetching data for verification.

protected get_where_clause_for_verification(array<string|int, mixed> $source_ids) : string
Parameters
$source_ids : array<string|int, mixed>

Array of IDs from source table.

Return values
string — WHERE clause.

maybe_add_insert_or_update_error()

Check if the amount of processed database rows matches the amount of orders to process, and log an error if not.

protected maybe_add_insert_or_update_error(string $operation, array<string|int, mixed>|bool $received_rows_count) : void
Parameters
$operation : string

Operation performed, 'insert' or 'update'.

$received_rows_count : array<string|int, mixed>|bool

Value returned by @wpdb after executing the query.

Return values
void —

process_migration_batch_for_ids_core()

Migrate a batch of entities from the posts table to the corresponding table.

protected process_migration_batch_for_ids_core(array<string|int, mixed> $entity_ids) : void
Parameters
$entity_ids : array<string|int, mixed>

Ids of entities to migrate.

Return values
void —

verify_data()

Verify data from both source and destination tables and check if they were migrated properly.

protected verify_data(array<string|int, mixed> $collected_data) : array<string|int, mixed>
Parameters
$collected_data : array<string|int, mixed>

Collected data in array format, should be in same structure as returned from query in $this->build_verification_query.

Return values
array<string|int, mixed> — Array of failed IDs if any, along with columns/meta_key names.

build_entity_table_query()

Helper method to build query used to fetch data from core source table.

private build_entity_table_query(array<string|int, mixed> $entity_ids) : string
Parameters
$entity_ids : array<string|int, mixed>

List of entity IDs to fetch.

Return values
string — Query that can be used to fetch data.

build_meta_data_query()

Helper method to build query that will be used to fetch data from source meta table.

private build_meta_data_query(array<string|int, mixed> $entity_ids) : string
Parameters
$entity_ids : array<string|int, mixed>

List of IDs to fetch metadata for.

Return values
string — Query for fetching meta data.

fetch_data_for_migration_for_ids()

Fetch data for migration.

private fetch_data_for_migration_for_ids(array<string|int, mixed> $entity_ids) : array<string|int, array<string|int, mixed>>
Parameters
$entity_ids : array<string|int, mixed>

Entity IDs to fetch data for.

Return values
array<string|int, array<string|int, mixed>> — Data along with errors (if any), will of the form: array( 'data' => array( 'id_1' => array( 'column1' => value1, 'column2' => value2, ...), ..., ), 'errors' => array( 'id_1' => array( 'column1' => error1, 'column2' => value2, ...), ..., )

fill_source_metadata()

Fill source metadata for given IDs for verification. This will return filled data in following format: [ { $source_table_$source_column: $value, ..., $destination_table_$destination_column: $value, ... meta_source_{$destination_column_name1}: $meta_value, ... }, ... ]

private fill_source_metadata(array<string|int, mixed> $results, array<string|int, mixed> $source_ids) : array<string|int, mixed>
Parameters
$results : array<string|int, mixed>

Entity data from both source and destination table.

$source_ids : array<string|int, mixed>

List of source IDs.

Return values
array<string|int, mixed> — Filled $results param with source metadata.

generate_column_clauses()

Generate values and columns clauses to be used in INSERT and INSERT..ON DUPLICATE KEY UPDATE statements.

private generate_column_clauses(array<string|int, mixed> $columns_schema, array<string|int, mixed> $batch) : array<string|int, mixed>
Parameters
$columns_schema : array<string|int, mixed>

Columns config for destination table.

$batch : array<string|int, mixed>

Actual data to migrate as returned by data in fetch_data_for_migration_for_ids method.

Return values
array<string|int, mixed> — SQL clause for values, columns placeholders, and columns.

generate_insert_sql_for_batch()

Generate SQL for data insertion.

private generate_insert_sql_for_batch(array<string|int, mixed> $batch) : string
Parameters
$batch : array<string|int, mixed>

Data to generate queries for. Will be 'data' array returned by $this->fetch_data_for_migration_for_ids() method.

Return values
string — Generated queries for insertion for this batch, would be of the form: INSERT IGNORE INTO $table_name ($columns) values ($value for row 1) ($value for row 2) ...

generate_update_sql_for_batch()

Generate SQL for data updating.

private generate_update_sql_for_batch(array<string|int, mixed> $batch, array<string|int, mixed> $entity_row_mapping) : string
Parameters
$batch : array<string|int, mixed>

Data to generate queries for. Will be data array returned by fetch_data_for_migration_for_ids() method.

$entity_row_mapping : array<string|int, mixed>

Maps rows to update data with their original IDs. Will be returned by generate_update_sql_for_batch.

Return values
string — Generated queries for batch update. Would be of the form: INSERT INTO $table ( $columns ) VALUES ($value for row 1) ($valye for row 2) ... ON DUPLICATE KEY UPDATE $column1 = VALUES($column1) $column2 = VALUES($column2) ...

get_destination_table_primary_id_schema()

Generate schema for primary ID column of destination table.

private get_destination_table_primary_id_schema() : array<string|int, array<string|int, mixed>>
Return values
array<string|int, array<string|int, mixed>> — Schema for primary ID column.

pre_process_row()

Helper method to pre-process rows to make sure we parse the correct type.

private pre_process_row(array<string|int, mixed> $row, array<string|int, mixed> $schema, string $alias, string $destination_alias) : array<string|int, mixed>
Parameters
$row : array<string|int, mixed>

Both migrated and source data for a single row.

$schema : array<string|int, mixed>

Column schema.

$alias : string

Name of source column.

$destination_alias : string

Name of destination column.

Return values
array<string|int, mixed> — Processed row.

process_and_sanitize_data()

Helper function to validate and combine data before we try to insert.

private process_and_sanitize_data(array<string|int, mixed> $entity_data, array<string|int, mixed> $meta_data) : array<string|int, array<string|int, mixed>>
Parameters
$entity_data : array<string|int, mixed>

Data from source table.

$meta_data : array<string|int, mixed>

Data from meta table.

Return values
array<string|int, array<string|int, mixed>> — Validated and combined data with errors.

process_and_sanitize_entity_data()

Helper method to sanitize core source table.

private process_and_sanitize_entity_data(array<string|int, mixed> &$sanitized_entity_data, array<string|int, mixed> &$error_records, array<string|int, mixed> $entity_data) : void
Parameters
$sanitized_entity_data : array<string|int, mixed>

Array containing sanitized data for insertion.

$error_records : array<string|int, mixed>

Error records.

$entity_data : array<string|int, mixed>

Original source data.

Return values
void —

process_insert_batch()

Process batch for insertion into destination table.

private process_insert_batch(array<string|int, mixed> $batch) : void
Parameters
$batch : array<string|int, mixed>

Data to insert, will be of the form as returned by data in fetch_data_for_migration_for_ids.

Return values
void —

process_update_batch()

Process batch for update into destination table.

private process_update_batch(array<string|int, mixed> $batch, array<string|int, mixed> $ids_mapping) : void
Parameters
$batch : array<string|int, mixed>

Data to insert, will be of the form as returned by data in fetch_data_for_migration_for_ids.

$ids_mapping : array<string|int, mixed>

Maps rows to update data with their original IDs.

Return values
void —

processs_and_sanitize_meta_data()

Helper method to sanitize soure meta data.

private processs_and_sanitize_meta_data(array<string|int, mixed> &$sanitized_entity_data, array<string|int, mixed> &$error_records, array<string|int, mixed> $meta_data) : void
Parameters
$sanitized_entity_data : array<string|int, mixed>

Array containing sanitized data for insertion.

$error_records : array<string|int, mixed>

Error records.

$meta_data : array<string|int, mixed>

Original source data.

Return values
void —

validate_data()

Validate and transform data so that we catch as many errors as possible before inserting.

private validate_data(mixed $value, string $type) : float|int|mixed|string|WP_Error
Parameters
$value : mixed

Actual data value.

$type : string

Type of data, could be decimal, int, date, string.

Return values
float|int|mixed|string|WP_Error —

verify_entity_columns()

Helper method to verify and compare core columns.

private verify_entity_columns(array<string|int, mixed> $row, array<string|int, mixed> $failed_ids) : array<string|int, mixed>
Parameters
$row : array<string|int, mixed>

Both migrated and source data for a single row.

$failed_ids : array<string|int, mixed>

Array of failed IDs.

Return values
array<string|int, mixed> — Array of failed IDs if any, along with columns/meta_key names.

verify_meta_columns()

Helper method to verify meta columns.

private verify_meta_columns(array<string|int, mixed> $row, array<string|int, mixed> $failed_ids) : array<string|int, mixed>
Parameters
$row : array<string|int, mixed>

Both migrated and source data for a single row.

$failed_ids : array<string|int, mixed>

Array of failed IDs.

Return values
array<string|int, mixed> — Array of failed IDs if any, along with columns/meta_key names.