Make WordPress Core


Ignore:
Timestamp:
08/26/2023 06:09:07 PM (9 months ago)
Author:
johnbillion
Message:

Database: Improve the documentation for various methods in the wpdb class.

See #58833

File:
1 edited

Legend:

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

    r56475 r56476  
    24482448     * Examples:
    24492449     *
    2450      *     wpdb::insert( 'table', array( 'column' => 'foo', 'field' => 'bar' ) )
    2451      *     wpdb::insert( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( '%s', '%d' ) )
     2450     *     $wpdb->insert(
     2451     *         'table',
     2452     *         array(
     2453     *             'column1' => 'foo',
     2454     *             'column2' => 'bar',
     2455     *         )
     2456     *     );
     2457     *     $wpdb->insert(
     2458     *         'table',
     2459     *         array(
     2460     *             'column1' => 'foo',
     2461     *             'column2' => 1337,
     2462     *         ),
     2463     *         array(
     2464     *             '%s',
     2465     *             '%d',
     2466     *         )
     2467     *     );
    24522468     *
    24532469     * @since 2.5.0
     
    24572473     * @see wp_set_wpdb_vars()
    24582474     *
    2459      * @param string       $table  Table name.
    2460      * @param array        $data   Data to insert (in column => value pairs).
    2461      *                             Both `$data` columns and `$data` values should be "raw" (neither should be SQL escaped).
    2462      *                             Sending a null value will cause the column to be set to NULL - the corresponding
    2463      *                             format is ignored in this case.
    2464      * @param array|string $format Optional. An array of formats to be mapped to each of the value in `$data`.
    2465      *                             If string, that format will be used for all of the values in `$data`.
    2466      *                             A format is one of '%d', '%f', '%s' (integer, float, string).
    2467      *                             If omitted, all values in `$data` will be treated as strings unless otherwise
    2468      *                             specified in wpdb::$field_types. Default null.
     2475     * @param string          $table  Table name.
     2476     * @param array           $data   Data to insert (in column => value pairs).
     2477     *                                Both `$data` columns and `$data` values should be "raw" (neither should be SQL escaped).
     2478     *                                Sending a null value will cause the column to be set to NULL - the corresponding
     2479     *                                format is ignored in this case.
     2480     * @param string[]|string $format Optional. An array of formats to be mapped to each of the value in `$data`.
     2481     *                                If string, that format will be used for all of the values in `$data`.
     2482     *                                A format is one of '%d', '%f', '%s' (integer, float, string).
     2483     *                                If omitted, all values in `$data` will be treated as strings unless otherwise
     2484     *                                specified in wpdb::$field_types. Default null.
    24692485     * @return int|false The number of rows inserted, or false on error.
    24702486     */
     
    24742490
    24752491    /**
    2476      * Replaces a row in the table.
     2492     * Replaces a row in the table or inserts it if it does not exist, based on a PRIMARY KEY or a UNIQUE index.
     2493     *
     2494     * A REPLACE works exactly like an INSERT, except that if an old row in the table has the same value as a new row
     2495     * for a PRIMARY KEY or a UNIQUE index, the old row is deleted before the new row is inserted.
    24772496     *
    24782497     * Examples:
    24792498     *
    2480      *     wpdb::replace( 'table', array( 'column' => 'foo', 'field' => 'bar' ) )
    2481      *     wpdb::replace( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( '%s', '%d' ) )
     2499     *     $wpdb->replace(
     2500     *         'table',
     2501     *         array(
     2502     *             'ID'      => 123,
     2503     *             'column1' => 'foo',
     2504     *             'column2' => 'bar',
     2505     *         )
     2506     *     );
     2507     *     $wpdb->replace(
     2508     *         'table',
     2509     *         array(
     2510     *             'ID'      => 456,
     2511     *             'column1' => 'foo',
     2512     *             'column2' => 1337,
     2513     *         ),
     2514     *         array(
     2515     *             '%d',
     2516     *             '%s',
     2517     *             '%d',
     2518     *         )
     2519     *     );
    24822520     *
    24832521     * @since 3.0.0
     
    24872525     * @see wp_set_wpdb_vars()
    24882526     *
    2489      * @param string       $table  Table name.
    2490      * @param array        $data   Data to insert (in column => value pairs).
    2491      *                             Both `$data` columns and `$data` values should be "raw" (neither should be SQL escaped).
    2492      *                             Sending a null value will cause the column to be set to NULL - the corresponding
    2493      *                             format is ignored in this case.
    2494      * @param array|string $format Optional. An array of formats to be mapped to each of the value in `$data`.
    2495      *                             If string, that format will be used for all of the values in `$data`.
    2496      *                             A format is one of '%d', '%f', '%s' (integer, float, string).
    2497      *                             If omitted, all values in `$data` will be treated as strings unless otherwise
    2498      *                             specified in wpdb::$field_types. Default null.
     2527     * @param string          $table  Table name.
     2528     * @param array           $data   Data to insert (in column => value pairs).
     2529     *                                Both `$data` columns and `$data` values should be "raw" (neither should be SQL escaped).
     2530     *                                A primary key or unique index is required to perform a replace operation.
     2531     *                                Sending a null value will cause the column to be set to NULL - the corresponding
     2532     *                                format is ignored in this case.
     2533     * @param string[]|string $format Optional. An array of formats to be mapped to each of the value in `$data`.
     2534     *                                If string, that format will be used for all of the values in `$data`.
     2535     *                                A format is one of '%d', '%f', '%s' (integer, float, string).
     2536     *                                If omitted, all values in `$data` will be treated as strings unless otherwise
     2537     *                                specified in wpdb::$field_types. Default null.
    24992538     * @return int|false The number of rows affected, or false on error.
    25002539     */
     
    25142553     * @see wp_set_wpdb_vars()
    25152554     *
    2516      * @param string       $table  Table name.
    2517      * @param array        $data   Data to insert (in column => value pairs).
    2518      *                             Both `$data` columns and `$data` values should be "raw" (neither should be SQL escaped).
    2519      *                             Sending a null value will cause the column to be set to NULL - the corresponding
    2520      *                             format is ignored in this case.
    2521      * @param array|string $format Optional. An array of formats to be mapped to each of the value in `$data`.
    2522      *                             If string, that format will be used for all of the values in `$data`.
    2523      *                             A format is one of '%d', '%f', '%s' (integer, float, string).
    2524      *                             If omitted, all values in `$data` will be treated as strings unless otherwise
    2525      *                             specified in wpdb::$field_types. Default null.
    2526      * @param string       $type   Optional. Type of operation. Either 'INSERT' or 'REPLACE'.
    2527      *                             Default 'INSERT'.
     2555     * @param string          $table  Table name.
     2556     * @param array           $data   Data to insert (in column => value pairs).
     2557     *                                Both `$data` columns and `$data` values should be "raw" (neither should be SQL escaped).
     2558     *                                Sending a null value will cause the column to be set to NULL - the corresponding
     2559     *                                format is ignored in this case.
     2560     * @param string[]|string $format Optional. An array of formats to be mapped to each of the value in `$data`.
     2561     *                                If string, that format will be used for all of the values in `$data`.
     2562     *                                A format is one of '%d', '%f', '%s' (integer, float, string).
     2563     *                                If omitted, all values in `$data` will be treated as strings unless otherwise
     2564     *                                specified in wpdb::$field_types. Default null.
     2565     * @param string          $type   Optional. Type of operation. Either 'INSERT' or 'REPLACE'.
     2566     *                                Default 'INSERT'.
    25282567     * @return int|false The number of rows affected, or false on error.
    25292568     */
     
    25662605     * Examples:
    25672606     *
    2568      *     wpdb::update( 'table', array( 'column' => 'foo', 'field' => 'bar' ), array( 'ID' => 1 ) )
    2569      *     wpdb::update( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( 'ID' => 1 ), array( '%s', '%d' ), array( '%d' ) )
     2607     *     $wpdb->update(
     2608     *         'table',
     2609     *         array(
     2610     *             'column1' => 'foo',
     2611     *             'column2' => 'bar',
     2612     *         ),
     2613     *         array(
     2614     *             'ID' => 1,
     2615     *         )
     2616     *     );
     2617     *     $wpdb->update(
     2618     *         'table',
     2619     *         array(
     2620     *             'column1' => 'foo',
     2621     *             'column2' => 1337,
     2622     *         ),
     2623     *         array(
     2624     *             'ID' => 1,
     2625     *         ),
     2626     *         array(
     2627     *             '%s',
     2628     *             '%d',
     2629     *         ),
     2630     *         array(
     2631     *             '%d',
     2632     *         )
     2633     *     );
    25702634     *
    25712635     * @since 2.5.0
     
    25752639     * @see wp_set_wpdb_vars()
    25762640     *
    2577      * @param string       $table        Table name.
    2578      * @param array        $data         Data to update (in column => value pairs).
    2579      *                                   Both $data columns and $data values should be "raw" (neither should be SQL escaped).
    2580      *                                   Sending a null value will cause the column to be set to NULL - the corresponding
    2581      *                                   format is ignored in this case.
    2582      * @param array        $where        A named array of WHERE clauses (in column => value pairs).
    2583      *                                   Multiple clauses will be joined with ANDs.
    2584      *                                   Both $where columns and $where values should be "raw".
    2585      *                                   Sending a null value will create an IS NULL comparison - the corresponding
    2586      *                                   format will be ignored in this case.
    2587      * @param array|string $format       Optional. An array of formats to be mapped to each of the values in $data.
    2588      *                                   If string, that format will be used for all of the values in $data.
    2589      *                                   A format is one of '%d', '%f', '%s' (integer, float, string).
    2590      *                                   If omitted, all values in $data will be treated as strings unless otherwise
    2591      *                                   specified in wpdb::$field_types. Default null.
    2592      * @param array|string $where_format Optional. An array of formats to be mapped to each of the values in $where.
    2593      *                                   If string, that format will be used for all of the items in $where.
    2594      *                                   A format is one of '%d', '%f', '%s' (integer, float, string).
    2595      *                                   If omitted, all values in $where will be treated as strings. Default null.
     2641     * @param string       $table           Table name.
     2642     * @param array        $data            Data to update (in column => value pairs).
     2643     *                                      Both $data columns and $data values should be "raw" (neither should be SQL escaped).
     2644     *                                      Sending a null value will cause the column to be set to NULL - the corresponding
     2645     *                                      format is ignored in this case.
     2646     * @param array        $where           A named array of WHERE clauses (in column => value pairs).
     2647     *                                      Multiple clauses will be joined with ANDs.
     2648     *                                      Both $where columns and $where values should be "raw".
     2649     *                                      Sending a null value will create an IS NULL comparison - the corresponding
     2650     *                                      format will be ignored in this case.
     2651     * @param string[]|string $format       Optional. An array of formats to be mapped to each of the values in $data.
     2652     *                                      If string, that format will be used for all of the values in $data.
     2653     *                                      A format is one of '%d', '%f', '%s' (integer, float, string).
     2654     *                                      If omitted, all values in $data will be treated as strings unless otherwise
     2655     *                                      specified in wpdb::$field_types. Default null.
     2656     * @param string[]|string $where_format Optional. An array of formats to be mapped to each of the values in $where.
     2657     *                                      If string, that format will be used for all of the items in $where.
     2658     *                                      A format is one of '%d', '%f', '%s' (integer, float, string).
     2659     *                                      If omitted, all values in $where will be treated as strings unless otherwise
     2660     *                                      specified in wpdb::$field_types. Default null.
    25962661     * @return int|false The number of rows updated, or false on error.
    25972662     */
     
    26462711     * Examples:
    26472712     *
    2648      *     wpdb::delete( 'table', array( 'ID' => 1 ) )
    2649      *     wpdb::delete( 'table', array( 'ID' => 1 ), array( '%d' ) )
     2713     *     $wpdb->delete(
     2714     *         'table',
     2715     *         array(
     2716     *             'ID' => 1,
     2717     *         )
     2718     *     );
     2719     *     $wpdb->delete(
     2720     *         'table',
     2721     *         array(
     2722     *             'ID' => 1,
     2723     *         ),
     2724     *         array(
     2725     *             '%d',
     2726     *         )
     2727     *     );
    26502728     *
    26512729     * @since 3.4.0
     
    26552733     * @see wp_set_wpdb_vars()
    26562734     *
    2657      * @param string       $table        Table name.
    2658      * @param array        $where        A named array of WHERE clauses (in column => value pairs).
    2659      *                                   Multiple clauses will be joined with ANDs.
    2660      *                                   Both $where columns and $where values should be "raw".
    2661      *                                   Sending a null value will create an IS NULL comparison - the corresponding
    2662      *                                   format will be ignored in this case.
    2663      * @param array|string $where_format Optional. An array of formats to be mapped to each of the values in $where.
    2664      *                                   If string, that format will be used for all of the items in $where.
    2665      *                                   A format is one of '%d', '%f', '%s' (integer, float, string).
    2666      *                                   If omitted, all values in $data will be treated as strings unless otherwise
    2667      *                                   specified in wpdb::$field_types. Default null.
     2735     * @param string          $table        Table name.
     2736     * @param array           $where        A named array of WHERE clauses (in column => value pairs).
     2737     *                                      Multiple clauses will be joined with ANDs.
     2738     *                                      Both $where columns and $where values should be "raw".
     2739     *                                      Sending a null value will create an IS NULL comparison - the corresponding
     2740     *                                      format will be ignored in this case.
     2741     * @param string[]|string $where_format Optional. An array of formats to be mapped to each of the values in $where.
     2742     *                                      If string, that format will be used for all of the items in $where.
     2743     *                                      A format is one of '%d', '%f', '%s' (integer, float, string).
     2744     *                                      If omitted, all values in $data will be treated as strings unless otherwise
     2745     *                                      specified in wpdb::$field_types. Default null.
    26682746     * @return int|false The number of rows deleted, or false on error.
    26692747     */
     
    27092787     * @since 4.2.0
    27102788     *
    2711      * @param string $table  Table name.
    2712      * @param array  $data   Field/value pair.
    2713      * @param mixed  $format Format for each field.
     2789     * @param string          $table  Table name.
     2790     * @param array           $data   Array of values keyed by their field names.
     2791     * @param string[]|string $format Formats or format to be mapped to the values in the data.
    27142792     * @return array|false An array of fields that contain paired value and formats.
    27152793     *                     False for invalid values.
     
    27692847     * @since 4.2.0
    27702848     *
    2771      * @param array $data   Array of fields to values.
    2772      * @param mixed $format Formats to be mapped to the values in $data.
    2773      * @return array Array, keyed by field names with values being an array
    2774      *               of 'value' and 'format' keys.
     2849     * @param array           $data   Array of values keyed by their field names.
     2850     * @param string[]|string $format Formats or format to be mapped to the values in the data.
     2851     * @return array {
     2852     *     Array of values and formats keyed by their field names.
     2853     *
     2854     *     @type mixed  $value  The value to be formatted.
     2855     *     @type string $format The format to be mapped to the value.
     2856     * }
    27752857     */
    27762858    protected function process_field_formats( $data, $format ) {
     
    28042886     * @since 4.2.0
    28052887     *
    2806      * @param array  $data  As it comes from the wpdb::process_field_formats() method.
     2888     * @param array $data {
     2889     *     Array of values and formats keyed by their field names,
     2890     *     as it comes from the wpdb::process_field_formats() method.
     2891     *
     2892     *     @type array ...$0 {
     2893     *         Value and format for this field.
     2894     *
     2895     *         @type mixed  $value  The value to be formatted.
     2896     *         @type string $format The format to be mapped to the value.
     2897     *     }
     2898     * }
    28072899     * @param string $table Table name.
    2808      * @return array|false The same array as $data with additional 'charset' keys.
    2809      *                     False on failure.
     2900     * @return array|false {
     2901     *     The same array of data with additional 'charset' keys, or false if
     2902     *     the charset for the table cannot be found.
     2903     *
     2904     *     @type array ...$0 {
     2905     *         Value, format, and charset for this field.
     2906     *
     2907     *         @type mixed        $value   The value to be formatted.
     2908     *         @type string       $format  The format to be mapped to the value.
     2909     *         @type string|false $charset The charset to be used for the value.
     2910     *     }
     2911     * }
    28102912     */
    28112913    protected function process_field_charsets( $data, $table ) {
     
    28352937     * @since 4.2.1
    28362938     *
    2837      * @param array  $data  As it comes from the wpdb::process_field_charsets() method.
     2939     * @param array $data {
     2940     *     Array of values, formats, and charsets keyed by their field names,
     2941     *     as it comes from the wpdb::process_field_charsets() method.
     2942     *
     2943     *     @type array ...$0 {
     2944     *         Value, format, and charset for this field.
     2945     *
     2946     *         @type mixed        $value   The value to be formatted.
     2947     *         @type string       $format  The format to be mapped to the value.
     2948     *         @type string|false $charset The charset to be used for the value.
     2949     *     }
     2950     * }
    28382951     * @param string $table Table name.
    2839      * @return array|false The same array as $data with additional 'length' keys, or false if
    2840      *                     any of the values were too long for their corresponding field.
     2952     * @return array|false {
     2953     *     The same array of data with additional 'length' keys, or false if
     2954     *     information for the table cannot be found.
     2955     *
     2956     *     @type array ...$0 {
     2957     *         Value, format, charset, and length for this field.
     2958     *
     2959     *         @type mixed        $value   The value to be formatted.
     2960     *         @type string       $format  The format to be mapped to the value.
     2961     *         @type string|false $charset The charset to be used for the value.
     2962     *         @type array|false  $length  {
     2963     *             Information about the maximum length of the value.
     2964     *             False if the column has no length.
     2965     *
     2966     *             @type string $type   One of 'byte' or 'char'.
     2967     *             @type int    $length The column length.
     2968     *         }
     2969     *     }
     2970     * }
    28412971     */
    28422972    protected function process_field_lengths( $data, $table ) {
     
    28622992
    28632993    /**
    2864      * Retrieves one variable from the database.
     2994     * Retrieves one value from the database.
    28652995     *
    28662996     * Executes a SQL query and returns the value from the SQL result.
     
    31703300         * @since 4.2.0
    31713301         *
    3172          * @param string|null $charset The character set to use. Default null.
    3173          * @param string      $table   The name of the table being checked.
    3174          * @param string      $column  The name of the column being checked.
     3302         * @param string|null|false|WP_Error $charset The character set to use. Default null.
     3303         * @param string                     $table   The name of the table being checked.
     3304         * @param string                     $column  The name of the column being checked.
    31753305         */
    31763306        $charset = apply_filters( 'pre_get_col_charset', null, $table, $column );
     
    32243354     *     example, numeric column), WP_Error object if there was an error.
    32253355     *
     3356     *     @type string $type   One of 'byte' or 'char'.
    32263357     *     @type int    $length The column length.
    3227      *     @type string $type   One of 'byte' or 'char'.
    32283358     * }
    32293359     */
     
    34003530     * @since 4.2.0
    34013531     *
    3402      * @param array $data Array of value arrays. Each value array has the keys 'value' and 'charset'.
     3532     * @param array $data Array of value arrays. Each value array has the keys 'value', 'charset', and 'length'.
    34033533     *                    An optional 'ascii' key can be set to false to avoid redundant ASCII checks.
    34043534     * @return array|WP_Error The $data parameter, with invalid characters removed from each value.
Note: See TracChangeset for help on using the changeset viewer.