WordPress.org
Get WordPress

Make WordPress Core

Ticket #9506: 9506.diff

File 9506.diff, 12.0 KB (added by mdawaffe, 17 years ago)

  • wp-includes/wp-db.php

     
    373373         * Sets the table prefix for the WordPress tables.
    374374         *
    375375         * Also allows for the CUSTOM_USER_TABLE and CUSTOM_USER_META_TABLE to
    376          * override the WordPress users and usersmeta tables.
     376         * override the WordPress users and usersmeta tables that would otherwise be determined by the $prefix.
    377377         *
    378378         * @since 2.5.0
    379379         *
    380380         * @param string $prefix Alphanumeric name for the new prefix.
    381          * @return string Old prefix
     381         * @return string|WP_Error Old prefix or WP_Error on error
    382382         */
    383383        function set_prefix($prefix) {
    384384
    … …  
    488488        }
    489489
    490490        /**
    491          * Prepares a SQL query for safe use, using sprintf() syntax.
     491         * Prepares a SQL query for safe execution.  Uses sprintf()-like syntax.
    492492         *
    493          * @link http://php.net/sprintf See for syntax to use for query string.
     493         * This function only supports a small subset of the sprintf syntax; it only supports %d (decimal number), %s (string).
     494         * Does not support sign, padding, alignment, width or precision specifiers.
     495         * Does not support argument numbering/swapping.
     496         *
     497         * May be called like {@link http://php.net/sprintf sprintf()} or like {@link http://php.net/vsprintf vsprintf()}.
     498         *
     499         * Both %d and %s should be left unquoted in the query string.
     500         *
     501         * <code>
     502         * wpdb::prepare( "SELECT * FROM `table` WHERE `column` = %s AND `field` = %d", "foo", 1337 )
     503         * </code>
     504         *
     505         * @link http://php.net/sprintf Description of syntax.
    494506         * @since 2.3.0
    495507         *
    496          * @param null|string $args If string, first parameter must be query statement
    497          * @param mixed $args,... If additional parameters, they will be set inserted into the query.
     508         * @param string $query Query statement with sprintf()-like placeholders
     509         * @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()}.
     510         * @param mixed $args,... further variables to substitute into the query's placeholders if being called like {@link http://php.net/sprintf sprintf()}.
    498511         * @return null|string Sanitized query string
    499512         */
    500         function prepare($args=null) {
    501                 if ( is_null( $args ) )
     513        function prepare($query = null) { // ( $query, *$args )
     514                if ( is_null( $query ) )
    502515                        return;
    503516                $args = func_get_args();
    504                 $query = array_shift($args);
    505                 // If args were passed as an array, move them up
     517                array_shift($args);
     518                // If args were passed as an array (as in vsprintf), move them up
    506519                if ( isset($args[0]) && is_array($args[0]) )
    507520                        $args = $args[0];
    508521                $query = str_replace("'%s'", '%s', $query); // in case someone mistakenly already singlequoted it
    … …  
    623636         * @since 0.71
    624637         *
    625638         * @param string $query
    626          * @return unknown
     639         * @return int|false Number of rows affected/selected or false on error
    627640         */
    628641        function query($query) {
    629642                if ( ! $this->ready )
    … …  
    693706        }
    694707
    695708        /**
    696          * Insert an array of data into a table.
     709         * Insert a row into a table.
    697710         *
     711         * <code>
     712         * wpdb::insert( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( '%s', '%d' ) )
     713         * </code>
     714         *
    698715         * @since 2.5.0
     716         * @see wpdb::prepare()
    699717         *
    700718         * @param string $table table name
    701          * @param array $data Should not already be SQL-escaped
    702          * @param array|string $format The format of the field values.
    703          * @return mixed Results of $this->query()
     719         * @param array $data Data to insert (in column => value pairs).  Both $data columns and $data values should be "raw" (neither should be SQL escaped).
     720         * @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.
     721         * @return int|false The number of rows inserted, or false on error.
    704722         */
    705723        function insert($table, $data, $format = null) {
    706724                global $db_field_types;
    … …  
    721739                return $this->query( $this->prepare( $sql, $data) );
    722740        }
    723741
     742       
    724743        /**
    725          * Update a row in the table with an array of data.
     744         * Update a row in the table
    726745         *
     746         * <code>
     747         * wpdb::update( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( 'ID' => 1 ), array( '%s', '%d' ), array( '%d' ) )
     748         * </code>
     749         *
    727750         * @since 2.5.0
     751         * @see wpdb::prepare()
    728752         *
    729753         * @param string $table table name
    730          * @param array $data Should not already be SQL-escaped
    731          * @param array $where A named array of WHERE column => value relationships.  Multiple member pairs will be joined with ANDs.
    732          * @param array|string $format The format of the field values.
    733          * @param array|string $where_format The format of the where field values.
    734          * @return mixed Results of $this->query()
     754         * @param array $data Data to update (in column => value pairs).  Both $data columns and $data values should be "raw" (neither should be SQL escaped).
     755         * @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".
     756         * @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.
     757         * @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.
     758         * @return int|false The number of rows updated, or false on error.
    735759         */
    736760        function update($table, $data, $where, $format = null, $where_format = null) {
    737761                global $db_field_types;
    … …  
    769793        /**
    770794         * Retrieve one variable from the database.
    771795         *
    772          * This combines the functionality of wpdb::get_row() and wpdb::get_col(),
    773          * so both the column and row can be picked.
     796         * Executes a SQL query and returns the value from the SQL result.
     797         * 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.
     798         * If $query is null, this function returns the value in the specified column and row from the previous SQL result.
    774799         *
    775          * It is possible to use this function without executing more queries. If
    776          * you already made a query, you can set the $query to 'null' value and just
    777          * retrieve either the column and row of the last query result.
    778          *
    779800         * @since 0.71
    780801         *
    781          * @param string $query Can be null as well, for caching
    782          * @param int $x Column num to return
    783          * @param int $y Row num to return
    784          * @return mixed Database query results
     802         * @param string|null $query SQL query.  If null, use the result from the previous query.
     803         * @param int $x (optional) Column of value to return.  Indexed from 0.
     804         * @param int $y (optional) Row of value to return.  Indexed from 0.
     805         * @return string Database query result
    785806         */
    786807        function get_var($query=null, $x = 0, $y = 0) {
    787808                $this->func_call = "\$db->get_var(\"$query\",$x,$y)";
    … …  
    800821        /**
    801822         * Retrieve one row from the database.
    802823         *
     824         * Executes a SQL query and returns the row from the SQL result.
     825         *
    803826         * @since 0.71
    804827         *
    805          * @param string $query SQL query
    806          * @param string $output ARRAY_A | ARRAY_N | OBJECT
    807          * @param int $y Row num to return
    808          * @return mixed Database query results
     828         * @param string|null $query SQL query.
     829         * @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.
     830         * @param int $y (optional) Row to return.  Indexed from 0.
     831         * @return mixed Database query result in format specifed by $output
    809832         */
    810833        function get_row($query = null, $output = OBJECT, $y = 0) {
    811834                $this->func_call = "\$db->get_row(\"$query\",$output,$y)";
    … …  
    831854        /**
    832855         * Retrieve one column from the database.
    833856         *
     857         * Executes a SQL query and returns the column from the SQL result.
     858         * If the SQL result contains more than one column, this function returns the column specified.
     859         * If $query is null, this function returns the specified column from the previous SQL result.
     860         *
    834861         * @since 0.71
    835862         *
    836          * @param string $query Can be null as well, for caching
    837          * @param int $x Col num to return. Starts from 0.
    838          * @return array Column results
     863         * @param string|null $query SQL query.  If null, use the result from the previous query.
     864         * @param int $x Column to return.  Indexed from 0.
     865         * @return array Database query result.  Array indexed from 0 by SQL result row number.
    839866         */
    840867        function get_col($query = null , $x = 0) {
    841868                if ( $query )
    … …  
    850877        }
    851878
    852879        /**
    853          * Retrieve an entire result set from the database.
     880         * Retrieve an entire SQL result set from the database (i.e., many rows)
    854881         *
     882         * Executes a SQL query and returns the entire SQL result.
     883         *
    855884         * @since 0.71
    856885         *
    857          * @param string|null $query Can also be null to pull from the cache
    858          * @param string $output ARRAY_A | ARRAY_N | OBJECT_K | OBJECT
     886         * @param string $query SQL query.
     887         * @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.
    859888         * @return mixed Database query results
    860889         */
    861890        function get_results($query = null, $output = OBJECT) {
    … …  
    926955         *
    927956         * @since 1.5.0
    928957         *
    929          * @return bool Always returns true
     958         * @return true
    930959         */
    931960        function timer_start() {
    932961                $mtime = microtime();
    … …  
    951980        }
    952981
    953982        /**
    954          * Wraps fatal errors in a nice header and footer and dies.
     983         * Wraps errors in a nice header and footer and dies.
    955984         *
     985         * Will not die if wpdb::$show_errors is true
     986         *
    956987         * @since 1.5.0
    957988         *
    958989         * @param string $message
    959          * @return unknown
     990         * @return false|void
    960991         */
    961992        function bail($message) {
    962993                if ( !$this->show_errors ) {
    … …  
    9701001        }
    9711002
    9721003        /**
    973          * Whether or not MySQL database is minimal required version.
     1004         * Whether or not MySQL database is at least the required minimum version.
    9741005         *
    9751006         * @since 2.5.0
    9761007         * @uses $wp_version
    … …  
    9861017        }
    9871018
    9881019        /**
    989          * Whether of not the database version supports collation.
     1020         * Whether of not the database supports collation.
    9901021         *
    9911022         * Called when WordPress is generating the table scheme.
    9921023         *
    … …  
    10021033        /**
    10031034         * Generic function to determine if a database supports a particular feature
    10041035         * @param string $db_cap the feature
    1005          * @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)
     1036         * @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.
    10061037         * @return bool
    10071038         */
    10081039        function has_cap( $db_cap ) {
    … …  
    10531084
    10541085        /**
    10551086         * The database version number
     1087         * @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.
    10561088         * @return false|string false on failure, version number on success
    10571089         */
    10581090        function db_version() {