wpdb::prepare( string $query, array|mixed $args )

Prepares a SQL query for safe execution. Uses sprintf()-like syntax.

Description

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

Parameters

$query

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

$args

(array|mixed) (Required) The array of variables to substitute into the query's placeholders if being called with an array of arguments, or the first variable to substitute into the query's placeholders if being called with individual arguments.

$args,...

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

Return

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

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( __( 'The query argument of %s must have a placeholder.' ), 'wpdb::prepare()' ), 'WP-3.9.0' );
		}

		$args = func_get_args();
		array_shift( $args );

		// If args were passed as an array (as in vsprintf), move them up.
		$passed_as_array = false;
		if ( is_array( $args[0] ) && count( $args ) == 1 ) {
			$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( __( 'Unsupported value type (%s).' ), gettype( $arg ) ), 'WP-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 backwards 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 );

		if ( count( $args ) !== $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.' ), 'WP-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',
					/* translators: 1: number of placeholders, 2: number of arguments passed */
					sprintf( __( 'The query does not contain the correct number of placeholders (%1$d) for the number of arguments passed (%2$d).' ),
						$placeholders,
						count( $args ) ),
					'WP-4.8.3'
				);
			}
		}

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

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

Expand Source Code View on GitHub

Related

Uses

Uses
Uses Description
wp-includes/l10n.php: __()

Retrieve the translation of $text.
wp-includes/wp-db.php: wpdb::add_placeholder_escape()

Adds a placeholder escape string, to escape anything that resembles a printf() placeholder.
wp-includes/load.php: wp_load_translations_early()

Attempt an early load of translations.
wp-includes/functions.php: _doing_it_wrong()

Mark something as being incorrectly called.

Used By

Used By
Used By Description
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/general-template.php: wp_get_archives()

Display archive links based on type and format.
wp-includes/class-wp-user-query.php: WP_User_Query::prepare_query()

Prepare 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/class-wp-user.php: WP_User::get_data_by()

Return only the main user fields
wp-includes/media.php: attachment_url_to_postid()

Tries to convert an attachment URL into a post ID.
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-term.php: WP_Term::get_instance()

Retrieve WP_Term instance.
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/class-wp-query.php: WP_Query::get_posts()

Retrieve the posts based on query variables.
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/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-network.php: WP_Network::get_instance()

Retrieve a network from the database by its ID.
wp-includes/class-wp-post.php: WP_Post::get_instance()

Retrieve WP_Post instance.
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-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-comment.php: WP_Comment::get_instance()

Retrieves a WP_Comment instance.
wp-includes/comment.php: trackback()

Send a Trackback.
wp-includes/comment.php: wp_update_comment_count_now()

Updates the comment count for the post.
wp-includes/comment.php: do_trackbacks()

Perform trackbacks.
wp-includes/comment.php: wp_delete_comment()

Trashes or deletes a comment.
wp-includes/comment.php: wp_allow_comment()

Validates whether this comment is allowed to be made.
wp-includes/comment.php: wp_check_comment_flood()

Checks whether comment flooding is occurring.
wp-includes/comment.php: check_comment()

Check whether a comment passes internal checks to be allowed to add.
wp-includes/comment.php: get_lastcommentmodified()

The date the last comment was modified.
wp-includes/comment.php: get_comment_count()

The amount of comments in a post or total comments.
wp-includes/bookmark.php: get_bookmark()

Retrieve Bookmark data
wp-includes/bookmark.php: get_bookmarks()

Retrieves the list of bookmarks
wp-includes/date.php: WP_Date_Query::get_sql_for_clause()

Turns a first-order date query into SQL for a WHERE clause.
wp-includes/date.php: WP_Date_Query::build_time_query()

Builds a query string for comparing time values (hour, minute, second).
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/ms-load.php: ms_not_installed()

Displays a failure message.
wp-includes/link-template.php: get_adjacent_post()

Retrieves the adjacent post.
wp-includes/ms-deprecated.php: get_admin_users_for_domain()

Get the admin for a domain/path combination.
wp-includes/ms-deprecated.php: get_blog_list()

Deprecated functionality to retrieve a list of all sites.
wp-includes/class-wp-site.php: WP_Site::get_instance()

Retrieves a site from the database by its ID.
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/meta.php: get_metadata_by_mid()

Get meta data by meta ID
wp-includes/meta.php: add_metadata()

Add metadata for the specified object.
wp-includes/meta.php: update_metadata()

Update metadata for the specified object. If no value already exists for the specified object ID and metadata key, the metadata will be added.
wp-includes/meta.php: delete_metadata()

Delete metadata for the specified object.
wp-includes/http.php: ms_allowed_http_request_hosts()

Whitelists any domain in a multisite installation for safe HTTP requests.
wp-includes/user.php: wp_get_users_with_no_role()

Get the user IDs of all users with no role on this site.
wp-includes/user.php: send_confirmation_on_profile_email()

Send a confirmation request email when a change of user email address is attempted.
wp-includes/user.php: check_password_reset_key()

Retrieves a user row based on password reset key and login
wp-includes/user.php: wp_insert_user()

Insert a user into the database.
wp-includes/user.php: count_users()

Count number of users who have each of the user roles.
wp-includes/wp-db.php: wpdb::set_charset()

Sets the connection’s character set.
wp-includes/wp-db.php: wpdb::_insert_replace_helper()

Helper function for insert and replace.
wp-includes/wp-db.php: wpdb::update()

Update a row in the table
wp-includes/wp-db.php: wpdb::delete()

Delete a row in the table
wp-includes/wp-db.php: wpdb::strip_invalid_text()

Strips any invalid characters based on value/charset pairs.
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/option.php: get_network_option()

