[ Index ]

PHP Cross Reference of WordPress

title

Body

[close]

/wp-includes/ -> wp-db.php (summary)

WordPress DB Class Original code from {@link http://php.justinvincent.com Justin Vincent (justin@visunet.ie)}

File Size: 3622 lines (104 kb)
Included or required: 1 time
Referenced: 0 times
Includes or requires: 0 files

Defines 1 class

wpdb:: (70 methods):
  __construct()
  __destruct()
  __get()
  __set()
  __isset()
  __unset()
  init_charset()
  determine_charset()
  set_charset()
  set_sql_mode()
  set_prefix()
  set_blog_id()
  get_blog_prefix()
  tables()
  select()
  _weak_escape()
  _real_escape()
  _escape()
  escape()
  escape_by_ref()
  prepare()
  esc_like()
  print_error()
  show_errors()
  hide_errors()
  suppress_errors()
  flush()
  db_connect()
  parse_db_host()
  check_connection()
  query()
  _do_query()
  log_query()
  placeholder_escape()
  add_placeholder_escape()
  remove_placeholder_escape()
  insert()
  replace()
  _insert_replace_helper()
  update()
  delete()
  process_fields()
  process_field_formats()
  process_field_charsets()
  process_field_lengths()
  get_var()
  get_row()
  get_col()
  get_results()
  get_table_charset()
  get_col_charset()
  get_col_length()
  check_ascii()
  check_safe_collation()
  strip_invalid_text()
  strip_invalid_text_from_query()
  strip_invalid_text_for_column()
  get_table_from_query()
  load_col_info()
  get_col_info()
  timer_start()
  timer_stop()
  bail()
  close()
  check_database_version()
  supports_collation()
  get_charset_collate()
  has_cap()
  get_caller()
  db_version()


Class: wpdb  - X-Ref

WordPress Database Access Abstraction Object

It is possible to replace this class with your own
by setting the $wpdb global variable in wp-content/db.php
file to your class. The wpdb class will still be included,
so you can extend it or simply use your own.

__construct( $dbuser, $dbpassword, $dbname, $dbhost )   X-Ref
Connects to the database server and selects a database

PHP5 style constructor for compatibility with PHP5. Does
the actual setting up of the class properties and connection
to the database.

param: string $dbuser     MySQL database user
param: string $dbpassword MySQL database password
param: string $dbname     MySQL database name
param: string $dbhost     MySQL database host
since: 2.0.8

__destruct()   X-Ref
PHP5 style destructor and will run when database object is destroyed.

return: true
since: 2.0.8

__get( $name )   X-Ref
Makes private properties readable for backward compatibility.

return: mixed The private member
param: string $name The private member to get, and optionally process
since: 3.5.0

__set( $name, $value )   X-Ref
Makes private properties settable for backward compatibility.

param: string $name  The private member to set
param: mixed  $value The value to set
since: 3.5.0

__isset( $name )   X-Ref
Makes private properties check-able for backward compatibility.

return: bool If the member is set or not
param: string $name  The private member to check
since: 3.5.0

__unset( $name )   X-Ref
Makes private properties un-settable for backward compatibility.

param: string $name  The private member to unset
since: 3.5.0

init_charset()   X-Ref
Set $this->charset and $this->collate

since: 3.1.0

determine_charset( $charset, $collate )   X-Ref
Determines the best charset and collation to use given a charset and collation.

For example, when able, utf8mb4 should be used instead of utf8.

return: array The most appropriate character set and collation to use.
param: string $charset The character set to check.
param: string $collate The collation to check.
since: 4.6.0

set_charset( $dbh, $charset = null, $collate = null )   X-Ref
Sets the connection's character set.

param: resource $dbh     The resource given by mysql_connect
param: string   $charset Optional. The character set. Default null.
param: string   $collate Optional. The collation. Default null.
since: 3.1.0

set_sql_mode( $modes = array()   X-Ref
Change the current SQL mode, and ensure its WordPress compatibility.

If no modes are passed, it will ensure the current MySQL server
modes are compatible.

param: array $modes Optional. A list of SQL modes to set.
since: 3.9.0

set_prefix( $prefix, $set_table_names = true )   X-Ref
Sets the table prefix for the WordPress tables.

return: string|WP_Error Old prefix or WP_Error on error
param: string $prefix          Alphanumeric name for the new prefix.
param: bool   $set_table_names Optional. Whether the table names, e.g. wpdb::$posts, should be updated or not.
since: 2.5.0

set_blog_id( $blog_id, $network_id = 0 )   X-Ref
Sets blog id.

return: int previous blog id
param: int $blog_id
param: int $network_id Optional.
since: 3.0.0

get_blog_prefix( $blog_id = null )   X-Ref
Gets blog prefix.

return: string Blog prefix.
param: int $blog_id Optional.
since: 3.0.0

tables( $scope = 'all', $prefix = true, $blog_id = 0 )   X-Ref
Returns an array of WordPress tables.

Also allows for the CUSTOM_USER_TABLE and CUSTOM_USER_META_TABLE to
override the WordPress users and usermeta tables that would otherwise
be determined by the prefix.

The scope argument can take one of the following:

'all' - returns 'all' and 'global' tables. No old tables are returned.
'blog' - returns the blog-level tables for the queried blog.
'global' - returns the global tables for the installation, returning multisite tables only if running multisite.
'ms_global' - returns the multisite global tables, regardless if current installation is multisite.
'old' - returns tables which are deprecated.

return: array Table names. When a prefix is requested, the key is the unprefixed table name.
param: string $scope   Optional. Can be all, global, ms_global, blog, or old tables. Defaults to all.
param: bool   $prefix  Optional. Whether to include table prefixes. Default true. If blog
param: int    $blog_id Optional. The blog_id to prefix. Defaults to wpdb::$blogid. Used only when prefix is requested.
since: 3.0.0

select( $db, $dbh = null )   X-Ref
Selects a database using the current database connection.

The database name will be changed based on the current database
connection. On failure, the execution will bail and display an DB error.

param: string        $db  MySQL database name
param: resource|null $dbh Optional link identifier.
since: 0.71

_weak_escape( $string )   X-Ref
Do not use, deprecated.

Use esc_sql() or wpdb::prepare() instead.

return: string
param: string $string
since: 2.8.0

_real_escape( $string )   X-Ref
Real escape, using mysqli_real_escape_string() or mysql_real_escape_string()

return: string escaped
param: string $string to escape
since: 2.8.0

_escape( $data )   X-Ref
Escape data. Works on arrays.

return: string|array escaped
param: string|array $data
since: 2.8.0

escape( $data )   X-Ref
Do not use, deprecated.

Use esc_sql() or wpdb::prepare() instead.

return: mixed
param: mixed $data
since: 0.71

escape_by_ref( &$string )   X-Ref
Escapes content by reference for insertion into the database, for security

param: string $string to escape
since: 2.3.0

prepare( $query, ...$args )   X-Ref
Prepares a SQL query for safe execution. Uses sprintf()-like syntax.

The following placeholders can be used in the query string:
%d (integer)
%f (float)
%s (string)

All placeholders MUST be left unquoted in the query string. A corresponding argument
MUST be passed for each placeholder.

For compatibility with old behavior, numbered or formatted string placeholders (eg, %1$s, %5s)
will not have quotes added by this function, so should be passed with appropriate quotes around
them for your usage.

Literal percentage signs (%) in the query string must be written as %%. Percentage wildcards (for example,
to use in LIKE syntax) must be passed via a substitution argument containing the complete LIKE string, these
cannot be inserted directly in the query string. Also see wpdb::esc_like().

Arguments may be passed as individual arguments to the method, or as a single array containing
all arguments. A combination of the two is not supported.

Examples:
$wpdb->prepare( "SELECT * FROM `table` WHERE `column` = %s AND `field` = %d OR `other_field` LIKE %s", array( 'foo', 1337, '%bar' ) );
$wpdb->prepare( "SELECT DATE_FORMAT(`field`, '%%c') FROM `table` WHERE `column` = %s", 'foo' );

return: string|void Sanitized query string, if there is a query to prepare.
param: string      $query   Query statement with sprintf()-like placeholders
param: array|mixed $args    The array of variables to substitute into the query's placeholders
param: mixed       ...$args Further variables to substitute into the query's placeholders
since: 2.3.0

esc_like( $text )   X-Ref
First half of escaping for LIKE special characters % and _ before preparing for MySQL.

Use this only before wpdb::prepare() or esc_sql().  Reversing the order is very bad for security.

Example Prepared Statement:

$wild = '%';
$find = 'only 43% of planets';
$like = $wild . $wpdb->esc_like( $find ) . $wild;
$sql  = $wpdb->prepare( "SELECT * FROM $wpdb->posts WHERE post_content LIKE %s", $like );

Example Escape Chain:

$sql  = esc_sql( $wpdb->esc_like( $input ) );

return: string Text in the form of a LIKE phrase. The output is not SQL safe. Call $wpdb::prepare()
param: string $text The raw text to be escaped. The input typed by the user should have no
since: 4.0.0

print_error( $str = '' )   X-Ref
Print SQL/DB error.

return: false|void False if the showing of errors is disabled.
param: string $str The error to display
since: 0.71

show_errors( $show = true )   X-Ref
Enables showing of database errors.

This function should be used only to enable showing of errors.
wpdb::hide_errors() should be used instead for hiding of errors. However,
this function can be used to enable and disable showing of database
errors.

return: bool Old value for showing errors.
param: bool $show Whether to show or hide errors
since: 0.71

hide_errors()   X-Ref
Disables showing of database errors.

By default database errors are not shown.

return: bool Whether showing of errors was active
since: 0.71

suppress_errors( $suppress = true )   X-Ref
Whether to suppress database errors.

By default database errors are suppressed, with a simple
call to this function they can be enabled.

return: bool Old value
param: bool $suppress Optional. New value. Defaults to true.
since: 2.5.0

flush()   X-Ref
Kill cached query results.

since: 0.71

db_connect( $allow_bail = true )   X-Ref
Connect to and select database.

If $allow_bail is false, the lack of database connection will need
to be handled manually.

return: bool True with a successful connection, false on failure.
param: bool $allow_bail Optional. Allows the function to bail. Default true.
since: 3.0.0
since: 3.9.0 $allow_bail parameter added.

parse_db_host( $host )   X-Ref
Parse the DB_HOST setting to interpret it for mysqli_real_connect.

mysqli_real_connect doesn't support the host param including a port or
socket like mysql_connect does. This duplicates how mysql_connect detects
a port and/or socket file.

return: array|bool Array containing the host, the port, the socket and whether
param: string $host The DB_HOST setting to parse.
since: 4.9.0

check_connection( $allow_bail = true )   X-Ref
Checks that the connection to the database is still up. If not, try to reconnect.

If this function is unable to reconnect, it will forcibly die, or if after the
the {@see 'template_redirect'} hook has been fired, return false instead.

If $allow_bail is false, the lack of database connection will need
to be handled manually.

return: bool|void True if the connection is up.
param: bool $allow_bail Optional. Allows the function to bail. Default true.
since: 3.9.0

query( $query )   X-Ref
Perform a MySQL database query, using current database connection.

More information can be found on the codex page.

return: int|bool Boolean true for CREATE, ALTER, TRUNCATE and DROP queries. Number of rows
param: string $query Database query
since: 0.71

_do_query( $query )   X-Ref
Internal function to perform the mysql_query() call.

param: string $query The query to run.
since: 3.9.0

log_query( $query, $query_time, $query_callstack, $query_start, $query_data )   X-Ref
Logs query data.

param: string $query           The query's SQL.
param: float  $query_time      Total time spent on the query, in seconds.
param: string $query_callstack Comma separated list of the calling functions.
param: float  $query_start     Unix timestamp of the time at the start of the query.
param: array  $query_data      Custom query data.
since: 5.3.0

placeholder_escape()   X-Ref
Generates and returns a placeholder escape string for use in queries returned by ::prepare().

return: string String to escape placeholders.
since: 4.8.3

add_placeholder_escape( $query )   X-Ref
Adds a placeholder escape string, to escape anything that resembles a printf() placeholder.

return: string The query with the placeholder escape string inserted where necessary.
param: string $query The query to escape.
since: 4.8.3

remove_placeholder_escape( $query )   X-Ref
Removes the placeholder escape strings from a query.

return: string The query with the placeholder removed.
param: string $query The query from which the placeholder will be removed.
since: 4.8.3

insert( $table, $data, $format = null )   X-Ref
Insert a row into a table.

wpdb::insert( 'table', array( 'column' => 'foo', 'field' => 'bar' ) )
wpdb::insert( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( '%s', '%d' ) )

return: int|false The number of rows inserted, or false on error.
param: string       $table  Table name
param: array        $data   Data to insert (in column => value pairs).
param: array|string $format Optional. An array of formats to be mapped to each of the value in $data.
since: 2.5.0

replace( $table, $data, $format = null )   X-Ref
Replace a row into a table.

wpdb::replace( 'table', array( 'column' => 'foo', 'field' => 'bar' ) )
wpdb::replace( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( '%s', '%d' ) )

return: int|false The number of rows affected, or false on error.
param: string       $table  Table name
param: array        $data   Data to insert (in column => value pairs).
param: array|string $format Optional. An array of formats to be mapped to each of the value in $data.
since: 3.0.0

_insert_replace_helper( $table, $data, $format = null, $type = 'INSERT' )   X-Ref
Helper function for insert and replace.

Runs an insert or replace query based on $type argument.

return: int|false The number of rows affected, or false on error.
param: string       $table  Table name
param: array        $data   Data to insert (in column => value pairs).
param: array|string $format Optional. An array of formats to be mapped to each of the value in $data.
param: string $type         Optional. What type of operation is this? INSERT or REPLACE. Defaults to INSERT.
since: 3.0.0

update( $table, $data, $where, $format = null, $where_format = null )   X-Ref
Update a row in the table

wpdb::update( 'table', array( 'column' => 'foo', 'field' => 'bar' ), array( 'ID' => 1 ) )
wpdb::update( 'table', array( 'column' => 'foo', 'field' => 1337 ), array( 'ID' => 1 ), array( '%s', '%d' ), array( '%d' ) )

return: int|false The number of rows updated, or false on error.
param: string       $table        Table name
param: array        $data         Data to update (in column => value pairs).
param: array        $where        A named array of WHERE clauses (in column => value pairs).
param: array|string $format       Optional. An array of formats to be mapped to each of the values in $data.
param: array|string $where_format Optional. An array of formats to be mapped to each of the values in $where.
since: 2.5.0

delete( $table, $where, $where_format = null )   X-Ref
Delete a row in the table

wpdb::delete( 'table', array( 'ID' => 1 ) )
wpdb::delete( 'table', array( 'ID' => 1 ), array( '%d' ) )

return: int|false The number of rows updated, or false on error.
param: string       $table        Table name
param: array        $where        A named array of WHERE clauses (in column => value pairs).
param: array|string $where_format Optional. An array of formats to be mapped to each of the values in $where.
since: 3.4.0

process_fields( $table, $data, $format )   X-Ref
Processes arrays of field/value pairs and field formats.

This is a helper method for wpdb's CRUD methods, which take field/value
pairs for inserts, updates, and where clauses. This method first pairs
each value with a format. Then it determines the charset of that field,
using that to determine if any invalid text would be stripped. If text is
stripped, then field processing is rejected and the query fails.

return: array|false Returns an array of fields that contain paired values
param: string $table  Table name.
param: array  $data   Field/value pair.
param: mixed  $format Format for each field.
since: 4.2.0

process_field_formats( $data, $format )   X-Ref
Prepares arrays of value/format pairs as passed to wpdb CRUD methods.

return: array Array, keyed by field names with values being an array
param: array $data   Array of fields to values.
param: mixed $format Formats to be mapped to the values in $data.
since: 4.2.0

process_field_charsets( $data, $table )   X-Ref
Adds field charsets to field/value/format arrays generated by
the wpdb::process_field_formats() method.

return: array|false The same array as $data with additional 'charset' keys.
param: array  $data  As it comes from the wpdb::process_field_formats() method.
param: string $table Table name.
since: 4.2.0

process_field_lengths( $data, $table )   X-Ref
For string fields, record the maximum string length that field can safely save.

return: array|false The same array as $data with additional 'length' keys, or false if
param: array  $data  As it comes from the wpdb::process_field_charsets() method.
param: string $table Table name.
since: 4.2.1

get_var( $query = null, $x = 0, $y = 0 )   X-Ref
Retrieve one variable from the database.

Executes a SQL query and returns the value from the SQL result.
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.
If $query is null, this function returns the value in the specified column and row from the previous SQL result.

return: string|null Database query result (as string), or null on failure
param: string|null $query Optional. SQL query. Defaults to null, use the result from the previous query.
param: int         $x     Optional. Column of value to return. Indexed from 0.
param: int         $y     Optional. Row of value to return. Indexed from 0.
since: 0.71

get_row( $query = null, $output = OBJECT, $y = 0 )   X-Ref
Retrieve one row from the database.

Executes a SQL query and returns the row from the SQL result.

return: array|object|null|void Database query result in format specified by $output or null on failure
param: string|null $query  SQL query.
param: string      $output Optional. The required return type. One of OBJECT, ARRAY_A, or ARRAY_N, which correspond to
param: int         $y      Optional. Row to return. Indexed from 0.
since: 0.71

get_col( $query = null, $x = 0 )   X-Ref
Retrieve one column from the database.

Executes a SQL query and returns the column from the SQL result.
If the SQL result contains more than one column, this function returns the column specified.
If $query is null, this function returns the specified column from the previous SQL result.

return: array Database query result. Array indexed from 0 by SQL result row number.
param: string|null $query Optional. SQL query. Defaults to previous query.
param: int         $x     Optional. Column to return. Indexed from 0.
since: 0.71

get_results( $query = null, $output = OBJECT )   X-Ref
Retrieve an entire SQL result set from the database (i.e., many rows)

Executes a SQL query and returns the entire SQL result.

return: array|object|null Database query results
param: string $query  SQL query.
param: string $output Optional. Any of ARRAY_A | ARRAY_N | OBJECT | OBJECT_K constants.
since: 0.71

get_table_charset( $table )   X-Ref
Retrieves the character set for the given table.

return: string|WP_Error Table character set, WP_Error object if it couldn't be found.
param: string $table Table name.
since: 4.2.0

get_col_charset( $table, $column )   X-Ref
Retrieves the character set for the given column.

return: string|false|WP_Error Column character set as a string. False if the column has no
param: string $table  Table name.
param: string $column Column name.
since: 4.2.0

get_col_length( $table, $column )   X-Ref
Retrieve the maximum string length allowed in a given column.
The length may either be specified as a byte length or a character length.

return: array|false|WP_Error array( 'length' => (int), 'type' => 'byte' | 'char' )
param: string $table  Table name.
param: string $column Column name.
since: 4.2.1

check_ascii( $string )   X-Ref
Check if a string is ASCII.

The negative regex is faster for non-ASCII strings, as it allows
the search to finish as soon as it encounters a non-ASCII character.

return: bool True if ASCII, false if not.
param: string $string String to check.
since: 4.2.0

check_safe_collation( $query )   X-Ref
Check if the query is accessing a collation considered safe on the current version of MySQL.

return: bool True if the collation is safe, false if it isn't.
param: string $query The query to check.
since: 4.2.0

strip_invalid_text( $data )   X-Ref
Strips any invalid characters based on value/charset pairs.

return: array|WP_Error The $data parameter, with invalid characters removed from
param: array $data Array of value arrays. Each value array has the keys
since: 4.2.0

strip_invalid_text_from_query( $query )   X-Ref
Strips any invalid characters from the query.

return: string|WP_Error The converted query, or a WP_Error object if the conversion fails.
param: string $query Query to convert.
since: 4.2.0

strip_invalid_text_for_column( $table, $column, $value )   X-Ref
Strips any invalid characters from the string for a given table and column.

return: string|WP_Error The converted string, or a WP_Error object if the conversion fails.
param: string $table  Table name.
param: string $column Column name.
param: string $value  The text to check.
since: 4.2.0

get_table_from_query( $query )   X-Ref
Find the first table name referenced in a query.

return: string|false $table The table name found, or false if a table couldn't be found.
param: string $query The query to search.
since: 4.2.0

load_col_info()   X-Ref
Load the column metadata from the last query.

since: 3.5.0

get_col_info( $info_type = 'name', $col_offset = -1 )   X-Ref
Retrieve column metadata from the last query.

return: mixed Column Results
param: string $info_type  Optional. Type one of name, table, def, max_length, not_null, primary_key, multiple_key, unique_key, numeric, blob, type, unsigned, zerofill
param: int    $col_offset Optional. 0: col name. 1: which table the col's in. 2: col's max length. 3: if the col is numeric. 4: col's type
since: 0.71

timer_start()   X-Ref
Starts the timer, for debugging purposes.

return: true
since: 1.5.0

timer_stop()   X-Ref
Stops the debugging timer.

return: float Total time spent on the query, in seconds
since: 1.5.0

bail( $message, $error_code = '500' )   X-Ref
Wraps errors in a nice header and footer and dies.

Will not die if wpdb::$show_errors is false.

return: false|void
param: string $message    The Error message
param: string $error_code Optional. A Computer readable string to identify the error.
since: 1.5.0

close()   X-Ref
Closes the current database connection.

return: bool True if the connection was successfully closed, false if it wasn't,
since: 4.5.0

check_database_version()   X-Ref
Whether MySQL database is at least the required minimum version.

return: WP_Error|void
since: 2.5.0

supports_collation()   X-Ref
Whether the database supports collation.

Called when WordPress is generating the table scheme.

Use `wpdb::has_cap( 'collation' )`.

return: bool True if collation is supported, false if version does not
since: 2.5.0

get_charset_collate()   X-Ref
The database character collate.

return: string The database character collate.
since: 3.5.0

has_cap( $db_cap )   X-Ref
Determine if a database supports a particular feature.

return: int|false Whether the database feature is supported, false otherwise.
param: string $db_cap The feature to check for. Accepts 'collation',
since: 2.7.0
since: 4.1.0 Added support for the 'utf8mb4' feature.
since: 4.6.0 Added support for the 'utf8mb4_520' feature.

get_caller()   X-Ref
Retrieve the name of the function that called wpdb.

Searches up the list of functions until it reaches
the one that would most logically had called this method.

return: string Comma separated list of the calling functions.
since: 2.5.0

db_version()   X-Ref
Retrieves the MySQL server version.

return: null|string Null on failure, version number on success.
since: 2.7.0



Generated: Sat Sep 21 01:00:03 2019 Cross-referenced by PHPXref 0.7.1