wpdb::prepare() WordPress Method

wpdb::prepare() is a method of the wpdb class. It is used to prepare a SQL query for execution. It takes a SQL query as a string and an array of arguments. The query is prepared by replacing placeholders in the query with the corresponding values in the array. The placeholders are either ? or %s.

wpdb::prepare( string $query, mixed $args ) #

Prepares a SQL query for safe execution.

Contents

Description

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.

Note: There is one exception to the above: 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.

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' );

Top ↑

Parameters

$query

(string)(Required)Query statement with sprintf()-like placeholders.

$args

(mixed)(Required)Further variables to substitute into the query's placeholders if being called with individual arguments.

Top ↑

Return

(string|void) Sanitized query string, if there is a query to prepare.

Top ↑

Source

File: wp-includes/wp-db.php

	public function prepare( $query, ...$args ) {
		if ( is_null( $query ) ) {
			return;
		}

		// This is not meant to be foolproof -- but it will catch obviously incorrect usage.
		if ( strpos( $query, '%' ) === false ) {
			wp_load_translations_early();
			_doing_it_wrong(
				'wpdb::prepare',
				sprintf(
					/* translators: %s: wpdb::prepare() */
					__( 'The query argument of %s must have a placeholder.' ),
					'wpdb::prepare()'
				),
				'3.9.0'
			);
		}

		// If args were passed as an array (as in vsprintf), move them up.
		$passed_as_array = false;
		if ( isset( $args[0] ) && is_array( $args[0] ) && 1 === count( $args ) ) {
			$passed_as_array = true;
			$args            = $args[0];
		}

		foreach ( $args as $arg ) {
			if ( ! is_scalar( $arg ) && ! is_null( $arg ) ) {
				wp_load_translations_early();
				_doing_it_wrong(
					'wpdb::prepare',
					sprintf(
						/* translators: %s: Value type. */
						__( 'Unsupported value type (%s).' ),
						gettype( $arg )
					),
					'4.8.2'
				);
			}
		}

		/*
		 * Specify the formatting allowed in a placeholder. The following are allowed:
		 *
		 * - Sign specifier. eg, $+d
		 * - Numbered placeholders. eg, %1$s
		 * - Padding specifier, including custom padding characters. eg, %05s, %'#5s
		 * - Alignment specifier. eg, %05-s
		 * - Precision specifier. eg, %.2f
		 */
		$allowed_format = '(?:[1-9][0-9]*[$])?[-+0-9]*(?: |0|\'.)?[-+0-9]*(?:\.[0-9]+)?';

		/*
		 * If a %s placeholder already has quotes around it, removing the existing quotes and re-inserting them
		 * ensures the quotes are consistent.
		 *
		 * For backward compatibility, this is only applied to %s, and not to placeholders like %1$s, which are frequently
		 * used in the middle of longer strings, or as table name placeholders.
		 */
		$query = str_replace( "'%s'", '%s', $query ); // Strip any existing single quotes.
		$query = str_replace( '"%s"', '%s', $query ); // Strip any existing double quotes.
		$query = preg_replace( '/(?<!%)%s/', "'%s'", $query ); // Quote the strings, avoiding escaped strings like %%s.

		$query = preg_replace( "/(?<!%)(%($allowed_format)?f)/", '%\\2F', $query ); // Force floats to be locale-unaware.

		$query = preg_replace( "/%(?:%|$|(?!($allowed_format)?[sdF]))/", '%%\\1', $query ); // Escape any unescaped percents.

		// Count the number of valid placeholders in the query.
		$placeholders = preg_match_all( "/(^|[^%]|(%%)+)%($allowed_format)?[sdF]/", $query, $matches );

		$args_count = count( $args );

		if ( $args_count !== $placeholders ) {
			if ( 1 === $placeholders && $passed_as_array ) {
				// If the passed query only expected one argument, but the wrong number of arguments were sent as an array, bail.
				wp_load_translations_early();
				_doing_it_wrong(
					'wpdb::prepare',
					__( 'The query only expected one placeholder, but an array of multiple placeholders was sent.' ),
					'4.9.0'
				);

				return;
			} else {
				/*
				 * If we don't have the right number of placeholders, but they were passed as individual arguments,
				 * or we were expecting multiple arguments in an array, throw a warning.
				 */
				wp_load_translations_early();
				_doing_it_wrong(
					'wpdb::prepare',
					sprintf(
						/* translators: 1: Number of placeholders, 2: Number of arguments passed. */
						__( 'The query does not contain the correct number of placeholders (%1$d) for the number of arguments passed (%2$d).' ),
						$placeholders,
						$args_count
					),
					'4.8.3'
				);

				/*
				 * If we don't have enough arguments to match the placeholders,
				 * return an empty string to avoid a fatal error on PHP 8.
				 */
				if ( $args_count < $placeholders ) {
					$max_numbered_placeholder = ! empty( $matches[3] ) ? max( array_map( 'intval', $matches[3] ) ) : 0;

					if ( ! $max_numbered_placeholder || $args_count < $max_numbered_placeholder ) {
						return '';
					}
				}
			}
		}

		array_walk( $args, array( $this, 'escape_by_ref' ) );
		$query = vsprintf( $query, $args );

		return $this->add_placeholder_escape( $query );
	}

