WordPress.org

Make WordPress Core

Changeset 41632


Ignore:
Timestamp:
09/28/2017 11:44:30 AM (4 years ago)
Author:
pento
Message:

Docs: Update the documentation for wpdb::prepare()

The inline documentation for wpdb::prepare() was kind of confusing, and didn't describe some of the behaviour correctly.

Fixes #41983.

File:
1 edited

Legend:

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

    r41629 r41632  
    11951195     * Prepares a SQL query for safe execution. Uses sprintf()-like syntax.
    11961196     *
    1197      * The following directives can be used in the query format string:
     1197     * The following placeholders can be used in the query string:
    11981198     *   %d (integer)
    11991199     *   %f (float)
    12001200     *   %s (string)
    1201      *   %% (literal percentage sign - no argument needed)
    1202      *
    1203      * All of %d, %f, and %s are to be left unquoted in the query string and they need an argument passed for them.
    1204      * Literals (%) as parts of the query must be properly written as %%.
    1205      *
    1206      * This function only supports a small subset of the sprintf syntax; it only supports %d (integer), %f (float), and %s (string).
    1207      * Does not support sign, padding, alignment, width or precision specifiers.
    1208      * Does not support argument numbering/swapping.
    1209      *
    1210      * May be called like {@link https://secure.php.net/sprintf sprintf()} or like {@link https://secure.php.net/vsprintf vsprintf()}.
    1211      *
    1212      * Both %d and %s should be left unquoted in the query string.
    1213      *
    1214      *     $wpdb->prepare( "SELECT * FROM `table` WHERE `column` = %s AND `field` = %d", 'foo', 1337 );
     1201     *
     1202     * All placeholders MUST be left unquoted in the query string. A corresponding argument MUST be passed for each placeholder.
     1203     *
     1204     * Literal percentage signs (%) in the query string must be written as %%. Percentage wildcards (for example, to use in LIKE syntax)
     1205     * must be passed in the string argument, it cannot be inserted in the query string.
     1206     *
     1207     * This method DOES NOT support sign, padding, alignment, width or precision specifiers.
     1208     * This method DOES NOT support argument numbering or swapping.
     1209     *
     1210     * Arguments may be passed as individual arguments to the method, or as a single array containing all arguments. A combination
     1211     * of the two is not supported.
     1212     *
     1213     * Examples:
     1214     *     $wpdb->prepare( "SELECT * FROM `table` WHERE `column` = %s AND `field` = %d OR `other_field` LIKE %s", array( 'foo', 1337, '%bar' ) );
    12151215     *     $wpdb->prepare( "SELECT DATE_FORMAT(`field`, '%%c') FROM `table` WHERE `column` = %s", 'foo' );
    12161216     *
     
    12191219     *
    12201220     * @param string      $query    Query statement with sprintf()-like placeholders
    1221      * @param array|mixed $args     The array of variables to substitute into the query's placeholders if being called like
    1222      *                              {@link https://secure.php.net/vsprintf vsprintf()}, or the first variable to substitute into the query's placeholders if
    1223      *                              being called like {@link https://secure.php.net/sprintf sprintf()}.
    1224      * @param mixed       $args,... further variables to substitute into the query's placeholders if being called like
    1225      *                              {@link https://secure.php.net/sprintf sprintf()}.
     1221     * @param array|mixed $args     The array of variables to substitute into the query's placeholders if being called with an array of arguments,
     1222     *                              or the first variable to substitute into the query's placeholders if being called with individual arguments.
     1223     * @param mixed       $args,... further variables to substitute into the query's placeholders if being called wih individual arguments.
    12261224     * @return string|void Sanitized query string, if there is a query to prepare.
    12271225     */
Note: See TracChangeset for help on using the changeset viewer.