WordPress.org
Get WordPress

Make WordPress Core

Changeset 10911


Ignore:
Timestamp:
04/10/2009 09:57:40 PM (15 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.