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

Prepares a SQL query for safe execution.

Description

Uses sprintf()-like syntax. The following placeholders can be used in the query string:

  • %d (integer)
  • %f (float)
  • %s (string)
  • %i (identifier, e.g. table/field names)

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

Parameters

$query

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

$args

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

Return

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

Source

File: wp-includes/class-wpdb.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/compat.php: str_contains()

Polyfill for str_contains() function added in PHP 8.0.
wp-includes/compat.php: str_ends_with()

Polyfill for str_ends_with() function added in PHP 8.0.
wp-includes/class-wpdb.php: wpdb::_escape_identifier_value()

Escapes an identifier value without adding the surrounding quotes.
wp-includes/l10n.php: __()

Retrieves the translation of $text.
wp-includes/class-wpdb.php: wpdb::_real_escape()

Real escape using mysqli_real_escape_string().
wp-includes/class-wpdb.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()

Marks something as being incorrectly called.
Show 3 more uses Hide more uses

Used By

Used By
Used By Description
wp-admin/includes/class-wp-site-health.php: WP_Site_Health::should_suggest_persistent_object_cache()

Determines whether to suggest using a persistent object cache.
wp-admin/includes/class-wp-debug-data.php: WP_Debug_Data::get_mysql_var()

Returns the value of a MySQL system variable.
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/comment.php: _wp_batch_update_comment_type()

Updates the comment type for a batch of comments.
wp-includes/object-relationships.php: cp_object_relationship_exists()

Check if a relationship exists between two recognized objects.
wp-includes/object-relationships.php: cp_get_object_relationship_ids()

Get IDs of all the recognized objects related to the known object.
wp-includes/object-relationships.php: cp_delete_object_relationship()

Delete a relationship between two recognized objects.
wp-includes/ms-site.php: wp_delete_site()

Deletes a site from the database.
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()

Displays archive links based on type and format.
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/class-wp-user.php: WP_User::get_data_by()

Returns only the main user fields.
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()

Retrieves an array of 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()

Generates SQL JOIN and WHERE clauses for a “first-order” query clause.
wp-includes/class-wp-network.php: WP_Network::get_instance()

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

Retrieves a WP_Comment 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/comment.php: trackback()

Sends a Trackback.
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: 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()

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

Retrieves the date the last comment was modified.
wp-includes/bookmark.php: get_bookmark()

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

Retrieves the list of bookmarks.
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/class-wp-date-query.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()

Generates 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()

Gets a blog details field.
wp-includes/ms-blogs.php: get_last_updated()

Gets a list of most recently updated blogs.
wp-includes/ms-blogs.php: get_blog_details()

Retrieves the details for a blog from the blogs table and blog options.
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.
wp-includes/meta.php: delete_metadata()

Deletes metadata for the specified object.
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/user.php: wp_get_users_with_no_role()

Gets the user IDs of all users with no role on this site.
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/class-wpdb.php: wpdb::set_charset()

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

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

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

Deletes a row in the table.
wp-includes/class-wpdb.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()

Retrieves 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()

Retrieves an array of URLs that pingbacked the given URL.
wp-includes/option.php: get_network_option()

Retrieves 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()

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/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 for a 404 request based on query vars.
wp-includes/class-wp-rewrite.php: WP_Rewrite::page_uri_index()

Retrieves all pages and attachments for pages URIs.
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/post.php: get_posts_by_author_sql()

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

Retrieves an array of pages (or hierarchical post type items).
wp-includes/post.php: wp_delete_attachment()

Trashes or deletes an attachment.
wp-includes/post.php: wp_delete_attachment_files()

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

Retrieves 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()

Restores comments for a post from the Trash.
wp-includes/post.php: wp_insert_post()

Inserts or update a post.
wp-includes/post.php: wp_count_posts()

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

Trashes or deletes 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: get_most_recent_post_of_user()

Gets a user’s most recent post.
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-functions.php: remove_user_from_blog()

Removes 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()

Determines whether a term is shared between multiple taxonomies.
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_batch_split_terms()

Splits a batch of shared taxonomy terms.
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_delete_term()

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

Creates term and taxonomy relationships.
wp-includes/taxonomy.php: wp_insert_term()

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

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

Gets all meta data, including meta IDs, for the given term ID.
wp-includes/revision.php: _wp_upgrade_revisions_of_post()

Upgrades the revisions author, adds the current post as a revision and sets the revisions version to 1.
wp-includes/revision.php: wp_get_post_autosave()

Retrieves the autosaved data of the specified post.
wp-includes/functions.php: wp_scheduled_delete()

Permanently deletes 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()

Checks 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()

Encapsulates the logic for Attach/Detach actions.
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/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()

Prints 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/schema.php: populate_network()

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

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

Create WordPress 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()

Determines 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/class-wp-upgrader.php: WP_Upgrader::create_lock()

Creates a lock using WordPress options.
wp-admin/includes/class-wp-privacy-requests-table.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/class-wp-ms-sites-list-table.php: WP_MS_Sites_List_Table::prepare_items()

Prepares the list of sites for display.
wp-includes/post.php: get_available_post_mime_types()

Gets all available post MIME types for a given post type.
wp-admin/includes/post.php: has_meta()

Returns meta data for the given post ID.
wp-admin/includes/post.php: post_exists()

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

Deletes 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-helper.php: maybe_create_table()

Creates a table in the database if it doesn’t already exist.
wp-admin/install.php: display_setup_form()

Displays installer setup form.
Show 139 more used by Hide more used by

Changelog

Changelog
Version Description
6.2.0 Added %i for identifiers, e.g. table or field names.<br> Check support via wpdb::has_cap( 'identifier_placeholders' ).<br> This preserves compatibility with sprintf(), as the C version uses %d and $i as a signed integer, whereas PHP only supports %d.
5.3.0 Formalized the existing and already documented ...$args parameter by updating the function signature. The second parameter was changed from $args to ...$args.
2.3.0 Introduced.