WordPress.org

Make WordPress Core

Changeset 10911


Ignore:
Timestamp:
04/10/09 21:57:40 (5 years ago)
Author:
ryan
Message:

phpdoc updates for wpdb. Props mdawaffe. fixes #9506

File:
1 edited

Legend:

Unmodified
Added
Removed
  • trunk/wp-includes/wp-db.php

    r10910 r10911  
    388388     * 
    389389     * Also allows for the CUSTOM_USER_TABLE and CUSTOM_USER_META_TABLE to 
    390      * override the WordPress users and usersmeta tables. 
     390     * override the WordPress users and usersmeta tables that would otherwise be determined by the $prefix. 
    391391     * 
    392392     * @since 2.5.0 
    393393     * 
    394394     * @param string $prefix Alphanumeric name for the new prefix. 
    395      * @return string Old prefix 
     395     * @return string|WP_Error Old prefix or WP_Error on error 
    396396     */ 
    397397    function set_prefix($prefix) { 
     
    503503 
    504504    /** 
    505      * Prepares a SQL query for safe use, using sprintf() syntax. 
    506      * 
    507      * @link http://php.net/sprintf See for syntax to use for query string. 
     505     * Prepares a SQL query for safe execution.  Uses sprintf()-like syntax. 
     506     * 
     507     * This function only supports a small subset of the sprintf syntax; it only supports %d (decimal number), %s (string). 
     508     * Does not support sign, padding, alignment, width or precision specifiers. 
     509     * Does not support argument numbering/swapping. 
     510     * 
     511     * May be called like {@link http://php.net/sprintf sprintf()} or like {@link http://php.net/vsprintf vsprintf()}. 
     512     * 
     513     * Both %d and %s should be left unquoted in the query string. 
     514     * 
     515     * <code> 
     516     * wpdb::prepare( "SELECT * FROM `table` WHERE `column` = %s AND `field` = %d", "foo", 1337 ) 
     517     * </code> 
     518     * 
     519     * @link http://php.net/sprintf Description of syntax. 
    508520     * @since 2.3.0 
    509521     * 
    510      * @param null|string $args If string, first parameter must be query statement 
    511      * @param mixed $args,... If additional parameters, they will be set inserted into the query. 
     522     * @param string $query Query statement with sprintf()-like placeholders 
     523     * @param array|mixed $args The array of variables to substitute into the query's placeholders if being called like {@link http://php.net/vsprintf vsprintf()}, or the first variable to substitute into the query's placeholders if being called like {@link http://php.net/sprintf sprintf()}. 
     524     * @param mixed $args,... further variables to substitute into the query's placeholders if being called like {@link http://php.net/sprintf sprintf()}. 
    512525     * @return null|string Sanitized query string 
    513526     */ 
    514     function prepare($args=null) { 
    515         if ( is_null( $args ) ) 
     527    function prepare($query = null) { // ( $query, *$args ) 
     528        if ( is_null( $query ) ) 
    516529            return; 
    517530        $args = func_get_args(); 
    518         $query = array_shift($args); 
    519         // If args were passed as an array, move them up 
     531        array_shift($args); 
     532        // If args were passed as an array (as in vsprintf), move them up 
    520533        if ( isset($args[0]) && is_array($args[0]) ) 
    521534            $args = $args[0]; 
     
    638651     * 
    639652     * @param string $query 
    640      * @return unknown 
     653     * @return int|false Number of rows affected/selected or false on error 
    641654     */ 
    642655    function query($query) { 
     
    708721 
    709722    /** 
    710      * Insert an array of data into a table. 
     723     * Insert a row into a table. 
     724     * 
     725     * <code> 
     726     * wpdb::insert( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( '%s', '%d' ) ) 
     727     * </code> 
    711728     * 
    712729     * @since 2.5.0 
     730     * @see wpdb::prepare() 
    713731     * 
    714732     * @param string $table table name 
    715      * @param array $data Should not already be SQL-escaped 
    716      * @param array|string $format The format of the field values. 
    717      * @return mixed Results of $this->query() 
     733     * @param array $data Data to insert (in column => value pairs).  Both $data columns and $data values should be "raw" (neither should be SQL escaped). 
     734     * @param array|string $format (optional) An array of formats to be mapped to each of the value in $data.  If string, that format will be used for all of the values in $data.  A format is one of '%d', '%s' (decimal number, string).  If omitted, all values in $data will be treated as strings. 
     735     * @return int|false The number of rows inserted, or false on error. 
    718736     */ 
    719737    function insert($table, $data, $format = null) { 
     
    734752    } 
    735753 
    736     /** 
    737      * Update a row in the table with an array of data. 
     754         
     755    /** 
     756     * Update a row in the table 
     757     * 
     758     * <code> 
     759     * wpdb::update( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( 'ID' => 1 ), array( '%s', '%d' ), array( '%d' ) ) 
     760     * </code> 
    738761     * 
    739762     * @since 2.5.0 
     763     * @see wpdb::prepare() 
    740764     * 
    741765     * @param string $table table name 
    742      * @param array $data Should not already be SQL-escaped 
    743      * @param array $where A named array of WHERE column => value relationships.  Multiple member pairs will be joined with ANDs. 
    744      * @param array|string $format The format of the field values. 
    745      * @param array|string $where_format The format of the where field values. 
    746      * @return mixed Results of $this->query() 
     766     * @param array $data Data to update (in column => value pairs).  Both $data columns and $data values should be "raw" (neither should be SQL escaped). 
     767     * @param array $where A named array of WHERE clauses (in column => value pairs).  Multiple clauses will be joined with ANDs.  Both $where columns and $where values should be "raw". 
     768     * @param array|string $format (optional) An array of formats to be mapped to each of the values in $data.  If string, that format will be used for all of the values in $data.  A format is one of '%d', '%s' (decimal number, string).  If omitted, all values in $data will be treated as strings. 
     769     * @param array|string $format_where (optional) An array of formats to be mapped to each of the values in $where.  If string, that format will be used for all of  the items in $where.  A format is one of '%d', '%s' (decimal number, string).  If omitted, all values in $where will be treated as strings. 
     770     * @return int|false The number of rows updated, or false on error. 
    747771     */ 
    748772    function update($table, $data, $where, $format = null, $where_format = null) { 
     
    780804     * Retrieve one variable from the database. 
    781805     * 
    782      * This combines the functionality of wpdb::get_row() and wpdb::get_col(), 
    783      * so both the column and row can be picked. 
    784      * 
    785      * It is possible to use this function without executing more queries. If 
    786      * you already made a query, you can set the $query to 'null' value and just 
    787      * retrieve either the column and row of the last query result. 
    788      * 
    789      * @since 0.71 
    790      * 
    791      * @param string $query Can be null as well, for caching 
    792      * @param int $x Column num to return 
    793      * @param int $y Row num to return 
    794      * @return mixed Database query results 
     806     * Executes a SQL query and returns the value from the SQL result. 
     807     * If the SQL result contains more than one column and/or more than one row, this function returns the value in the column and row specified. 
     808     * If $query is null, this function returns the value in the specified column and row from the previous SQL result. 
     809     * 
     810     * @since 0.71 
     811     * 
     812     * @param string|null $query SQL query.  If null, use the result from the previous query. 
     813     * @param int $x (optional) Column of value to return.  Indexed from 0. 
     814     * @param int $y (optional) Row of value to return.  Indexed from 0. 
     815     * @return string Database query result 
    795816     */ 
    796817    function get_var($query=null, $x = 0, $y = 0) { 
     
    811832     * Retrieve one row from the database. 
    812833     * 
    813      * @since 0.71 
    814      * 
    815      * @param string $query SQL query 
    816      * @param string $output ARRAY_A | ARRAY_N | OBJECT 
    817      * @param int $y Row num to return 
    818      * @return mixed Database query results 
     834     * Executes a SQL query and returns the row from the SQL result. 
     835     * 
     836     * @since 0.71 
     837     * 
     838     * @param string|null $query SQL query. 
     839     * @param string $output (optional) one of ARRAY_A | ARRAY_N | OBJECT constants.  Return an associative array (column => value, ...), a numerically indexed array (0 => value, ...) or an object ( ->column = value ), respectively. 
     840     * @param int $y (optional) Row to return.  Indexed from 0. 
     841     * @return mixed Database query result in format specifed by $output 
    819842     */ 
    820843    function get_row($query = null, $output = OBJECT, $y = 0) { 
     
    842865     * Retrieve one column from the database. 
    843866     * 
    844      * @since 0.71 
    845      * 
    846      * @param string $query Can be null as well, for caching 
    847      * @param int $x Col num to return. Starts from 0. 
    848      * @return array Column results 
     867     * Executes a SQL query and returns the column from the SQL result. 
     868     * If the SQL result contains more than one column, this function returns the column specified. 
     869     * If $query is null, this function returns the specified column from the previous SQL result. 
     870     * 
     871     * @since 0.71 
     872     * 
     873     * @param string|null $query SQL query.  If null, use the result from the previous query. 
     874     * @param int $x Column to return.  Indexed from 0. 
     875     * @return array Database query result.  Array indexed from 0 by SQL result row number. 
    849876     */ 
    850877    function get_col($query = null , $x = 0) { 
     
    861888 
    862889    /** 
    863      * Retrieve an entire result set from the database. 
    864      * 
    865      * @since 0.71 
    866      * 
    867      * @param string|null $query Can also be null to pull from the cache 
    868      * @param string $output ARRAY_A | ARRAY_N | OBJECT_K | OBJECT 
     890     * Retrieve an entire SQL result set from the database (i.e., many rows) 
     891     * 
     892     * Executes a SQL query and returns the entire SQL result. 
     893     * 
     894     * @since 0.71 
     895     * 
     896     * @param string $query SQL query. 
     897     * @param string $output (optional) ane of ARRAY_A | ARRAY_N | OBJECT | OBJECT_K constants.  With one of the first three, return an array of rows indexed from 0 by SQL result row number.  Each row is an associative array (column => value, ...), a numerically indexed array (0 => value, ...), or an object. ( ->column = value ), respectively.  With OBJECT_K, return an associative array of row objects keyed by the value of each row's first column's value.  Duplicate keys are discarded. 
    869898     * @return mixed Database query results 
    870899     */ 
     
    937966     * @since 1.5.0 
    938967     * 
    939      * @return bool Always returns true 
     968     * @return true 
    940969     */ 
    941970    function timer_start() { 
     
    962991 
    963992    /** 
    964      * Wraps fatal errors in a nice header and footer and dies. 
     993     * Wraps errors in a nice header and footer and dies. 
     994     * 
     995     * Will not die if wpdb::$show_errors is true 
    965996     * 
    966997     * @since 1.5.0 
    967998     * 
    968999     * @param string $message 
    969      * @return unknown 
     1000     * @return false|void 
    9701001     */ 
    9711002    function bail($message) { 
     
    9811012 
    9821013    /** 
    983      * Whether or not MySQL database is minimal required version. 
     1014     * Whether or not MySQL database is at least the required minimum version. 
    9841015     * 
    9851016     * @since 2.5.0 
     
    9971028 
    9981029    /** 
    999      * Whether of not the database version supports collation. 
     1030     * Whether of not the database supports collation. 
    10001031     * 
    10011032     * Called when WordPress is generating the table scheme. 
     
    10131044     * Generic function to determine if a database supports a particular feature 
    10141045     * @param string $db_cap the feature 
    1015      * @param false|string|resource $dbh_or_table the databaese (the current database, the database housing the specified table, or the database of the mysql resource) 
     1046     * @param false|string|resource $dbh_or_table (not implemented) Which database to test.  False = the currently selected database, string = the database containing the specified table, resource = the database corresponding to the specified mysql resource. 
    10161047     * @return bool 
    10171048     */ 
     
    10641095    /** 
    10651096     * The database version number 
     1097     * @param false|string|resource $dbh_or_table (not implemented) Which database to test.  False = the currently selected database, string = the database containing the specified table, resource = the database corresponding to the specified mysql resource. 
    10661098     * @return false|string false on failure, version number on success 
    10671099     */ 
Note: See TracChangeset for help on using the changeset viewer.