Expand full source codeCollapse full source codeView on TracView on GitHub

Top ↑

Top ↑

Used By

Used By
Used ByDescription
wp-admin/includes/class-wp-debug-data.php:WP_Debug_Data::get_mysql_var()

Returns the value of a MySQL system variable.

wp-includes/comment.php:_wp_batch_update_comment_type()

Updates the comment type for a batch of comments.

wp-includes/ms-site.php:wp_delete_site()

Deletes a site from the database.

wp-admin/includes/schema.php:populate_network_meta()

Creates WordPress network meta and sets the default values.

wp-admin/includes/schema.php:populate_site_meta()

Creates WordPress site meta and sets the default values.

wp-includes/query.php:_find_post_by_old_slug()

Find the post ID for redirecting an old slug.

wp-includes/query.php:_find_post_by_old_date()

Find the post ID for redirecting an old date.

wp-includes/post.php:wp_delete_attachment_files()

Deletes all files that belong to the given attachment.

wp-admin/includes/class-wp-privacy-requests-table.php:WP_Privacy_Requests_Table::get_request_counts()

Count number of requests for each status.

wp-includes/taxonomy.php:has_term_meta()

Gets all meta data, including meta IDs, for the given term ID.

wp-includes/option.php:delete_expired_transients()

Deletes all expired transients.

wp-includes/comment.php:wp_check_comment_flood()

Checks whether comment flooding is occurring.

wp-includes/class-wp-term-query.php:WP_Term_Query::get_search_sql()

Used internally to generate a SQL string related to the ‘search’ parameter.

wp-includes/class-wp-term-query.php:WP_Term_Query::get_terms()

Retrieves the query results.

wp-includes/class-wp-network-query.php:WP_Network_Query::get_search_sql()

Used internally to generate an SQL string for searching across multiple columns.

wp-includes/class-wp-network-query.php:WP_Network_Query::get_network_ids()

Used internally to get a list of network IDs matching the query vars.

wp-includes/class-wp-site-query.php:WP_Site_Query::get_search_sql()

Used internally to generate an SQL string for searching across multiple columns.

wp-includes/class-wp-site-query.php:WP_Site_Query::get_site_ids()

Used internally to get a list of site IDs matching the query vars.

wp-admin/includes/export.php:wxr_term_meta()

Output term meta XML tags for a given term object.

wp-includes/class-wp-site.php:WP_Site::get_instance()

Retrieves a site from the database by its ID.

wp-admin/includes/class-wp-upgrader.php:WP_Upgrader::create_lock()

Creates a lock using WordPress options.

wp-includes/class-wp-network.php:WP_Network::get_instance()

Retrieve a network from the database by its ID.

wp-includes/taxonomy.php:wp_term_is_shared()

Determines whether a term is shared between multiple taxonomies.

wp-includes/class-wp-comment.php:WP_Comment::get_instance()

Retrieves a WP_Comment instance.

wp-includes/user.php:wp_get_users_with_no_role()

Gets the user IDs of all users with no role on this site.

wp-includes/class-wp-comment-query.php:WP_Comment_Query::get_comment_ids()

Used internally to get a list of comment IDs matching the query vars.

wp-includes/class-wp-term.php:WP_Term::get_instance()

Retrieve WP_Term instance.

wp-includes/option.php:delete_network_option()

Removes a network option by name.

