Skip to content

Commit 05041ab

Browse files
swissspidyswissspidy
committed
Add some docblocks
1 parent 21c0b81 commit 05041ab

2 files changed

Lines changed: 103 additions & 24 deletions

File tree

‎src/Search_Replace_Command.php‎

Lines changed: 91 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -611,6 +611,14 @@ function ( $e ) {
611611
}
612612
}
613613

614+
/**
615+
* Exports a table's data with search and replace.
616+
*
617+
* @param string $table The table to export.
618+
* @param string $old The string to search for.
619+
* @param string $new The string to replace with.
620+
* @return array A tuple containing the report array and the total number of rows.
621+
*/
614622
private function php_export_table( $table, $old, $new ) {
615623
list( $primary_keys, $columns, $all_columns ) = self::get_columns( $table );
616624

@@ -675,6 +683,17 @@ private function php_export_table( $table, $old, $new ) {
675683
return array( $table_report, $total_rows );
676684
}
677685

686+
/**
687+
* Performs a search and replace on a column using SQL.
688+
*
689+
* @param string $col The column to perform the search-replace on.
690+
* @param string[] $primary_keys The primary keys of the table.
691+
* @param string $table The table to perform the search-replace on.
692+
* @param string $old The string to search for.
693+
* @param string $new The string to replace with.
694+
* @param string[] $clauses The WHERE clauses to apply.
695+
* @return int The number of replacements made.
696+
*/
678697
private function sql_handle_col( $col, $primary_keys, $table, $old, $new, $clauses ) {
679698
global $wpdb;
680699

@@ -704,6 +723,17 @@ private function sql_handle_col( $col, $primary_keys, $table, $old, $new, $claus
704723
return $count;
705724
}
706725

726+
/**
727+
* Performs a search and replace on a column using PHP.
728+
*
729+
* @param string $col The column to perform the search-replace on.
730+
* @param string[] $primary_keys The primary keys of the table.
731+
* @param string $table The table to perform the search-replace on.
732+
* @param string $old The string to search for.
733+
* @param string $new The string to replace with.
734+
* @param string[] $additional_where The additional WHERE clauses to apply.
735+
* @return int The number of replacements made.
736+
*/
707737
private function php_handle_col( $col, $primary_keys, $table, $old, $new, $additional_where ) {
708738
global $wpdb;
709739

@@ -818,6 +848,12 @@ static function ( $key ) {
818848
return $count;
819849
}
820850

851+
/**
852+
* Writes a set of rows to the export file as SQL INSERT statements.
853+
*
854+
* @param string $table The table to write the rows for.
855+
* @param array $rows The rows to write.
856+
*/
821857
private function write_sql_row_fields( $table, $rows ) {
822858
global $wpdb;
823859

@@ -888,6 +924,12 @@ private function write_sql_row_fields( $table, $rows ) {
888924
}
889925
}
890926

927+
/**
928+
* Gets the primary keys, text columns, and all columns for a table.
929+
*
930+
* @param string $table The table to get the columns for.
931+
* @return array A tuple containing the primary keys, text columns, and all columns.
932+
*/
891933
private static function get_columns( $table ) {
892934
global $wpdb;
893935

@@ -915,6 +957,12 @@ private static function get_columns( $table ) {
915957
return array( $primary_keys, $text_columns, $all_columns );
916958
}
917959

960+
/**
961+
* Checks if a column type is a text type.
962+
*
963+
* @param string $type The column type to check.
964+
* @return bool Whether the column type is a text type.
965+
*/
918966
private static function is_text_col( $type ) {
919967
foreach ( array( 'text', 'varchar' ) as $token ) {
920968
if ( false !== stripos( $type, $token ) ) {
@@ -925,6 +973,12 @@ private static function is_text_col( $type ) {
925973
return false;
926974
}
927975

976+
/**
977+
* Escapes a string for a MySQL LIKE statement.
978+
*
979+
* @param string $old The string to escape.
980+
* @return string The escaped string.
981+
*/
928982
private static function esc_like( $old ) {
929983
global $wpdb;
930984

@@ -1020,14 +1074,15 @@ private function get_colors( $assoc_args, $colors ) {
10201074
return $colors;
10211075
}
10221076

1023-
/*
1077+
/**
10241078
* Logs the difference between old match and new replacement for SQL replacement.
10251079
*
1026-
* @param string $col Column being processed.
1027-
* @param array $primary_keys Primary keys for table.
1028-
* @param string $table Table being processed.
1029-
* @param string $old Old value to match.
1030-
* @param string $new New value to replace the old value with.
1080+
* @param string $col Column being processed.
1081+
* @param string[] $primary_keys Primary keys for table.
1082+
* @param string $table Table being processed.
1083+
* @param string $old Old value to match.
1084+
* @param string $new New value to replace the old value with.
1085+
* @param string[] $clauses The WHERE clauses to apply.
10311086
* @return int Count of changed rows.
10321087
*/
10331088
private function log_sql_diff( $col, $primary_keys, $table, $old, $new, $clauses ) {
@@ -1062,15 +1117,15 @@ private function log_sql_diff( $col, $primary_keys, $table, $old, $new, $clauses
10621117
return count( $results );
10631118
}
10641119

1065-
/*
1120+
/**
10661121
* Logs the difference between old matches and new replacements at the end of a PHP (regex) replacement of a database row.
10671122
*
1068-
* @param string $col Column being processed.
1069-
* @param array $keys Associative array (or object) of primary key names and their values for the row being processed.
1070-
* @param string $table Table being processed.
1071-
* @param string $old Old value to match.
1072-
* @param string $new New value to replace the old value with.
1073-
* @param array $log_data Array of data strings before replacements.
1123+
* @param string $col Column being processed.
1124+
* @param array|object $keys Associative array (or object) of primary key names and their values for the row being processed.
1125+
* @param string $table Table being processed.
1126+
* @param string $old Old value to match.
1127+
* @param string $new New value to replace the old value with.
1128+
* @param string[] $log_data Array of data strings before replacements.
10741129
*/
10751130
private function log_php_diff( $col, $keys, $table, $old, $new, $log_data ) {
10761131
if ( $this->regex ) {
@@ -1196,14 +1251,14 @@ static function ( $m ) use ( $matches ) {
11961251
return array( $old_bits, $new_bits );
11971252
}
11981253

1199-
/*
1254+
/**
12001255
* Outputs the log strings.
12011256
*
1202-
* @param string $col Column being processed.
1203-
* @param array $keys Associative array (or object) of primary key names and their values for the row being processed.
1204-
* @param string $table Table being processed.
1205-
* @param array $old_bits Array of old match log strings.
1206-
* @param array $new_bits Array of new replacement log strings.
1257+
* @param string $col Column being processed.
1258+
* @param array|object $keys Associative array (or object) of primary key names and their values for the row being processed.
1259+
* @param string $table Table being processed.
1260+
* @param string[] $old_bits Array of old match log strings.
1261+
* @param string[] $new_bits Array of new replacement log strings.
12071262
*/
12081263
private function log_write( $col, $keys, $table, $old_bits, $new_bits ) {
12091264
if ( ! $this->log_handle ) {
@@ -1226,9 +1281,15 @@ private function log_write( $col, $keys, $table, $old_bits, $new_bits ) {
12261281
fwrite( $this->log_handle, "{$table_column_id_log}\n{$old_log}\n{$new_log}\n" );
12271282
}
12281283

1284+
/**
1285+
* Develops the WHERE specifications from a string.
1286+
*
1287+
* @param string|null $str_specs The string of WHERE specifications.
1288+
* @return array The WHERE specifications as an array.
1289+
*/
12291290
private function develop_where_specs( $str_specs ) {
12301291
global $wpdb;
1231-
$specs = array_filter( explode( ';', $str_specs ) );
1292+
$specs = array_filter( explode( ';', (string) $str_specs ) );
12321293
$clauses = [];
12331294
foreach ( $specs as $spec ) {
12341295
list( $tables, $cols, $conditions ) = explode( ':', $spec, 3 );
@@ -1244,12 +1305,22 @@ private function develop_where_specs( $str_specs ) {
12441305
return $clauses;
12451306
}
12461307

1308+
/**
1309+
* Excludes revisions from the search-replace operation.
1310+
*/
12471311
private function no_revision() {
12481312
global $wpdb;
12491313
$this->where[ $wpdb->posts ]['*'][] = self::esc_sql_ident( 'post_status' ) . '=' . self::esc_sql_value( 'publish' );
12501314
$this->where[ $wpdb->postmeta ]['*'][] = self::esc_sql_ident( 'post_id' ) . ' IN ( SELECT ID FROM ' . $wpdb->posts . ' WHERE ' . self::esc_sql_ident( 'post_status' ) . '=' . self::esc_sql_value( 'publish' ) . ')';
12511315
}
12521316

1317+
/**
1318+
* Gets the WHERE clauses for a given table and column.
1319+
*
1320+
* @param string $table The table to get the clauses for.
1321+
* @param string|null $column The column to get the clauses for.
1322+
* @return string[] The WHERE clauses.
1323+
*/
12531324
private function get_clauses( $table, $column = null ) {
12541325
return array_filter(
12551326
array_merge(

‎src/WP_CLI/SearchReplacer.php‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -73,6 +73,7 @@ class SearchReplacer {
7373
* @param string $regex_delimiter Delimiter for regular expression.
7474
* @param bool $logging Whether logging.
7575
* @param integer $regex_limit The maximum possible replacements for each pattern in each subject string.
76+
* @param callable|string|false $callback The callback function to invoke.
7677
*/
7778
public function __construct( $from, $to, $recurse_objects = false, $regex = false, $regex_flags = '', $regex_delimiter = '/', $logging = false, $regex_limit = -1, $callback = false ) {
7879
$this->from = $from;
@@ -97,16 +98,23 @@ public function __construct( $from, $to, $recurse_objects = false, $regex = fals
9798
*
9899
* @param array|string $data The data to operate on.
99100
* @param bool $serialised Does the value of $data need to be unserialized?
101+
* @param array $opts Options for the callback.
100102
*
101-
* @return array The original array with all elements replaced as needed.
103+
* @return array|string The original array with all elements replaced as needed.
102104
*/
103105
public function run( $data, $serialised = false, $opts = [] ) {
104106
return $this->run_recursively( $data, $serialised, 0, [], $opts );
105107
}
106108

107109
/**
108-
* @param int $recursion_level Current recursion depth within the original data.
109-
* @param array $visited_data Data that has been seen in previous recursion iterations.
110+
* The main workhorse of the run method.
111+
*
112+
* @param mixed $data The data to operate on.
113+
* @param bool $serialised Does the value of $data need to be unserialized?
114+
* @param int $recursion_level Current recursion depth within the original data.
115+
* @param array $visited_data Data that has been seen in previous recursion iterations.
116+
* @param array $opts Options for the callback.
117+
* @return mixed The original data with all elements replaced as needed.
110118
*/
111119
private function run_recursively( $data, $serialised, $recursion_level = 0, $visited_data = array(), $opts = [] ) {
112120

@@ -269,7 +277,7 @@ public function clear_log_data() {
269277
/**
270278
* Get the PCRE error constant name from an error value.
271279
*
272-
* @param integer $error Error code.
280+
* @param int|null $error Error code.
273281
* @return string Error constant name.
274282
*/
275283
private function preg_error_message( $error ) {

0 commit comments

Comments
 (0)