From 0a9d65e577a6f6607deca90bb41f44a41b45ac89 Mon Sep 17 00:00:00 2001 From: John James Jacoby Date: Mon, 30 Aug 2021 14:35:35 -0500 Subject: [PATCH] Docs: refresh some inline docs. This commit improves the consistency of some docs and return values across all files. See #115. --- src/Database/Base.php | 10 +++- src/Database/Column.php | 56 +++++++++++----------- src/Database/Queries/Compare.php | 81 ++++++++++++++++++++------------ src/Database/Queries/Date.php | 2 +- src/Database/Queries/Meta.php | 2 +- src/Database/Query.php | 63 ++++++++++++++++++------- src/Database/Row.php | 2 +- src/Database/Schema.php | 2 +- src/Database/Table.php | 2 +- 9 files changed, 140 insertions(+), 80 deletions(-) diff --git a/src/Database/Base.php b/src/Database/Base.php index 3293d1e..495b111 100644 --- a/src/Database/Base.php +++ b/src/Database/Base.php @@ -4,7 +4,7 @@ * * @package Database * @subpackage Base - * @copyright Copyright (c) 2020 + * @copyright Copyright (c) 2021 * @license https://opensource.org/licenses/gpl-2.0.php GNU Public License * @since 1.0.0 */ @@ -177,8 +177,14 @@ protected function first_letters( $string = '', $sep = '_' ) { // Trim spaces off the ends $unspace = trim( $string ); + + // Only non-accented table names (avoid truncation) $accents = remove_accents( $unspace ); + + // Only lowercase letters are allowed $lower = strtolower( $accents ); + + // Explode into parts $parts = explode( $sep, $lower ); // Loop through parts and concatenate the first letters together @@ -290,7 +296,7 @@ protected function get_db() { * Developer note: * * It should be impossible for a database table to be interacted with - * before the primary database interface it is setup. + * before the primary database interface is setup. * * However, because applications are complicated, it is unsafe to assume * anything, so this silently returns false instead of halting everything. diff --git a/src/Database/Column.php b/src/Database/Column.php index 63a7d4a..dafe835 100644 --- a/src/Database/Column.php +++ b/src/Database/Column.php @@ -4,7 +4,7 @@ * * @package Database * @subpackage Column - * @copyright Copyright (c) 2020 + * @copyright Copyright (c) 2021 * @license https://opensource.org/licenses/gpl-2.0.php GNU Public License * @since 1.0.0 */ @@ -433,39 +433,39 @@ private function parse_args( $args = array() ) { $r = wp_parse_args( $args, array( // Table - 'name' => '', - 'type' => '', - 'length' => '', - 'unsigned' => false, - 'zerofill' => false, - 'binary' => false, - 'allow_null' => false, - 'default' => '', - 'extra' => '', - 'encoding' => $this->get_db()->charset, - 'collation' => $this->get_db()->collate, - 'comment' => '', + 'name' => '', + 'type' => '', + 'length' => '', + 'unsigned' => false, + 'zerofill' => false, + 'binary' => false, + 'allow_null' => false, + 'default' => '', + 'extra' => '', + 'encoding' => $this->get_db()->charset, + 'collation' => $this->get_db()->collate, + 'comment' => '', // Query - 'pattern' => false, - 'searchable' => false, - 'sortable' => false, - 'date_query' => false, - 'transition' => false, - 'in' => true, - 'not_in' => true, + 'pattern' => false, + 'searchable' => false, + 'sortable' => false, + 'date_query' => false, + 'transition' => false, + 'in' => true, + 'not_in' => true, // Special - 'primary' => false, - 'created' => false, - 'modified' => false, - 'uuid' => false, + 'primary' => false, + 'created' => false, + 'modified' => false, + 'uuid' => false, // Cache - 'cache_key' => false, + 'cache_key' => false, // Validation - 'validate' => '', + 'validate' => '', // Capabilities 'caps' => array(), @@ -692,10 +692,10 @@ private function sanitize_default( $default = '' ) { * Sanitize the pattern * * @since 1.0.0 - * @param mixed $pattern + * @param string $pattern * @return string */ - private function sanitize_pattern( $pattern = false ) { + private function sanitize_pattern( $pattern = '%s' ) { // Allowed patterns $allowed_patterns = array( '%s', '%d', '%f' ); diff --git a/src/Database/Queries/Compare.php b/src/Database/Queries/Compare.php index 9223e6f..fb2b29d 100644 --- a/src/Database/Queries/Compare.php +++ b/src/Database/Queries/Compare.php @@ -4,7 +4,7 @@ * * @package Database * @subpackage Compare - * @copyright Copyright (c) 2020 + * @copyright Copyright (c) 2021 * @license https://opensource.org/licenses/gpl-2.0.php GNU Public License * @since 1.0.0 */ @@ -24,6 +24,35 @@ */ class Compare extends Meta { + // All supported SQL comparisons + const ALL_COMPARES = array( + '=', + '!=', + '>', + '>=', + '<', + '<=', + 'LIKE', + 'NOT LIKE', + 'IN', + 'NOT IN', + 'BETWEEN', + 'NOT BETWEEN', + 'EXISTS', + 'NOT EXISTS', + 'REGEXP', + 'NOT REGEXP', + 'RLIKE', + ); + + // IN and BETWEEN + const IN_BETWEEN_COMPARES = array( + 'IN', + 'NOT IN', + 'BETWEEN', + 'NOT BETWEEN' + ); + /** * Generate SQL WHERE clauses for a first-order query clause. * @@ -44,65 +73,57 @@ class Compare extends Meta { public function get_sql_for_clause( &$clause, $parent_query, $clause_key = '' ) { global $wpdb; + // Default chunks $sql_chunks = array( 'where' => array(), 'join' => array(), ); + // Maybe format compare clause if ( isset( $clause['compare'] ) ) { $clause['compare'] = strtoupper( $clause['compare'] ); + + // Or set compare clause based on value } else { - $clause['compare'] = isset( $clause['value'] ) && is_array( $clause['value'] ) ? 'IN' : '='; + $clause['compare'] = isset( $clause['value'] ) && is_array( $clause['value'] ) + ? 'IN' + : '='; } - if ( ! in_array( - $clause['compare'], array( - '=', - '!=', - '>', - '>=', - '<', - '<=', - 'LIKE', - 'NOT LIKE', - 'IN', - 'NOT IN', - 'BETWEEN', - 'NOT BETWEEN', - 'EXISTS', - 'NOT EXISTS', - 'REGEXP', - 'NOT REGEXP', - 'RLIKE', - ), true - ) ) { + // Fallback to equals + if ( ! in_array( $clause['compare'], self::ALL_COMPARES, true ) ) { $clause['compare'] = '='; } - if ( isset( $clause['compare_key'] ) && 'LIKE' === strtoupper( $clause['compare_key'] ) ) { + // Uppercase or equals + if ( isset( $clause['compare_key'] ) && ( 'LIKE' === strtoupper( $clause['compare_key'] ) ) ) { $clause['compare_key'] = strtoupper( $clause['compare_key'] ); } else { $clause['compare_key'] = '='; } - $compare = $clause['compare']; - $compare_key = $clause['compare_key']; + // Get comparison from clause + $compare = $clause['compare']; - // Build the WHERE clause. + /** Build the WHERE clause ********************************************/ // Column name and value. if ( array_key_exists( 'key', $clause ) && array_key_exists( 'value', $clause ) ) { $column = sanitize_key( $clause['key'] ); $value = $clause['value']; - if ( in_array( $compare, array( 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN' ), true ) ) { + // IN or BETWEEN + if ( in_array( $compare, self::IN_BETWEEN_COMPARES, true ) ) { if ( ! is_array( $value ) ) { $value = preg_split( '/[,\s]+/', $value ); } + + // Anything else } else { $value = trim( $value ); } + // Format WHERE from compare value(s) switch ( $compare ) { case 'IN': case 'NOT IN': @@ -139,7 +160,8 @@ public function get_sql_for_clause( &$clause, $parent_query, $clause_key = '' ) } - if ( $where ) { + // Maybe add column, compare, & where to chunks + if ( ! empty( $where ) ) { $sql_chunks['where'][] = "{$column} {$compare} {$where}"; } } @@ -152,6 +174,7 @@ public function get_sql_for_clause( &$clause, $parent_query, $clause_key = '' ) $sql_chunks['where'] = array( '( ' . implode( ' AND ', $sql_chunks['where'] ) . ' )' ); } + // Return return $sql_chunks; } } \ No newline at end of file diff --git a/src/Database/Queries/Date.php b/src/Database/Queries/Date.php index de74bc5..db976c3 100644 --- a/src/Database/Queries/Date.php +++ b/src/Database/Queries/Date.php @@ -4,7 +4,7 @@ * * @package Database * @subpackage Date - * @copyright Copyright (c) 2020 + * @copyright Copyright (c) 2021 * @license https://opensource.org/licenses/gpl-2.0.php GNU Public License * @since 1.0.0 */ diff --git a/src/Database/Queries/Meta.php b/src/Database/Queries/Meta.php index ac4ef0d..728d1ac 100644 --- a/src/Database/Queries/Meta.php +++ b/src/Database/Queries/Meta.php @@ -4,7 +4,7 @@ * * @package Database * @subpackage Meta - * @copyright Copyright (c) 2020 + * @copyright Copyright (c) 2021 * @license https://opensource.org/licenses/gpl-2.0.php GNU Public License * @since 1.1.0 */ diff --git a/src/Database/Query.php b/src/Database/Query.php index e9f6dbb..3d17ce8 100644 --- a/src/Database/Query.php +++ b/src/Database/Query.php @@ -4,7 +4,7 @@ * * @package Database * @subpackage Query - * @copyright Copyright (c) 2020 + * @copyright Copyright (c) 2021 * @license https://opensource.org/licenses/gpl-2.0.php GNU Public License * @since 1.0.0 */ @@ -448,10 +448,14 @@ private function set_query_var_defaults() { 'search' => '', 'search_columns' => array(), 'count' => false, + + // Disable SQL_CALC_FOUND_ROWS? + 'no_found_rows' => true, + + // Queries 'meta_query' => null, // See Queries\Meta 'date_query' => null, // See Queries\Date 'compare_query' => null, // See Queries\Compare - 'no_found_rows' => true, // Caching 'update_item_cache' => true, @@ -752,6 +756,9 @@ private function get_primary_column_name() { * * @since 1.0.0 * + * @param array $args Arguments to get a column by. + * @param string $field Field to get from a column. + * @param mixed $default Default to use if no field is set. * @return mixed Column object, or false */ private function get_column_field( $args = array(), $field = '', $default = false ) { @@ -770,6 +777,7 @@ private function get_column_field( $args = array(), $field = '', $default = fals * * @since 1.0.0 * + * @param array $args Arguments to get a column by. * @return mixed Column object, or false */ private function get_column_by( $args = array() ) { @@ -787,6 +795,12 @@ private function get_column_by( $args = array() ) { * Get columns from an array of arguments. * * @since 1.0.0 + * + * @param array $args Arguments to filter columns by. + * @param string $operator Optional. The logical operation to perform. + * @param string $field Optional. A field from the object to place + * instead of the entire object. Default false. + * @return array Array of column. */ private function get_columns( $args = array(), $operator = 'and', $field = false ) { @@ -1285,9 +1299,13 @@ private function parse_where() { /** Query Classes *****************************************************/ - // Get the primary column name & meta table + // Get the primary column name $primary = $this->get_primary_column_name(); + + // Get the meta table $table = $this->get_meta_type(); + + // Set the " AND " regex pattern $and = '/^\s*AND\s*/'; // Maybe perform a meta query. @@ -1379,8 +1397,10 @@ private function parse_where() { */ private function parse_fields( $fields = '', $alias = true ) { - // Default return value + // Get the primary column name $primary = $this->get_primary_column_name(); + + // Default return value $retval = ( true === $alias ) ? "{$this->table_alias}.{$primary}" : $primary; @@ -1458,8 +1478,10 @@ private function parse_groupby( $groupby = '', $alias = true ) { */ private function parse_orderby( $orderby = '' ) { - // Default value + // Get the primary column name $primary = $this->get_primary_column_name(); + + // Default return value $parsed = "{$this->table_alias}.{$primary}"; // Default to primary column @@ -1576,6 +1598,8 @@ private function get_item_fields( $items = array() ) { // Get the primary column name $primary = $this->get_primary_column_name(); + + // Get the query var fields $fields = $this->query_vars['fields']; // Strings need to be single columns @@ -1699,7 +1723,7 @@ public function get_item_by( $column_name = '', $column_value = '' ) { return $retval; } - // Get the column names + // Get all of the column names $columns = $this->get_column_names(); // Bail if column does not exist @@ -1707,7 +1731,7 @@ public function get_item_by( $column_name = '', $column_value = '' ) { return $retval; } - // Cache groups + // Get all of the cache groups $groups = $this->get_cache_groups(); // Check cache @@ -1718,7 +1742,7 @@ public function get_item_by( $column_name = '', $column_value = '' ) { // Item not cached if ( false === $retval ) { - // Try to get item directly from DB + // Get item by column name & value (from database, not cache) $retval = $this->get_item_raw( $column_name, $column_value ); // Bail on failure @@ -1726,7 +1750,7 @@ public function get_item_by( $column_name = '', $column_value = '' ) { return false; } - // Cache + // Update item cache(s) $this->update_item_cache( $retval ); } @@ -1823,7 +1847,7 @@ public function add_item( $data = array() ) { $this->save_extra_item_meta( $item_id, $meta ); } - // Use get item to prime caches + // Update item cache(s) $this->update_item_cache( $item_id ); // Transition item data @@ -1948,7 +1972,7 @@ public function update_item( $item_id = 0, $data = array() ) { return false; } - // Use get item to prime caches + // Update item cache(s) $this->update_item_cache( $item_id ); // Transition item data @@ -1977,7 +2001,7 @@ public function delete_item( $item_id = 0 ) { // Get the primary column name $primary = $this->get_primary_column_name(); - // Get item (before it's deleted) + // Get item by ID (from database, not cache) $item = $this->get_item_raw( $primary, $item_id ); // Bail if item does not exist to delete @@ -2196,7 +2220,8 @@ private function default_item() { * * @since 1.0.0 * - * @param array $item + * @param array $new_data + * @param array $old_data * @return array */ private function transition_item( $new_data = array(), $old_data = array() ) { @@ -2463,9 +2488,11 @@ private function delete_all_item_meta( $item_id = 0 ) { return; } + // Get the primary column name + $primary = $this->get_primary_column_name(); + // Guess the item ID column for the meta table - $primary_id = $this->get_primary_column_name(); - $item_id_column = $this->apply_prefix( "{$this->item_name}_{$primary_id}" ); + $item_id_column = $this->apply_prefix( "{$this->item_name}_{$primary}" ); // Get meta IDs $query = "SELECT meta_id FROM {$table} WHERE {$item_id_column} = %d"; @@ -2662,7 +2689,7 @@ private function prime_item_caches( $item_ids = array(), $force = false ) { $prepare = sprintf( $query, $ids ); $results = $this->get_db()->get_results( $prepare ); - // Update item caches + // Update item cache(s) $this->update_item_cache( $results ); } @@ -2690,7 +2717,11 @@ private function update_item_cache( $items = array() ) { // Maybe query for single item if ( is_numeric( $items ) ) { + + // Get the primary column name $primary = $this->get_primary_column_name(); + + // Get item by ID (from database, not cache) $items = $this->get_item_raw( $primary, $items ); } diff --git a/src/Database/Row.php b/src/Database/Row.php index a53a8bb..8a981e6 100644 --- a/src/Database/Row.php +++ b/src/Database/Row.php @@ -4,7 +4,7 @@ * * @package Database * @subpackage Row - * @copyright Copyright (c) 2020 + * @copyright Copyright (c) 2021 * @license https://opensource.org/licenses/gpl-2.0.php GNU Public License * @since 1.0.0 */ diff --git a/src/Database/Schema.php b/src/Database/Schema.php index 99dee49..065bc29 100644 --- a/src/Database/Schema.php +++ b/src/Database/Schema.php @@ -4,7 +4,7 @@ * * @package Database * @subpackage Schema - * @copyright Copyright (c) 2020 + * @copyright Copyright (c) 2021 * @license https://opensource.org/licenses/gpl-2.0.php GNU Public License * @since 1.0.0 */ diff --git a/src/Database/Table.php b/src/Database/Table.php index df5e748..9560ddf 100644 --- a/src/Database/Table.php +++ b/src/Database/Table.php @@ -4,7 +4,7 @@ * * @package Database * @subpackage Table - * @copyright Copyright (c) 2020 + * @copyright Copyright (c) 2021 * @license https://opensource.org/licenses/gpl-2.0.php GNU Public License * @since 1.0.0 */