wp-includes/option.php:get_network_option()

Retrieves a network’s option value based on the option name.

wp-includes/taxonomy.php:_wp_batch_split_terms()

Splits a batch of shared taxonomy terms.

wp-includes/wp-db.php:wpdb::strip_invalid_text()

Strips any invalid characters based on value/charset pairs.

wp-admin/includes/media.php:wp_media_attach_action()

Encapsulates the logic for Attach/Detach actions.

wp-includes/class-wp-meta-query.php:WP_Meta_Query::get_sql_for_clause()

Generate SQL JOIN and WHERE clauses for a first-order query clause.

wp-includes/class-wp-tax-query.php:WP_Tax_Query::get_sql_for_clause()

Generate SQL JOIN and WHERE clauses for a “first-order” query clause.

wp-includes/class-wp-date-query.php:WP_Date_Query::get_sql_for_clause()

Turns a first-order date query into SQL for a WHERE clause.

wp-includes/media.php:attachment_url_to_postid()

Tries to convert an attachment URL into a post ID.

wp-admin/install.php:display_setup_form()

Display installer setup form.

wp-admin/includes/network.php:network_domain_check()

Check for an existing network.

wp-admin/export.php:export_date_options()

Create the date options fields for exporting a given post type.

wp-admin/includes/export.php:export_wp()

Generates the WXR export file for download.

wp-admin/includes/deprecated.php:WP_User_Search::prepare_query()

Prepares the user search query (legacy).

wp-admin/includes/deprecated.php:get_author_user_ids()

Get all user IDs.

wp-admin/includes/deprecated.php:get_editable_user_ids()

Gets the IDs of any users who can edit posts.

wp-admin/includes/deprecated.php:get_nonauthor_user_ids()

Gets all users who are not authors.

wp-admin/includes/deprecated.php:get_others_unpublished_posts()

Retrieves editable posts from other users.

wp-admin/includes/class-wp-list-table.php:WP_List_Table::months_dropdown()

Displays a dropdown for filtering items in the list table by month.

wp-admin/includes/ms.php:wpmu_delete_user()

Delete a user from the network and remove from all sites.

wp-admin/includes/schema.php:populate_network()

Populate network settings.

wp-admin/includes/schema.php:populate_options()

Create WordPress options and set the default values.

wp-admin/includes/upgrade.php:maybe_create_table()

Creates a table in the database, if it doesn’t already exist.

wp-admin/includes/upgrade.php:wp_install_defaults()

Creates the initial content for a newly-installed site.

wp-admin/includes/user.php:get_users_drafts()

Retrieve the user’s drafts.

wp-admin/includes/user.php:wp_delete_user()

Remove user and optionally reassign posts and links to another user.

wp-admin/includes/template.php:meta_form()

Prints the form in the Custom Fields meta box.

wp-admin/includes/template.php:parent_dropdown()

Prints out option HTML elements for the page parents drop-down.

wp-admin/includes/class-wp-ms-sites-list-table.php:WP_MS_Sites_List_Table::prepare_items()

Prepares the list of sites for display.

wp-admin/includes/media.php:update_gallery_tab()

Adds the gallery tab back to the tabs array if post has image attachments.

wp-admin/includes/post.php:has_meta()

Returns meta data for the given post ID.

wp-includes/post.php:get_available_post_mime_types()

Get all available post MIME types for a given post type.

wp-admin/includes/post.php:post_exists()

Determines if a post exists based on title, content, date and type.

wp-admin/includes/class-wp-importer.php:WP_Importer::get_imported_comments()

Set array with imported comments from WordPress database

wp-admin/includes/class-wp-importer.php:WP_Importer::get_imported_posts()

Returns array with imported permalinks from WordPress database

wp-admin/includes/class-wp-importer.php:WP_Importer::count_imported_posts()

Return count of imported permalinks from WordPress database

wp-admin/includes/nav-menu.php:_wp_delete_orphaned_draft_menu_items()

Deletes orphaned draft menu items

wp-admin/includes/comment.php:comment_exists()

Determine if a comment exists based on author and date.

wp-admin/includes/class-wp-posts-list-table.php:WP_Posts_List_Table::__construct()

Constructor.

wp-includes/class-wp-user.php:WP_User::get_data_by()

Returns only the main user fields.

