WordPress.org

Make WordPress Core

Ticket #2474: inline-docs-wpdb.diff

File inline-docs-wpdb.diff, 6.2 KB (added by davidhouse, 8 years ago)
  • wp-includes/wp-db.php

     
    3636        var $optiongroup_options; 
    3737        var $postmeta; 
    3838 
    39         // ================================================================== 
    40         //      DB Constructor - connects to the server and selects a database 
    41  
     39        /** 
     40         * Connects to the database server and selects a database 
     41         * @param string $dbuser 
     42         * @param string $dbpassword 
     43         * @param string $dbname 
     44         * @param string $dbhost 
     45         */ 
    4246        function wpdb($dbuser, $dbpassword, $dbname, $dbhost) { 
    4347                $this->dbh = @mysql_connect($dbhost, $dbuser, $dbpassword); 
    4448                if (!$this->dbh) { 
     
    5761                $this->select($dbname); 
    5862        } 
    5963 
    60         // ================================================================== 
    61         //      Select a DB (if another one needs to be selected) 
    62  
     64        /** 
     65         * Selects a database using the current class's $this->dbh 
     66         * @param string $db name 
     67         */ 
    6368        function select($db) { 
    6469                if (!@mysql_select_db($db, $this->dbh)) { 
    6570                        $this->bail(" 
     
    7378                } 
    7479        } 
    7580 
    76         // ==================================================================== 
    77         //      Format a string correctly for safe insert under all PHP conditions 
    78  
     81        /** 
     82         * Escapes content for insertion into the database, for security 
     83         * 
     84         * @param string $string 
     85         * @return string query safe string 
     86         */ 
    7987        function escape($string) { 
    8088                return addslashes( $string ); // Disable rest for now, causing problems 
    8189                if( !$this->dbh || version_compare( phpversion(), '4.3.0' ) == '-1' ) 
     
    105113                } 
    106114        } 
    107115 
    108         // ================================================================== 
    109         //      Turn error handling on or off.. 
    110  
     116        /** 
     117         * Turn error reporting for SQL errors on 
     118         */ 
    111119        function show_errors() { 
    112120                $this->show_errors = true; 
    113121        } 
    114122 
     123        /** 
     124         * Turn error reporting for SQL errors off 
     125         */ 
    115126        function hide_errors() { 
    116127                $this->show_errors = false; 
    117128        } 
    118129 
    119         // ================================================================== 
    120         //      Kill cached query results 
    121  
     130        /** 
     131         * Flush the internal wpdb cache which stores the last query's results 
     132         */ 
    122133        function flush() { 
    123134                $this->last_result = null; 
    124135                $this->col_info = null; 
    125136                $this->last_query = null; 
    126137        } 
    127138 
    128         // ================================================================== 
    129         //      Basic Query     - see docs for more detail 
    130  
     139        /** 
     140         * Simply run an SQL query 
     141         * @param string $query 
     142         * @return mixed number of rows affected/selected 
     143         */ 
    131144        function query($query) { 
    132145                // initialise return 
    133146                $return_val = 0; 
     
    145158 
    146159                $this->result = @mysql_query($query, $this->dbh); 
    147160                ++$this->num_queries; 
    148  
     161         
    149162                if (SAVEQUERIES) 
    150163                        $this->queries[] = array( $query, $this->timer_stop() ); 
    151164 
     
    187200                return $return_val; 
    188201        } 
    189202 
    190         // ================================================================== 
    191         //      Get one variable from the DB - see docs for more detail 
    192  
     203        /** 
     204         * Get one variable from the database 
     205         * @param string $query (can be null as well, for caching, see codex) 
     206         * @param int $x = 0 row num to return 
     207         * @param int $y = 0 col num to return 
     208         * @return mixed results 
     209         */ 
    193210        function get_var($query=null, $x = 0, $y = 0) { 
    194211                $this->func_call = "\$db->get_var(\"$query\",$x,$y)"; 
    195212                if ( $query ) 
     
    204221                return (isset($values[$x]) && $values[$x]!=='') ? $values[$x] : null; 
    205222        } 
    206223 
    207         // ================================================================== 
    208         //      Get one row from the DB - see docs for more detail 
    209  
     224        /** 
     225         * Get one row from the database 
     226         * @param string $query 
     227         * @param string $output ARRAY_A | ARRAY_N | OBJECT 
     228         * @param int $y row num to return 
     229         * @return mixed results 
     230         */ 
    210231        function get_row($query = null, $output = OBJECT, $y = 0) { 
    211232                $this->func_call = "\$db->get_row(\"$query\",$output,$y)"; 
    212233                if ( $query ) 
     
    223244                } 
    224245        } 
    225246 
    226         // ================================================================== 
    227         //      Function to get 1 column from the cached result set based in X index 
    228         // se docs for usage and info 
    229  
     247        /** 
     248         * Gets one column from the database 
     249         * @param string $query (can be null as well, for caching, see codex) 
     250         * @param int $x col num to return 
     251         * @return array results 
     252         */ 
    230253        function get_col($query = null , $x = 0) { 
    231254                if ( $query ) 
    232255                        $this->query($query); 
     
    238261                return $new_array; 
    239262        } 
    240263 
    241         // ================================================================== 
    242         // Return the the query as a result set - see docs for more details 
    243  
     264        /** 
     265         * Return an entire result set from the database 
     266         * @param string $query (can also be null to pull from the cache) 
     267         * @param string $output ARRAY_A | ARRAY_N | OBJECT 
     268         * @return mixed results 
     269         */ 
    244270        function get_results($query = null, $output = OBJECT) { 
    245271                $this->func_call = "\$db->get_results(\"$query\", $output)"; 
    246272 
     
    267293                } 
    268294        } 
    269295 
    270  
    271         // ================================================================== 
    272         // Function to get column meta data info pertaining to the last query 
    273         // see docs for more info and usage 
    274  
     296        /** 
     297         * Grabs column metadata from the last query 
     298         * @param string $info_type one of name, table, def, max_length, not_null, primary_key, multiple_key, unique_key, numeric, blob, type, unsigned, zerofill 
     299         * @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 
     300         * @return mixed results 
     301         */ 
    275302        function get_col_info($info_type = 'name', $col_offset = -1) { 
    276303                if ( $this->col_info ) { 
    277304                        if ( $col_offset == -1 ) { 
     
    287314                } 
    288315        } 
    289316 
     317        /** 
     318         * Starts the timer, for debugging purposes 
     319         */ 
    290320        function timer_start() { 
    291321                $mtime = microtime(); 
    292322                $mtime = explode(' ', $mtime); 
     
    294324                return true; 
    295325        } 
    296326 
    297         function timer_stop($precision = 3) { 
     327        /** 
     328         * Stops the debugging timer 
     329         * @return int total time spent on the query, in milliseconds 
     330         */ 
     331        function timer_stop() { 
    298332                $mtime = microtime(); 
    299333                $mtime = explode(' ', $mtime); 
    300334                $time_end = $mtime[1] + $mtime[0]; 
     
    302336                return $time_total; 
    303337        } 
    304338 
     339        /** 
     340         * Wraps fatal errors in a nice header and footer and dies. 
     341         * @param string $message 
     342         */ 
    305343        function bail($message) { // Just wraps errors in a nice header and footer 
    306344        if ( !$this->show_errors ) 
    307345                return false;