WordPress.org
Get WordPress

Make WordPress Core

Changeset 10911


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