wp-includes/general-template.php:wp_get_archives()

Display archive links based on type and format.

wp-includes/deprecated.php:delete_usermeta()

Remove user meta data.

wp-includes/deprecated.php:get_usermeta()

Retrieve user metadata.

wp-includes/deprecated.php:update_usermeta()

Update metadata of user.

wp-includes/class-wp-query.php:WP_Query::get_posts()

Retrieves an array of posts based on query variables.

wp-includes/class-wp-query.php:WP_Query::parse_search()

Generates SQL for the WHERE clause based on passed search terms.

wp-includes/class-wp-query.php:WP_Query::parse_search_order()

Generates SQL for the ORDER BY condition based on passed search terms.

wp-includes/functions.php:wp_scheduled_delete()

Permanently delete comments or posts of any type that have held a status of ‘trash’ for the number of days defined in EMPTY_TRASH_DAYS.

wp-includes/functions.php:do_enclose()

Check content for video and audio links to add as enclosures.

wp-includes/taxonomy.php:_update_post_term_count()

Updates term count based on object types of the current taxonomy.

wp-includes/taxonomy.php:_update_generic_term_count()

Updates term count based on number of objects.

wp-includes/taxonomy.php:wp_unique_term_slug()

Makes term slug unique, if it isn’t already.

wp-includes/taxonomy.php:wp_update_term()

Updates term based on arguments provided.

wp-includes/taxonomy.php:wp_set_object_terms()

Creates term and taxonomy relationships.

wp-includes/taxonomy.php:wp_remove_object_terms()

Removes term(s) associated with a given object.

wp-includes/taxonomy.php:wp_insert_term()

Adds a new term to the database.

wp-includes/taxonomy.php:wp_delete_term()

Removes a term from the database.

wp-includes/link-template.php:get_adjacent_post()

Retrieves the adjacent post.

wp-includes/http.php:ms_allowed_http_request_hosts()

Adds any domain in a multisite installation for safe HTTP requests to the allowed list.

wp-includes/class-wp-date-query.php:WP_Date_Query::build_time_query()

Builds a query string for comparing time values (hour, minute, second).

wp-includes/option.php:wp_load_core_site_options()

Loads and caches certain often requested site options if is_multisite() and a persistent cache is not being used.

wp-includes/option.php:add_option()

Adds a new option.

wp-includes/option.php:delete_option()

Removes option by name. Prevents removal of protected WordPress options.

wp-includes/option.php:get_option()

Retrieves an option value based on an option name.

wp-includes/class-wp-user-query.php:WP_User_Query::prepare_query()

Prepares the query variables.

wp-includes/class-wp-user-query.php:WP_User_Query::get_search_sql()

Used internally to generate an SQL string for searching across multiple columns.

wp-includes/user.php:wp_insert_user()

Inserts a user into the database.

wp-includes/user.php:count_users()

Counts number of users who have each of the user roles.

wp-includes/media.php:wp_enqueue_media()

Enqueues all scripts, styles, settings, and templates necessary to use all media JS APIs.

wp-includes/class-wp-post.php:WP_Post::get_instance()

Retrieve WP_Post instance.

wp-includes/post.php:get_posts_by_author_sql()

Retrieve the post SQL based on capability, author, and type.

wp-includes/post.php:wp_delete_attachment()

Trash or delete an attachment.

wp-includes/post.php:get_page_by_title()

Retrieve a page given its title.

wp-includes/post.php:get_pages()

Retrieve an array of pages (or hierarchical post type items).

wp-includes/post.php:wp_unique_post_slug()

Computes a unique slug for the post, when given the desired slug and some post details.

wp-includes/post.php:wp_untrash_post_comments()

Restore comments for a post from the Trash.

wp-includes/post.php:wp_insert_post()

Insert or update a post.

wp-includes/post.php:wp_delete_post()

Trash or delete a post or page.

wp-includes/post.php:wp_trash_post_comments()

Moves comments for a post to the Trash.

wp-includes/post.php:wp_count_posts()

Count number of posts of a post type and if user has permissions to view.

wp-includes/class-wp-rewrite.php:WP_Rewrite::page_uri_index()

Retrieves all page and attachments for pages URIs.

wp-includes/canonical.php:redirect_guess_404_permalink()

Attempts to guess the correct URL for a 404 request based on query vars.