Retrieve a network’s option value based on the option name.
wp-includes/option.php: delete_network_option()

Removes a network option by name.
wp-includes/option.php: delete_expired_transients()

Deletes all expired transients.
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()

Add a new option.
wp-includes/option.php: delete_option()

Removes option by name. Prevents removal of protected ClassicPress options.
wp-includes/option.php: get_option()

Retrieves an option value based on an option name.
wp-includes/canonical.php: redirect_canonical()

Redirects incoming links to the proper URL based on the site url.
wp-includes/canonical.php: redirect_guess_404_permalink()

Attempts to guess the correct URL based on query vars
wp-includes/class-wp-rewrite.php: WP_Rewrite::page_uri_index()

Retrieves all page and attachments for pages URIs.
wp-includes/class-wp-term-query.php: WP_Term_Query::get_terms()

Get terms, based on query_vars.
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/post.php: get_posts_by_author_sql()

Retrieve the post SQL based on capability, author, and type.
wp-includes/post.php: get_pages()

Retrieve a list of pages (or hierarchical post type items).
wp-includes/post.php: wp_delete_attachment()

Trash or delete an attachment.
wp-includes/post.php: wp_delete_attachment_files()

Deletes all files that belong to the given attachment.
wp-includes/post.php: get_page_by_title()

Retrieve a page given its title.
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_trash_post_comments()

Moves comments for a post to the trash.
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_count_posts()

Count number of posts of a post type and if user has permissions to view.
wp-includes/post.php: wp_delete_post()

Trash or delete a post or page.
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-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/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: get_most_recent_post_of_user()

Get a user’s most recent post.
wp-includes/ms-functions.php: wpmu_validate_user_signup()

Sanitize and validate data required for a user sign-up.
wp-includes/ms-functions.php: wpmu_validate_blog_signup()

Processes new site registrations.
wp-includes/ms-functions.php: wpmu_activate_signup()

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

Remove a user from a blog.
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-comment-query.php: WP_Comment_Query::get_search_sql()

Used internally to generate an SQL string for searching across multiple columns
wp-includes/taxonomy.php: wp_term_is_shared()

Determine whether a term is shared between multiple taxonomies.
wp-includes/taxonomy.php: _update_post_term_count()

Will update term count based on object types of the current taxonomy.
wp-includes/taxonomy.php: _update_generic_term_count()

Will update term count based on number of objects.
wp-includes/taxonomy.php: _wp_batch_split_terms()

Splits a batch of shared taxonomy terms.
wp-includes/taxonomy.php: wp_unique_term_slug()

Will make slug unique, if it isn’t already.
wp-includes/taxonomy.php: wp_update_term()

Update term based on arguments provided.
wp-includes/taxonomy.php: wp_delete_term()

Removes a term from the database.
wp-includes/taxonomy.php: wp_insert_term()

Add a new term to the database.
wp-includes/taxonomy.php: wp_set_object_terms()

Create Term and Taxonomy Relationships.
wp-includes/taxonomy.php: wp_remove_object_terms()

Remove term(s) associated with a given object.
wp-includes/taxonomy.php: has_term_meta()

Get all meta data, including meta IDs, for the given term ID.
wp-includes/taxonomy.php: term_exists()

Check if Term exists.
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/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-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/media.php: wp_media_attach_action()

Encapsulate logic for Attach/Detach actions
wp-admin/includes/class-wp-list-table.php: WP_List_Table::months_dropdown()

Display a monthly dropdown for filtering items
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/template.php: parent_dropdown()

Print out option HTML elements for the page parents drop-down.
wp-admin/includes/template.php: meta_form()

Prints the form in the Custom Fields meta box.
wp-admin/includes/network.php: network_domain_check()

Check for an existing network.
wp-admin/includes/schema.php: populate_network()

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

Create ClassicPress options and set the default values.
wp-admin/includes/nav-menu.php: _wp_delete_orphaned_draft_menu_items()

Deletes orphaned draft menu items
wp-admin/includes/class-wp-posts-list-table.php: WP_Posts_List_Table::__construct()

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

Returns array with imported permalinks from ClassicPress database
wp-admin/includes/class-wp-importer.php: WP_Importer::count_imported_posts()

Return count of imported permalinks from ClassicPress database
wp-admin/includes/class-wp-importer.php: WP_Importer::get_imported_comments()

Set array with imported comments from ClassicPress database
wp-admin/includes/comment.php: comment_exists()

Determine if a comment exists based on author and date.
wp-admin/includes/upgrade.php: wp_install_defaults()

Creates the initial content for a newly-installed site.
wp-admin/includes/upgrade.php: wp_upgrade()

Runs ClassicPress Upgrade functions.
wp-admin/includes/class-wp-upgrader.php: WP_Upgrader::create_lock()

Creates a lock using ClassicPress options.
wp-admin/includes/user.php: WP_Privacy_Requests_Table::get_request_counts()

Count number of requests for each status.
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/export.php: export_wp()

Generates the WXR export file for download.
wp-admin/includes/export.php: wxr_term_meta()

Output term meta XML tags for a given term object.
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/post.php: has_meta()

Get meta data for the given post ID.
wp-admin/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()

Determine if a post exists based on title, content, and date
wp-admin/includes/ms.php: wpmu_delete_user()

Delete a user from the network and remove from all sites.
wp-admin/export.php: export_date_options()

Create the date options fields for exporting a given post type.
wp-admin/install.php: display_setup_form()

Display installer setup form.
wp-admin/includes/upgrade.php: maybe_create_table()

Creates a table in the database if it doesn’t already exist.
Show 139 more used by Hide more used by

Changelog

Changelog
Version Description
WP-2.3.0 Introduced.