From 1668b671ffe9a0bd1194ce0d2d468fee51aa9520 Mon Sep 17 00:00:00 2001 From: ryan Date: Thu, 30 Nov 2006 01:44:33 +0000 Subject: [PATCH] Inline docs for wpdb. Props masquerade and davidhouse. #2474 git-svn-id: http://svn.automattic.com/wordpress/trunk@4549 1a063a9b-81f0-0310-95a4-ce76da25c4cd --- wp-includes/wp-db.php | 91 +++++++++++++++++++++++++++++-------------- 1 file changed, 62 insertions(+), 29 deletions(-) diff --git a/wp-includes/wp-db.php b/wp-includes/wp-db.php index d1303b12a..47a32f7ed 100644 --- a/wp-includes/wp-db.php +++ b/wp-includes/wp-db.php @@ -36,9 +36,13 @@ class wpdb { var $optiongroup_options; var $postmeta; - // ================================================================== - // DB Constructor - connects to the server and selects a database - + /** + * Connects to the database server and selects a database + * @param string $dbuser + * @param string $dbpassword + * @param string $dbname + * @param string $dbhost + */ function wpdb($dbuser, $dbpassword, $dbname, $dbhost) { $this->dbh = @mysql_connect($dbhost, $dbuser, $dbpassword); if (!$this->dbh) { @@ -57,9 +61,10 @@ class wpdb { $this->select($dbname); } - // ================================================================== - // Select a DB (if another one needs to be selected) - + /** + * Selects a database using the current class's $this->dbh + * @param string $db name + */ function select($db) { if (!@mysql_select_db($db, $this->dbh)) { $this->bail(" @@ -73,9 +78,12 @@ class wpdb { } } - // ==================================================================== - // Format a string correctly for safe insert under all PHP conditions - + /** + * Escapes content for insertion into the database, for security + * + * @param string $string + * @return string query safe string + */ function escape($string) { return addslashes( $string ); // Disable rest for now, causing problems if( !$this->dbh || version_compare( phpversion(), '4.3.0' ) == '-1' ) @@ -147,7 +155,7 @@ class wpdb { $this->result = @mysql_query($query, $this->dbh); ++$this->num_queries; - + if (SAVEQUERIES) $this->queries[] = array( $query, $this->timer_stop() ); @@ -189,9 +197,13 @@ class wpdb { return $return_val; } - // ================================================================== - // Get one variable from the DB - see docs for more detail - + /** + * Get one variable from the database + * @param string $query (can be null as well, for caching, see codex) + * @param int $x = 0 row num to return + * @param int $y = 0 col num to return + * @return mixed results + */ function get_var($query=null, $x = 0, $y = 0) { $this->func_call = "\$db->get_var(\"$query\",$x,$y)"; if ( $query ) @@ -206,9 +218,13 @@ class wpdb { return (isset($values[$x]) && $values[$x]!=='') ? $values[$x] : null; } - // ================================================================== - // Get one row from the DB - see docs for more detail - + /** + * Get one row from the database + * @param string $query + * @param string $output ARRAY_A | ARRAY_N | OBJECT + * @param int $y row num to return + * @return mixed results + */ function get_row($query = null, $output = OBJECT, $y = 0) { $this->func_call = "\$db->get_row(\"$query\",$output,$y)"; if ( $query ) @@ -228,10 +244,12 @@ class wpdb { } } - // ================================================================== - // Function to get 1 column from the cached result set based in X index - // se docs for usage and info - + /** + * Gets one column from the database + * @param string $query (can be null as well, for caching, see codex) + * @param int $x col num to return + * @return array results + */ function get_col($query = null , $x = 0) { if ( $query ) $this->query($query); @@ -243,9 +261,12 @@ class wpdb { return $new_array; } - // ================================================================== - // Return the the query as a result set - see docs for more details - + /** + * Return an entire result set from the database + * @param string $query (can also be null to pull from the cache) + * @param string $output ARRAY_A | ARRAY_N | OBJECT + * @return mixed results + */ function get_results($query = null, $output = OBJECT) { $this->func_call = "\$db->get_results(\"$query\", $output)"; @@ -272,11 +293,12 @@ class wpdb { } } - - // ================================================================== - // Function to get column meta data info pertaining to the last query - // see docs for more info and usage - + /** + * Grabs column metadata from the last query + * @param string $info_type one of name, table, def, max_length, not_null, primary_key, multiple_key, unique_key, numeric, blob, type, unsigned, zerofill + * @param int $col_offset 0: col name. 1: which table the col's in. 2: col's max length. 3: if the col is numeric. 4: col's type + * @return mixed results + */ function get_col_info($info_type = 'name', $col_offset = -1) { if ( $this->col_info ) { if ( $col_offset == -1 ) { @@ -292,6 +314,9 @@ class wpdb { } } + /** + * Starts the timer, for debugging purposes + */ function timer_start() { $mtime = microtime(); $mtime = explode(' ', $mtime); @@ -299,7 +324,11 @@ class wpdb { return true; } - function timer_stop($precision = 3) { + /** + * Stops the debugging timer + * @return int total time spent on the query, in milliseconds + */ + function timer_stop() { $mtime = microtime(); $mtime = explode(' ', $mtime); $time_end = $mtime[1] + $mtime[0]; @@ -307,6 +336,10 @@ class wpdb { return $time_total; } + /** + * Wraps fatal errors in a nice header and footer and dies. + * @param string $message + */ function bail($message) { // Just wraps errors in a nice header and footer if ( !$this->show_errors ) return false;