wp-includes/canonical.php:redirect_canonical()

Redirects incoming links to the proper URL based on the site url.

wp-includes/revision.php:_wp_upgrade_revisions_of_post()

Upgrade the revisions author, add the current post as a revision and set the revisions version to 1

wp-includes/revision.php:wp_get_post_autosave()

Retrieve the autosaved data of the specified post.

wp-includes/ms-functions.php:get_most_recent_post_of_user()

Gets a user’s most recent post.

wp-includes/ms-functions.php:global_terms()

Maintains a canonical list of terms by syncing terms created for each blog with the global terms table.

wp-includes/ms-functions.php:wpmu_activate_signup()

Activates a signup.

wp-includes/ms-functions.php:wpmu_validate_user_signup()

Sanitizes and validates data required for a user sign-up.

wp-includes/ms-functions.php:wpmu_validate_blog_signup()

Processes new site registrations.

wp-includes/ms-deprecated.php:get_admin_users_for_domain()

Get the admin for a domain/path combination.

wp-includes/ms-functions.php:remove_user_from_blog()

Removes a user from a blog.

wp-includes/bookmark.php:get_bookmark()

Retrieve Bookmark data

wp-includes/bookmark.php:get_bookmarks()

Retrieves the list of bookmarks

wp-includes/ms-load.php:ms_not_installed()

Displays a failure message.

wp-includes/ms-deprecated.php:get_blog_list()

Deprecated functionality to retrieve a list of all sites.

wp-includes/ms-blogs.php:get_blog_status()

Get a blog details field.

wp-includes/ms-blogs.php:get_last_updated()

Get a list of most recently updated blogs.

wp-includes/ms-blogs.php:get_blog_details()

Retrieve the details for a blog from the blogs table and blog options.

wp-includes/class-wp-xmlrpc-server.php:wp_xmlrpc_server::mt_getTrackbackPings()

Retrieve trackbacks sent to a given post.

wp-includes/class-wp-xmlrpc-server.php:wp_xmlrpc_server::pingback_ping()

Retrieves a pingback and registers it.

wp-includes/class-wp-xmlrpc-server.php:wp_xmlrpc_server::pingback_extensions_getPingbacks()

Retrieve array of URLs that pingbacked the given URL.

wp-includes/wp-db.php:wpdb::_insert_replace_helper()

Helper function for insert and replace.

wp-includes/wp-db.php:wpdb::update()

Updates a row in the table.

wp-includes/wp-db.php:wpdb::delete()

Deletes a row in the table.

wp-includes/wp-db.php:wpdb::set_charset()

Sets the connection’s character set.

wp-includes/comment.php:trackback()

Sends a Trackback.

wp-includes/class-wp-comment-query.php:WP_Comment_Query::get_search_sql()

Used internally to generate an SQL string for searching across multiple columns.

wp-includes/comment.php:wp_update_comment_count_now()

Updates the comment count for the post.

wp-includes/comment.php:do_trackbacks()

Performs trackbacks.

wp-includes/comment.php:wp_delete_comment()

Trashes or deletes a comment.

wp-includes/comment.php:get_lastcommentmodified()

Retrieves the date the last comment was modified.

wp-includes/comment.php:wp_allow_comment()

Validates whether this comment is allowed to be made.

wp-includes/comment.php:check_comment()

Checks whether a comment passes internal checks to be allowed to add.

wp-includes/meta.php:delete_metadata()

Deletes metadata for the specified object.

wp-includes/meta.php:get_metadata_by_mid()

Retrieves metadata by meta ID.

wp-includes/meta.php:add_metadata()

Adds metadata for the specified object.

wp-includes/meta.php:update_metadata()

Updates metadata for the specified object. If no value already exists for the specified object ID and metadata key, the metadata will be added.

Show 140 more used byHide more used by

Top ↑

Changelog

Changelog
VersionDescription
5.3.0Formalized the existing and already documented ...$args parameter by updating the function signature. The second parameter was changed from $args to ...$args.
2.3.0Introduced.
Download the latest version of WordPress from https://wordpress.org/

The content displayed on this page has been created in part by processing WordPress source code files which are made available under the GPLv2 (or a later version) license by the Free Software Foundation. In addition to this, the content includes user-written examples and information. All material is subject to review and curation by the WPPaste.com community.

Show More