OrdersTableFieldQuery.php
| 1 | <?php |
| 2 | namespace Automattic\WooCommerce\Internal\DataStores\Orders; |
| 3 | |
| 4 | defined( 'ABSPATH' ) || exit; |
| 5 | |
| 6 | /** |
| 7 | * Provides the implementation for `field_query` in {@see OrdersTableQuery} used to build |
| 8 | * complex queries against order fields in the database. |
| 9 | * |
| 10 | * @internal |
| 11 | */ |
| 12 | class OrdersTableFieldQuery { |
| 13 | |
| 14 | /** |
| 15 | * List of valid SQL operators to use as field_query 'compare' values. |
| 16 | * |
| 17 | * @var array |
| 18 | */ |
| 19 | private const VALID_COMPARISON_OPERATORS = array( |
| 20 | '=', |
| 21 | '!=', |
| 22 | 'LIKE', |
| 23 | 'NOT LIKE', |
| 24 | 'IN', |
| 25 | 'NOT IN', |
| 26 | 'EXISTS', |
| 27 | 'NOT EXISTS', |
| 28 | 'RLIKE', |
| 29 | 'REGEXP', |
| 30 | 'NOT REGEXP', |
| 31 | '>', |
| 32 | '>=', |
| 33 | '<', |
| 34 | '<=', |
| 35 | 'BETWEEN', |
| 36 | 'NOT BETWEEN', |
| 37 | ); |
| 38 | |
| 39 | /** |
| 40 | * The original query object. |
| 41 | * |
| 42 | * @var OrdersTableQuery |
| 43 | */ |
| 44 | private $query = null; |
| 45 | |
| 46 | /** |
| 47 | * Determines whether the field query should produce no results due to an invalid argument. |
| 48 | * |
| 49 | * @var boolean |
| 50 | */ |
| 51 | private $force_no_results = false; |
| 52 | |
| 53 | /** |
| 54 | * Holds a sanitized version of the `field_query`. |
| 55 | * |
| 56 | * @var array |
| 57 | */ |
| 58 | private $queries = array(); |
| 59 | |
| 60 | /** |
| 61 | * JOIN clauses to add to the main SQL query. |
| 62 | * |
| 63 | * @var array |
| 64 | */ |
| 65 | private $join = array(); |
| 66 | |
| 67 | /** |
| 68 | * WHERE clauses to add to the main SQL query. |
| 69 | * |
| 70 | * @var array |
| 71 | */ |
| 72 | private $where = array(); |
| 73 | |
| 74 | /** |
| 75 | * Table aliases in use by the field query. Used to keep track of JOINs and optimize when possible. |
| 76 | * |
| 77 | * @var array |
| 78 | */ |
| 79 | private $table_aliases = array(); |
| 80 | |
| 81 | |
| 82 | /** |
| 83 | * Constructor. |
| 84 | * |
| 85 | * @param OrdersTableQuery $q The main query being performed. |
| 86 | */ |
| 87 | public function __construct( OrdersTableQuery $q ) { |
| 88 | $field_query = $q->get( 'field_query' ); |
| 89 | |
| 90 | if ( ! $field_query || ! is_array( $field_query ) ) { |
| 91 | return; |
| 92 | } |
| 93 | |
| 94 | $this->query = $q; |
| 95 | $this->queries = $this->sanitize_query( $field_query ); |
| 96 | $this->where = ( ! $this->force_no_results ) ? $this->process( $this->queries ) : '1=0'; |
| 97 | } |
| 98 | |
| 99 | /** |
| 100 | * Sanitizes the field_query argument. |
| 101 | * |
| 102 | * @param array $q A field_query array. |
| 103 | * @return array A sanitized field query array. |
| 104 | * @throws \Exception When field table info is missing. |
| 105 | */ |
| 106 | private function sanitize_query( array $q ) { |
| 107 | $sanitized = array(); |
| 108 | |
| 109 | foreach ( $q as $key => $arg ) { |
| 110 | if ( 'relation' === $key ) { |
| 111 | $relation = $arg; |
| 112 | } elseif ( ! is_array( $arg ) ) { |
| 113 | continue; |
| 114 | } elseif ( $this->is_atomic( $arg ) ) { |
| 115 | if ( isset( $arg['value'] ) && array() === $arg['value'] ) { |
| 116 | continue; |
| 117 | } |
| 118 | |
| 119 | // Sanitize 'compare'. |
| 120 | $arg['compare'] = strtoupper( $arg['compare'] ?? '=' ); |
| 121 | $arg['compare'] = in_array( $arg['compare'], self::VALID_COMPARISON_OPERATORS, true ) ? $arg['compare'] : '='; |
| 122 | |
| 123 | if ( '=' === $arg['compare'] && isset( $arg['value'] ) && is_array( $arg['value'] ) ) { |
| 124 | $arg['compare'] = 'IN'; |
| 125 | } |
| 126 | |
| 127 | // Sanitize 'cast'. |
| 128 | $arg['cast'] = $this->sanitize_cast_type( $arg['type'] ?? '' ); |
| 129 | |
| 130 | $field_info = $this->query->get_field_mapping_info( $arg['field'] ); |
| 131 | if ( ! $field_info ) { |
| 132 | $this->force_no_results = true; |
| 133 | continue; |
| 134 | } |
| 135 | |
| 136 | $arg = array_merge( $arg, $field_info ); |
| 137 | |
| 138 | $sanitized[ $key ] = $arg; |
| 139 | } else { |
| 140 | $sanitized_arg = $this->sanitize_query( $arg ); |
| 141 | |
| 142 | if ( $sanitized_arg ) { |
| 143 | $sanitized[ $key ] = $sanitized_arg; |
| 144 | } |
| 145 | } |
| 146 | } |
| 147 | |
| 148 | if ( $sanitized ) { |
| 149 | $sanitized['relation'] = 1 === count( $sanitized ) ? 'OR' : $this->sanitize_relation( $relation ?? 'AND' ); |
| 150 | } |
| 151 | |
| 152 | return $sanitized; |
| 153 | } |
| 154 | |
| 155 | /** |
| 156 | * Makes sure we use an AND or OR relation. Defaults to AND. |
| 157 | * |
| 158 | * @param string $relation An unsanitized relation prop. |
| 159 | * @return string |
| 160 | */ |
| 161 | private function sanitize_relation( string $relation ): string { |
| 162 | if ( ! empty( $relation ) && 'OR' === strtoupper( $relation ) ) { |
| 163 | return 'OR'; |
| 164 | } |
| 165 | |
| 166 | return 'AND'; |
| 167 | } |
| 168 | |
| 169 | /** |
| 170 | * Processes field_query entries and generates the necessary table aliases, JOIN statements and WHERE conditions. |
| 171 | * |
| 172 | * @param array $q A field query. |
| 173 | * @return string An SQL WHERE statement. |
| 174 | */ |
| 175 | private function process( array $q ) { |
| 176 | $where = ''; |
| 177 | |
| 178 | if ( empty( $q ) ) { |
| 179 | return $where; |
| 180 | } |
| 181 | |
| 182 | if ( $this->is_atomic( $q ) ) { |
| 183 | $q['alias'] = $this->find_or_create_table_alias_for_clause( $q ); |
| 184 | $where = $this->generate_where_for_clause( $q ); |
| 185 | } else { |
| 186 | $relation = $q['relation']; |
| 187 | unset( $q['relation'] ); |
| 188 | $chunks = array(); |
| 189 | foreach ( $q as $query ) { |
| 190 | $chunks[] = $this->process( $query ); |
| 191 | } |
| 192 | |
| 193 | if ( 1 === count( $chunks ) ) { |
| 194 | $where = $chunks[0]; |
| 195 | } else { |
| 196 | $where = '(' . implode( " {$relation} ", $chunks ) . ')'; |
| 197 | } |
| 198 | } |
| 199 | |
| 200 | return $where; |
| 201 | } |
| 202 | |
| 203 | /** |
| 204 | * Checks whether a given field_query clause is atomic or not (i.e. not nested). |
| 205 | * |
| 206 | * @param array $q The field_query clause. |
| 207 | * @return boolean TRUE if atomic, FALSE otherwise. |
| 208 | */ |
| 209 | private function is_atomic( $q ) { |
| 210 | return isset( $q['field'] ); |
| 211 | } |
| 212 | |
| 213 | /** |
| 214 | * Finds a common table alias that the field_query clause can use, or creates one. |
| 215 | * |
| 216 | * @param array $q An atomic field_query clause. |
| 217 | * @return string A table alias for use in an SQL JOIN clause. |
| 218 | * @throws \Exception When table info for clause is missing. |
| 219 | */ |
| 220 | private function find_or_create_table_alias_for_clause( $q ) { |
| 221 | global $wpdb; |
| 222 | |
| 223 | if ( ! empty( $q['alias'] ) ) { |
| 224 | return $q['alias']; |
| 225 | } |
| 226 | |
| 227 | if ( empty( $q['table'] ) || empty( $q['column'] ) ) { |
| 228 | throw new \Exception( __( 'Missing table info for query arg.', 'woocommerce' ) ); |
| 229 | } |
| 230 | |
| 231 | $join = ''; |
| 232 | |
| 233 | if ( isset( $q['mapping_id'] ) ) { |
| 234 | // Re-use JOINs and aliases from OrdersTableQuery for core tables. |
| 235 | $alias = $this->query->get_core_mapping_alias( $q['mapping_id'] ); |
| 236 | $join = $this->query->get_core_mapping_join( $q['mapping_id'] ); |
| 237 | } else { |
| 238 | $alias = $q['table']; |
| 239 | $join = ''; |
| 240 | } |
| 241 | |
| 242 | if ( in_array( $alias, $this->table_aliases, true ) ) { |
| 243 | return $alias; |
| 244 | } |
| 245 | |
| 246 | $this->table_aliases[] = $alias; |
| 247 | |
| 248 | if ( $join ) { |
| 249 | $this->join[ $alias ] = $join; |
| 250 | } |
| 251 | |
| 252 | return $alias; |
| 253 | } |
| 254 | |
| 255 | /** |
| 256 | * Returns the correct type for a given clause 'type'. |
| 257 | * |
| 258 | * @param string $type MySQL type. |
| 259 | * @return string MySQL type. |
| 260 | */ |
| 261 | private function sanitize_cast_type( $type ) { |
| 262 | $clause_type = strtoupper( $type ); |
| 263 | |
| 264 | if ( ! $clause_type || ! preg_match( '/^(?:BINARY|CHAR|DATE|DATETIME|SIGNED|UNSIGNED|TIME|NUMERIC(?:\(\d+(?:,\s?\d+)?\))?|DECIMAL(?:\(\d+(?:,\s?\d+)?\))?)$/', $clause_type ) ) { |
| 265 | return 'CHAR'; |
| 266 | } |
| 267 | |
| 268 | if ( 'NUMERIC' === $clause_type ) { |
| 269 | $clause_type = 'SIGNED'; |
| 270 | } |
| 271 | |
| 272 | return $clause_type; |
| 273 | } |
| 274 | |
| 275 | /** |
| 276 | * Generates an SQL WHERE clause for a given field_query atomic clause. |
| 277 | * |
| 278 | * @param array $clause An atomic field_query clause. |
| 279 | * @return string An SQL WHERE clause or an empty string if $clause is invalid. |
| 280 | */ |
| 281 | private function generate_where_for_clause( $clause ): string { |
| 282 | global $wpdb; |
| 283 | |
| 284 | $clause_value = $clause['value'] ?? ''; |
| 285 | |
| 286 | if ( in_array( $clause['compare'], array( 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN' ), true ) ) { |
| 287 | if ( ! is_array( $clause_value ) ) { |
| 288 | $clause_value = preg_split( '/[,\s]+/', $clause_value ); |
| 289 | } |
| 290 | } elseif ( is_string( $clause_value ) ) { |
| 291 | $clause_value = trim( $clause_value ); |
| 292 | } |
| 293 | |
| 294 | $clause_compare = $clause['compare']; |
| 295 | switch ( $clause_compare ) { |
| 296 | case 'IN': |
| 297 | case 'NOT IN': |
| 298 | $where = $wpdb->prepare( '(' . substr( str_repeat( ',%s', count( (array) $clause_value ) ), 1 ) . ')', $clause_value ); // phpcs:ignore WordPress.DB.PreparedSQL.NotPrepared |
| 299 | break; |
| 300 | case 'BETWEEN': |
| 301 | case 'NOT BETWEEN': |
| 302 | $where = $wpdb->prepare( '%s AND %s', $clause_value[0], $clause_value[1] ?? $clause_value[0] ); |
| 303 | break; |
| 304 | case 'LIKE': |
| 305 | case 'NOT LIKE': |
| 306 | $where = $wpdb->prepare( '%s', '%' . $wpdb->esc_like( $clause_value ) . '%' ); |
| 307 | break; |
| 308 | case 'EXISTS': |
| 309 | // EXISTS with a value is interpreted as '='. |
| 310 | if ( $clause_value ) { |
| 311 | $clause_compare = '='; |
| 312 | $where = $wpdb->prepare( '%s', $clause_value ); |
| 313 | } else { |
| 314 | $clause_compare = 'IS NOT'; |
| 315 | $where = 'NULL'; |
| 316 | } |
| 317 | |
| 318 | break; |
| 319 | case 'NOT EXISTS': |
| 320 | // 'value' is ignored for NOT EXISTS. |
| 321 | $clause_compare = 'IS'; |
| 322 | $where = 'NULL'; |
| 323 | break; |
| 324 | default: |
| 325 | $where = $wpdb->prepare( '%s', $clause_value ); |
| 326 | break; |
| 327 | } |
| 328 | |
| 329 | if ( ! empty( $where ) ) { |
| 330 | if ( 'CHAR' === $clause['cast'] ) { |
| 331 | return "`{$clause['alias']}`.`{$clause['column']}` {$clause_compare} {$where}"; |
| 332 | } else { |
| 333 | return "CAST(`{$clause['alias']}`.`{$clause['column']}` AS {$clause['cast']}) {$clause_compare} {$where}"; |
| 334 | } |
| 335 | } |
| 336 | |
| 337 | return ''; |
| 338 | } |
| 339 | |
| 340 | /** |
| 341 | * Returns JOIN and WHERE clauses to be appended to the main SQL query. |
| 342 | * |
| 343 | * @return array { |
| 344 | * @type string $join JOIN clause. |
| 345 | * @type string $where WHERE clause. |
| 346 | * } |
| 347 | */ |
| 348 | public function get_sql_clauses() { |
| 349 | return array( |
| 350 | 'join' => $this->join, |
| 351 | 'where' => $this->where ? array( $this->where ) : array(), |
| 352 | ); |
| 353 | } |
| 354 | |
| 355 | } |
| 356 |