From 57b1bd23403a6fceb44f9a01172775e074a5bc5f Mon Sep 17 00:00:00 2001 From: Nestor Soriano Date: Fri, 29 Apr 2022 10:41:17 +0200 Subject: [PATCH] Improve the readability of classes in Database\Migrations\CustomOrderTable - Add meaningful docblock comments for the classes - Add type ints for parameters and return values in all mehtods --- .../MetaToCustomTableMigrator.php | 39 ++++++++++--------- .../MetaToMetaTableMigrator.php | 21 +++++----- .../PostMetaToOrderMetaMigrator.php | 5 ++- .../PostToOrderAddressTableMigrator.php | 11 +++--- .../PostToOrderOpTableMigrator.php | 9 +++-- .../PostToOrderTableMigrator.php | 10 +++-- .../Migrations/MigrationErrorLogger.php | 2 - .../Database/Migrations/MigrationHelper.php | 10 ++--- 8 files changed, 54 insertions(+), 53 deletions(-) diff --git a/plugins/woocommerce/src/Database/Migrations/CustomOrderTable/MetaToCustomTableMigrator.php b/plugins/woocommerce/src/Database/Migrations/CustomOrderTable/MetaToCustomTableMigrator.php index 75c758ec2ef..229c17ec269 100644 --- a/plugins/woocommerce/src/Database/Migrations/CustomOrderTable/MetaToCustomTableMigrator.php +++ b/plugins/woocommerce/src/Database/Migrations/CustomOrderTable/MetaToCustomTableMigrator.php @@ -8,7 +8,8 @@ namespace Automattic\WooCommerce\Database\Migrations\CustomOrderTable; use Automattic\WooCommerce\Database\Migrations\MigrationHelper; /** - * Class MetaToCustomTableMigrator. + * Base class for implementing migrations from the standard WordPress meta table + * to custom structured tables. * * @package Automattic\WooCommerce\Database\Migrations\CustomOrderTable */ @@ -78,7 +79,7 @@ abstract class MetaToCustomTableMigrator { 'primary_key_type' => $type bool|int|string|decimal ) */ - abstract public function get_schema_config(); + abstract public function get_schema_config(): array; /** * Specify column config from the source table. @@ -95,7 +96,7 @@ abstract class MetaToCustomTableMigrator { * .... * ). */ - abstract public function get_core_column_mapping(); + abstract public function get_core_column_mapping(): array; /** * Specify meta keys config from source meta table. @@ -112,7 +113,7 @@ abstract class MetaToCustomTableMigrator { * .... * ). */ - abstract public function get_meta_column_config(); + abstract public function get_meta_column_config(): array; /** * Generate SQL for data insertion. @@ -125,7 +126,7 @@ abstract class MetaToCustomTableMigrator { * ($value for row 2) * ... */ - public function generate_insert_sql_for_batch( $batch ) { + public function generate_insert_sql_for_batch( array $batch ): string { $table = $this->schema_config['destination']['table_name']; list( $value_sql, $column_sql ) = $this->generate_column_clauses( array_merge( $this->core_column_mapping, $this->meta_column_mapping ), $batch ); @@ -150,7 +151,7 @@ abstract class MetaToCustomTableMigrator { * $column2 = VALUES($column2) * ... */ - public function generate_update_sql_for_batch( $batch, $entity_row_mapping ) { + public function generate_update_sql_for_batch( array $batch, array $entity_row_mapping ): string { $table = $this->schema_config['destination']['table_name']; $destination_primary_id_schema = $this->get_destination_table_primary_id_schema(); @@ -173,7 +174,7 @@ abstract class MetaToCustomTableMigrator { * * @return array[] Schema for primary ID column. */ - protected function get_destination_table_primary_id_schema() { + protected function get_destination_table_primary_id_schema(): array { return array( 'destination_primary_key' => array( 'destination' => $this->schema_config['destination']['primary_key'], @@ -190,7 +191,7 @@ abstract class MetaToCustomTableMigrator { * * @return array SQL clause for values, columns placeholders, and columns. */ - protected function generate_column_clauses( $columns_schema, $batch ) { + protected function generate_column_clauses( array $columns_schema, array $batch ): array { global $wpdb; $columns = array(); @@ -229,7 +230,7 @@ abstract class MetaToCustomTableMigrator { * * @return array List of errors happened during migration. */ - public function process_migration_batch_for_ids( $entity_ids ) { + public function process_migration_batch_for_ids( array $entity_ids ): array { $data = $this->fetch_data_for_migration_for_ids( $entity_ids ); foreach ( $data['errors'] as $entity_id => $error ) { @@ -259,7 +260,7 @@ abstract class MetaToCustomTableMigrator { * * @param array $batch Data to insert, will be of the form as returned by `data` in `fetch_data_for_migration_for_ids`. */ - protected function process_insert_batch( $batch ) { + protected function process_insert_batch( array $batch ): void { global $wpdb; if ( 0 === count( $batch ) ) { return; @@ -279,7 +280,7 @@ abstract class MetaToCustomTableMigrator { * @param array $batch Data to insert, will be of the form as returned by `data` in `fetch_data_for_migration_for_ids`. * @param array $already_migrated Maps rows to update data with their original IDs. */ - protected function process_update_batch( $batch, $already_migrated ) { + protected function process_update_batch( array $batch, array $already_migrated ): void { global $wpdb; if ( 0 === count( $batch ) ) { return; @@ -310,7 +311,7 @@ abstract class MetaToCustomTableMigrator { * ..., * ) */ - public function fetch_data_for_migration_for_ids( $entity_ids ) { + public function fetch_data_for_migration_for_ids( array $entity_ids ): array { global $wpdb; if ( empty( $entity_ids ) ) { @@ -352,7 +353,7 @@ abstract class MetaToCustomTableMigrator { * ... * ) */ - public function get_already_migrated_records( $entity_ids ) { + public function get_already_migrated_records( array $entity_ids ): array { global $wpdb; $source_table = $this->schema_config['source']['entity']['table_name']; $source_destination_join_column = $this->schema_config['source']['entity']['destination_rel_column']; @@ -389,7 +390,7 @@ WHERE source.`$source_primary_key_column` IN ( $entity_id_placeholder ) * * @return string Query that can be used to fetch data. */ - protected function build_entity_table_query( $entity_ids ) { + protected function build_entity_table_query( array $entity_ids ): string { global $wpdb; $source_entity_table = $this->schema_config['source']['entity']['table_name']; $source_meta_rel_id_column = "`$source_entity_table`.`{$this->schema_config['source']['entity']['meta_rel_column']}`"; @@ -430,7 +431,7 @@ WHERE $where_clause; * * @return string Query for fetching meta data. */ - protected function build_meta_data_query( $entity_ids ) { + protected function build_meta_data_query( array $entity_ids ): string { global $wpdb; $meta_table = $this->schema_config['source']['meta']['table_name']; $meta_keys = array_keys( $this->meta_column_mapping ); @@ -469,7 +470,7 @@ WHERE * * @return array[] Validated and combined data with errors. */ - private function process_and_sanitize_data( $entity_data, $meta_data ) { + private function process_and_sanitize_data( array $entity_data, array $meta_data ): array { $sanitized_entity_data = array(); $error_records = array(); $this->process_and_sanitize_entity_data( $sanitized_entity_data, $error_records, $entity_data ); @@ -488,7 +489,7 @@ WHERE * @param array $error_records Error records. * @param array $entity_data Original source data. */ - private function process_and_sanitize_entity_data( &$sanitized_entity_data, &$error_records, $entity_data ) { + private function process_and_sanitize_entity_data( array &$sanitized_entity_data, array &$error_records, array $entity_data ): void { foreach ( $entity_data as $entity ) { $row_data = array(); foreach ( $this->core_column_mapping as $column_name => $schema ) { @@ -512,7 +513,7 @@ WHERE * @param array $error_records Error records. * @param array $meta_data Original source data. */ - private function processs_and_sanitize_meta_data( &$sanitized_entity_data, &$error_records, $meta_data ) { + private function processs_and_sanitize_meta_data( array &$sanitized_entity_data, array &$error_records, array $meta_data ): void { foreach ( $meta_data as $datum ) { $column_schema = $this->meta_column_mapping[ $datum->meta_key ]; $value = $this->validate_data( $datum->meta_value, $column_schema['type'] ); @@ -532,7 +533,7 @@ WHERE * * @return float|int|mixed|string|\WP_Error */ - private function validate_data( $value, $type ) { + private function validate_data( $value, string $type ) { switch ( $type ) { case 'decimal': $value = (float) $value; diff --git a/plugins/woocommerce/src/Database/Migrations/CustomOrderTable/MetaToMetaTableMigrator.php b/plugins/woocommerce/src/Database/Migrations/CustomOrderTable/MetaToMetaTableMigrator.php index 40a0309296b..6fa5ec84323 100644 --- a/plugins/woocommerce/src/Database/Migrations/CustomOrderTable/MetaToMetaTableMigrator.php +++ b/plugins/woocommerce/src/Database/Migrations/CustomOrderTable/MetaToMetaTableMigrator.php @@ -8,9 +8,8 @@ namespace Automattic\WooCommerce\Database\Migrations\CustomOrderTable; use Automattic\WooCommerce\Database\Migrations\MigrationHelper; /** - * Class MetaToMetaTableMigrator. - * - * Generic class for powering migrations from one meta table to another table. + * Base class for implementing migrations from the standard WordPress meta table + * to custom meta (key-value pairs) tables. * * @package Automattic\WooCommerce\Database\Migrations\CustomOrderTable */ @@ -61,7 +60,7 @@ abstract class MetaToMetaTableMigrator { * ), * ) */ - abstract public function get_meta_config(); + abstract public function get_meta_config(): array; /** * MetaToMetaTableMigrator constructor. @@ -76,7 +75,7 @@ abstract class MetaToMetaTableMigrator { * * @param array $entity_ids Entity IDs to process migration for. */ - public function process_migration_batch_for_ids( $entity_ids ) { + public function process_migration_batch_for_ids( array $entity_ids ): void { global $wpdb; $to_migrate = $this->fetch_data_for_migration_for_ids( $entity_ids ); @@ -111,7 +110,7 @@ abstract class MetaToMetaTableMigrator { * * @return string Query to update batch records. */ - public function generate_update_sql_for_batch( $batch ) { + public function generate_update_sql_for_batch( array $batch ): string { global $wpdb; $table = $this->schema_config['destination']['meta']['table_name']; @@ -149,7 +148,7 @@ abstract class MetaToMetaTableMigrator { * * @return string Insert SQL query. */ - public function generate_insert_sql_for_batch( $batch ) { + public function generate_insert_sql_for_batch( array $batch ): string { global $wpdb; $table = $this->schema_config['destination']['meta']['table_name']; @@ -196,7 +195,7 @@ abstract class MetaToMetaTableMigrator { * ..., * ) */ - public function fetch_data_for_migration_for_ids( $entity_ids ) { + public function fetch_data_for_migration_for_ids( array $entity_ids ): array { global $wpdb; if ( empty( $entity_ids ) ) { return array( @@ -241,7 +240,7 @@ abstract class MetaToMetaTableMigrator { * * @return array Already migrated records. */ - private function get_already_migrated_records( $entity_ids ) { + private function get_already_migrated_records( array $entity_ids ): array { global $wpdb; $destination_table_name = $this->schema_config['destination']['meta']['table_name']; @@ -298,7 +297,7 @@ WHERE destination.$destination_entity_id_column in ( $entity_ids_placeholder ) O * * @return array[] Returns two arrays, first for records to migrate, and second for records to upgrade. */ - private function classify_update_insert_records( $to_migrate, $already_migrated ) { + private function classify_update_insert_records( array $to_migrate, array $already_migrated ): array { $to_update = array(); $to_insert = array(); @@ -347,7 +346,7 @@ WHERE destination.$destination_entity_id_column in ( $entity_ids_placeholder ) O * * @return string Query that can be used to fetch data. */ - private function build_meta_table_query( $entity_ids ) { + private function build_meta_table_query( array $entity_ids ): string { global $wpdb; $source_meta_table = $this->schema_config['source']['meta']['table_name']; $source_meta_key_column = $this->schema_config['source']['meta']['meta_key_column']; diff --git a/plugins/woocommerce/src/Database/Migrations/CustomOrderTable/PostMetaToOrderMetaMigrator.php b/plugins/woocommerce/src/Database/Migrations/CustomOrderTable/PostMetaToOrderMetaMigrator.php index 6b859778538..457b47f2798 100644 --- a/plugins/woocommerce/src/Database/Migrations/CustomOrderTable/PostMetaToOrderMetaMigrator.php +++ b/plugins/woocommerce/src/Database/Migrations/CustomOrderTable/PostMetaToOrderMetaMigrator.php @@ -6,7 +6,8 @@ namespace Automattic\WooCommerce\Database\Migrations\CustomOrderTable; /** - * Class PostMetaToOrderMetaMigrator. + * Helper class to migrate records from the WordPress post meta table + * to the custom orders meta table. * * @package Automattic\WooCommerce\Database\Migrations\CustomOrderTable */ @@ -34,7 +35,7 @@ class PostMetaToOrderMetaMigrator extends MetaToMetaTableMigrator { * * @return array Meta data migration config. */ - public function get_meta_config() { + public function get_meta_config(): array { global $wpdb; // TODO: Remove hardcoding. $this->table_names = array( diff --git a/plugins/woocommerce/src/Database/Migrations/CustomOrderTable/PostToOrderAddressTableMigrator.php b/plugins/woocommerce/src/Database/Migrations/CustomOrderTable/PostToOrderAddressTableMigrator.php index d56ede044bf..549936b3a9e 100644 --- a/plugins/woocommerce/src/Database/Migrations/CustomOrderTable/PostToOrderAddressTableMigrator.php +++ b/plugins/woocommerce/src/Database/Migrations/CustomOrderTable/PostToOrderAddressTableMigrator.php @@ -6,7 +6,8 @@ namespace Automattic\WooCommerce\Database\Migrations\CustomOrderTable; /** - * Class PostToOrderAddressTableMigrator + * Helper class to migrate records from the WordPress post table + * to the custom order addresses table. * * @package Automattic\WooCommerce\Database\Migrations\CustomOrderTable */ @@ -33,7 +34,7 @@ class PostToOrderAddressTableMigrator extends MetaToCustomTableMigrator { * * @return array Config. */ - public function get_schema_config() { + public function get_schema_config(): array { global $wpdb; // TODO: Remove hardcoding. $this->table_names = array( @@ -72,7 +73,7 @@ class PostToOrderAddressTableMigrator extends MetaToCustomTableMigrator { * * @return \string[][] Config. */ - public function get_core_column_mapping() { + public function get_core_column_mapping(): array { $type = $this->type; return array( @@ -93,7 +94,7 @@ class PostToOrderAddressTableMigrator extends MetaToCustomTableMigrator { * * @return \string[][] Config. */ - public function get_meta_column_config() { + public function get_meta_column_config(): array { $type = $this->type; return array( @@ -158,7 +159,7 @@ class PostToOrderAddressTableMigrator extends MetaToCustomTableMigrator { * ... * ) */ - public function get_already_migrated_records( $entity_ids ) { + public function get_already_migrated_records( array $entity_ids ): array { global $wpdb; $source_table = $this->schema_config['source']['entity']['table_name']; $source_destination_join_column = $this->schema_config['source']['entity']['destination_rel_column']; diff --git a/plugins/woocommerce/src/Database/Migrations/CustomOrderTable/PostToOrderOpTableMigrator.php b/plugins/woocommerce/src/Database/Migrations/CustomOrderTable/PostToOrderOpTableMigrator.php index 3f0a9bccf3d..86aa2ed05c8 100644 --- a/plugins/woocommerce/src/Database/Migrations/CustomOrderTable/PostToOrderOpTableMigrator.php +++ b/plugins/woocommerce/src/Database/Migrations/CustomOrderTable/PostToOrderOpTableMigrator.php @@ -6,7 +6,8 @@ namespace Automattic\WooCommerce\Database\Migrations\CustomOrderTable; /** - * Class PostToOrderOpTableMigrator + * Helper class to migrate records from the WordPress post table + * to the custom order operations table. * * @package Automattic\WooCommerce\Database\Migrations\CustomOrderTable */ @@ -17,7 +18,7 @@ class PostToOrderOpTableMigrator extends MetaToCustomTableMigrator { * * @return array Config. */ - public function get_schema_config() { + public function get_schema_config(): array { global $wpdb; // TODO: Remove hardcoding. $this->table_names = array( @@ -57,7 +58,7 @@ class PostToOrderOpTableMigrator extends MetaToCustomTableMigrator { * * @return \string[][] Config. */ - public function get_core_column_mapping() { + public function get_core_column_mapping(): array { return array( 'id' => array( 'type' => 'int', @@ -72,7 +73,7 @@ class PostToOrderOpTableMigrator extends MetaToCustomTableMigrator { * * @return \string[][] Config. */ - public function get_meta_column_config() { + public function get_meta_column_config(): array { return array( '_created_via' => array( 'type' => 'string', diff --git a/plugins/woocommerce/src/Database/Migrations/CustomOrderTable/PostToOrderTableMigrator.php b/plugins/woocommerce/src/Database/Migrations/CustomOrderTable/PostToOrderTableMigrator.php index 39c37ac4801..7e0e401e8c9 100644 --- a/plugins/woocommerce/src/Database/Migrations/CustomOrderTable/PostToOrderTableMigrator.php +++ b/plugins/woocommerce/src/Database/Migrations/CustomOrderTable/PostToOrderTableMigrator.php @@ -6,7 +6,9 @@ namespace Automattic\WooCommerce\Database\Migrations\CustomOrderTable; /** - * Class PostToOrderTableMigrator. + * Helper class to migrate records from the WordPress post table + * to the custom order table (and only that table - PostsToOrdersMigrationController + * is used for fully migrating orders). */ class PostToOrderTableMigrator extends MetaToCustomTableMigrator { @@ -15,7 +17,7 @@ class PostToOrderTableMigrator extends MetaToCustomTableMigrator { * * @return array Config. */ - public function get_schema_config() { + public function get_schema_config(): array { global $wpdb; // TODO: Remove hardcoding. @@ -55,7 +57,7 @@ class PostToOrderTableMigrator extends MetaToCustomTableMigrator { * * @return \string[][] Config. */ - public function get_core_column_mapping() { + public function get_core_column_mapping(): array { return array( 'ID' => array( 'type' => 'int', @@ -85,7 +87,7 @@ class PostToOrderTableMigrator extends MetaToCustomTableMigrator { * * @return \string[][] Config. */ - public function get_meta_column_config() { + public function get_meta_column_config(): array { return array( '_order_currency' => array( 'type' => 'string', diff --git a/plugins/woocommerce/src/Database/Migrations/MigrationErrorLogger.php b/plugins/woocommerce/src/Database/Migrations/MigrationErrorLogger.php index 191dce8963d..66f92ace374 100644 --- a/plugins/woocommerce/src/Database/Migrations/MigrationErrorLogger.php +++ b/plugins/woocommerce/src/Database/Migrations/MigrationErrorLogger.php @@ -6,8 +6,6 @@ namespace Automattic\WooCommerce\Database\Migrations; /** - * Class MigrationErrorLogger. - * * Error logging for custom table migrations. * * @package Automattic\WooCommerce\Database\Migrations diff --git a/plugins/woocommerce/src/Database/Migrations/MigrationHelper.php b/plugins/woocommerce/src/Database/Migrations/MigrationHelper.php index 60a8f05f83d..68cc2c33708 100644 --- a/plugins/woocommerce/src/Database/Migrations/MigrationHelper.php +++ b/plugins/woocommerce/src/Database/Migrations/MigrationHelper.php @@ -6,8 +6,6 @@ namespace Automattic\WooCommerce\Database\Migrations; /** - * Class MigrationHelper. - * * Helper class to assist with migration related operations. */ class MigrationHelper { @@ -33,7 +31,7 @@ class MigrationHelper { * * @return string Insert clause. */ - public static function get_insert_switch( $switch ) { + public static function get_insert_switch( string $switch ): string { switch ( $switch ) { case 'insert_ignore': $insert_query = 'INSERT IGNORE'; @@ -59,7 +57,7 @@ class MigrationHelper { * * @return array Schema config escaped for backtick. */ - public static function escape_schema_for_backtick( $schema_config ) { + public static function escape_schema_for_backtick( array $schema_config ): array { array_walk( $schema_config['source']['entity'], array( self::class, 'escape_and_add_backtick' ) ); array_walk( $schema_config['source']['meta'], array( self::class, 'escape_and_add_backtick' ) ); array_walk( $schema_config['destination'], array( self::class, 'escape_and_add_backtick' ) ); @@ -85,7 +83,7 @@ class MigrationHelper { * * @return string $wpdb placeholder. */ - public static function get_wpdb_placeholder_for_type( $type ) { + public static function get_wpdb_placeholder_for_type( string $type ): string { return self::$wpdb_placeholder_for_type[ $type ]; } @@ -96,7 +94,7 @@ class MigrationHelper { * * @return string SQL clause for INSERT...ON DUPLICATE KEY UPDATE */ - public static function generate_on_duplicate_statement_clause( $columns ) { + public static function generate_on_duplicate_statement_clause( array $columns ): string { $update_value_statements = array(); foreach ( $columns as $column ) { $update_value_statements[] = "$column = VALUES( $column )";