[pdf-embedder url=”https://clickety-clack.click/img/clickety-clack-site/prevsiteimgs/2020/02/WordPressActionsFiltersandHooks.pdf”]
https://www.designbombs.com/wordpress-filters-cheat-sheet/
WordPress Filters Cheat Sheet
This cheat sheet explores a fundamental concept in WordPress development: filters.
In WordPress, filters enable developers to intercept and modify data as a WordPress page is loading, before sending it to the browser or saving it to the database.
Understanding how filters work isn’t all that easy, partly because the concept is difficult to visualize, and also because filters are often confused with WordPress actions. Yet, it’s an important concept to master because filters are one of the most common ways developers interact with WordPress.
For these reasons, this filter cheat sheet is ideal for those new to working with filters. This cheat sheet provides an in-depth understanding of what filters do and how they work, and provides a quick reference guide for using filters in WordPress development.
WordPress Basics: Hooks & Functions
Let’s start with a basic overview of how WordPress works to help you understand the context of where filters fit in WordPress core code .
A WordPress page is made up of a whole bunch of functions and database queries, with the WordPress core code and the theme working together to output text, images, stylesheets, and other resources. The browser interprets all of this data as it’s processing and then displays it all together as one web page.
Hooks
Throughout the core code are hooks, which are basically placeholders developers can use to “hook” into WordPress and insert their own custom code for processing as a page is loading.
There are two types of hooks: filters and actions:
Filter hooks let you intercept and modify data as it’s being processed. Basically, filters let you manipulate data coming out of the database before going to the browser, or coming from the browser before going into the database. For example, you might want to do something as simple as prepend a word to the title of all your blog posts, or filter out bad language in post comments.
Action hooks, on the other hand, lets you add extra functionality at specific points in the processing and loading of a page. For example, you might want to add a promotional pop-up message to your page or display a copyright message in the footer.
Basically, filter hooks change stuff and action hooks do stuff.
WordPress provides a huge stack of built-in filter hooks for use in WordPress development. However, you can also create your own filter hooks using the [ code style=”css”][/code] function, which I’ll show you how to use shortly.
Functions
In order to use WordPress hooks, you need to write a function.
A function is a piece of custom code that specifies how something will happen. For example, you could code a function to query data, output content, or perform many other tasks.
In WordPress, if you want to “change stuff” in your theme, you need to code a filter function that uses a filter hook.
Using Filters: Example
There are three basic steps involved in adding your own filters to WordPress:
- Coding a PHP function that filters the data.
- Hooking into and existing and appropriate filter hook in WordPress by calling [ code style=”css”][/code].
- Putting your PHP function in a WordPress/plugin file and activating it.
1. Creating a Filter Function
Say you wanted to filter out bad language in blog post comments on your site.
The first step is to code a function that filters your WordPress comments and either removes the bad language or replaces it with other words. For example, you could put together a list of bad words you don’t want displayed on your site and replace them with a censor flag by creating the following PHP function:
function filter_bad_languge( $content ) { $badwords = array('fopdoogle', 'gobermouch', 'yaldson'); $content = str_ireplace( $badwords, '{censored}', $content ); return $content; }
Here’s a breakdown of the code above:
- This is the code that hooks into the filter hook. It’s easy to spot a custom function as it always starts with [ code style=”css”]function()[/code].
- [ code style=”css”]filter_badlanguge[/code] is the name of the filter function.
- [ code style=”css”]$content[/code] is the function’s single argument.
- [ code style=”css”]$badwords = array(‘fopdoogle’,‘gobermouch’,‘yaldson’);[/code] is the first work the function carries out. Specifically, it creates an array called [ code style=”css”]$badwords[/code] and adds the words fopdoogle, gobermouch, and yaldson to that array.
- [ code style=”css”]str_ireplace[/code] loops through your content, searching for any of the words stored in the [ code style=”css”]$badwords[/code] array, replacing them with “{censored},” and then returning them to [ code style=”css”]$content[/code].
- return is very important here: it’s how the function returns the filtered content back to WordPress core.
2. Using a Filter Hook
Once you’ve coded your filter, you need to “hook” it into WordPress core using a hook call. To do this, you use [ code style=”css”]add_filter()[/code]:
add_filter( 'comment_text', 'filter_bad_language' );
Here’s what the above code means:
- [ code style=”css”]comment_text[/code] is the name of the filter hook provided by WordPress, which we want our filter to apply to, i.e. we want our filter to work on blog post comments.
- [ code style=”css”]filter_badlanguage[/code] is the name of the function that we want to use for filtering.
3. Installing and Activating a Filter
The last step in order to get your filter hook working is to add your function and [ code style=”css”]add_filter()[/code] call together in a PHP file. Continuing our bad language example, we would combine the code like so:
function filter_bad_languge( $content ) { $badwords = array('fopdoogle', 'gobermouch', 'yaldson'); $content = str_ireplace( $badwords, '{censored}', $content ); return $content; } add_filter( 'comment_text', 'filter_bad_language' );
Typically, you would either add your function and call to your theme’s functions.php file using a child theme, or create a new plugin. How to do this is beyond the scope of this article, but I highly encourage you read up how to create a child theme and how to create a plugin in the WordPress Developer Handbook.
If you decide to use your function in a plugin, you’ll need to install and activate your newly created plugin in order for your code to work.
Using Custom Filter Hooks
A useful feature in WordPress plugin development is the ability to create custom hooks for use in your plugins so that other developers can extend and modify them.
Custom hooks can be created and called in the same way that WordPress core hooks are created and called.
There are two basic steps involved in creating and using your own custom filter hooks:
- Adding a custom filter hook to an existing function using [ code style=”css”]apply_filters()[/code].
- You (or another developer) coding a custom function that hooks into the custom filter hook.
Creating a Filter Hook
To create a custom hook, you add [ code style=”css”]apply_filters()[/code] in your code where you would like to place a hook.
For example, using the bad language example from above, let’s say we wanted to allow other developers to add new words to be censored. You could do this by updating the function to include a filter:
function filter_bad_languge( $content ) { $badwords = array('fopdoogle', 'gobermouch', 'yaldson'); $badwords = apply_filters('add_bad_language_filter', $badwords ); $content = str_ireplace( $badwords, '{censored}', $content ); return $content; }
[ code style=”css”]add_badlanguage_filter[/code] becomes a filter hook that can be used to modify the list of censored words, with [ code style=”css”]$content[/code] being the default value to be returned.
Using a Custom Filter Hook
So what happens when another developer uses this custom filter? Well, they can remove bad words, change their names, add new words, etc. In this example, I simply want to add a new censored word:
function add_new_bad_words($profanities) { $extra_bad_words = array('sard', 'bescumber'); $profanities = array_merge($extra_bad_words, $profanities); return $profanities; } add_filter('add_bad_language_filter', 'add_new_bad_words');
When the add_new_bad_words function displays the list of bad words, we’ll now see this:
- fopdoogle
- gobermouch
- yaldson
- sard
- bescumber
(In case you haven’t already googled these unusual sounding words, they’re old English curse words.)
Naming Conflicts
Since you can give custom hooks any name you want, it’s important that you prefix your hook names to avoid conflicts with other plugins.
For example, a filter hook simply called post_body would be more likely to be used by another developer. This means if a WordPress user installs and activates your plugin and another developers plugin with hooks using similar names, it would lead to bugs.
It’s recommended you prefix your custom hooks with a shortened version of your name or company, i.e. [ code style=”css”]wbb_add_bad_language_filter[/code].
Unhooking Functions From Filters
In some cases, you may want your plugin to disable a filter built into WordPress or used by a conflicting plugin. You can do this by using [ code style=”css”]remove_filter()[/code].
The [ code style=”css”]remove_filter()[/code] function has three parameters: the name of the filter hook, the name of the function which should be removed, and the priority (which is only mandatory if a priority was set when the function was originally hooked to the filter).
So to remove the add_new_bad_words I created earlier, I would use:
remove_filter( 'add_new_bad_words', 'add_bad_language_filter');
The code output would then revert to the value I specified in my original [ code style=”css”]apply_filters()[/code] function.
Filter Hook Reference Guide
WordPress has hundreds of built-in filter hooks that developers can use to hook into the core code.
The WordPress Codex provides guidance on how to use filter hooks, which it lists using the following categories:
- Post, Page, and Attachment (Upload) Filters
- Comment, Trackback, and Ping Filters
- Category and Term Filters
- Link Filters
- Date and Time Filters
- Author and User Filters
- Blogroll Filters
- Blog Information and Option Filters
- General Text Filters
- Administrative Filters
- Rich Text Editor Filters
- Template Filters
- Registration & Login Filters
- Redirect/Rewrite Filters
- WP_Query Filters
- Media Filters
- Advanced WordPress Filters
- Widgets
- Admin Bar
Many of these filter hooks are split into two sub-categories: database reads and database writes. This depends on whether a function is reading from the database prior to displaying content on a page, or you’re writing code prior to saving data to the database.
Using with hooks in WordPress started with working out what hook you need to “hook” your code to and then writing a function to modify the data you need.
Post, Page, and Attachment (Upload) Filters
Database Reads
- [ code style=”css”]attachment_fields_to_edit[/code] – Applied to form fields to be displayed when editing an attachment.
- [ code style=”css”]attachment_icon[/code] – Applied to the icon for an attachment in the [ code style=”css”]get_attachment_icon[/code] function.
- [ code style=”css”]attachment_innerHTML[/code] – applied to the title to be used for an attachment if there is no icon, in the [ code style=”css”]get_attachment_innerHTML[/code] function.
- [ code style=”css”]author_edit_pre[/code] – Applied to post author prior to display for editing.
- [ code style=”css”]body_class[/code] – Applied to the classes for the HTML [ code style=”css”]<body>[/code] element. Called in the get_body_class function.
- [ code style=”css”]content_edit_pre[/code] – Applied to post content prior to display for editing.
- [ code style=”css”]content_filtered_edit_pre[/code] – Applied to post content filtered prior to display for editing.
- [ code style=”css”]excerpt_edit_pre[/code] – Applied to post excerpt prior to display for editing.
- [ code style=”css”]date_edit_pre[/code] – Applied to post date prior to display for editing.
- [ code style=”css”]date_gmt_edit_pre[/code] – Applied to post date prior to display for editing.
- [ code style=”css”]get_attached_file[/code] – Applied to the attached file information retrieved by the [ code style=”css”]get_attached_file[/code] function.
- [ code style=”css”]get_enclosed[/code] – Applied to the enclosures list for a post by the get_enclosed function.
- [ code style=”css”]get_pages[/code] – Applied to the list of pages returned by the get_pages function.
- [ code style=”css”]get_pung[/code] – Applied to the list of pinged URLs for a post by the [ code style=”css”]get_pung[/code] function.
- [ code style=”css”]get_the_archive_title[/code] – Applied to the archive’s title in the get_the_archive_title function.
- [ code style=”css”]get_the_excerpt[/code] – Applied to the post’s excerpt in the get_the_excerpt function.
- [ code style=”css”]get_the_guid[/code] – Applied to the post’s GUID in the [ code style=”css”]get_the_guid[/code] function.
- [ code style=”css”]get_to_ping[/code] – Applied to the list of URLs to ping for a post by the [ code style=”css”]get_to_ping[/code] function.
- [ code style=”css”]icon_dir[/code] – Applied to the template’s image directory in several functions.
- [ code style=”css”]icon_dir_uri[/code] – Applied to the template’s image directory URI in several functions. Basically allows a plugin to specify that icons for MIME types should come from a different location.
- [ code style=”css”]image_size_names_choose[/code] – Applied to the list of image sizes selectable in the Media Library. Commonly used to make custom image sizes selectable.
- [ code style=”css”]mime_type_edit_pre[/code] – Applied to post mime type prior to display for editing.
- [ code style=”css”]modified_edit_pre[/code] – Applied to post modification date prior to display for editing.
- [ code style=”css”]modified_gmt_edit_pre[/code] – Applied to post modification gmt date prior to display for editing.
- [ code style=”css”]no_texturize_shortcodes[/code] – Applied to registered shortcodes. Can be used to exempt shortcodes from the automatic texturize function.
- [ code style=”css”]parent_edit_pre[/code] – Applied to post parent id prior to display for editing.
- [ code style=”css”]password_edit_pre[/code] – Applied to post password prior to display for editing.
- [ code style=”css”]post_class[/code] – Applied to the classes of the outermost HTML element for a post. Called in the [ code style=”css”]get_post_class[/code] function. Filter function arguments: an array of class names, an array of additional class names that were added to the first array, and the post ID.
- [ code style=”css”]pre_kses[/code] – Applied to various content prior to being processed/sanitized by KSES. This hook allows developers to customize what types of scripts/tags should either be allowed in content or stripped.
- [ code style=”css”]prepend_attachment[/code] – Applied to the HTML to be prepended by the prepend_attachment function.
- [ code style=”css”]protected_title_format[/code] – Used to the change or manipulate the post title when the post is password protected.
- [ code style=”css”]private_title_format[/code] – Used to the change or manipulate the post title when its status is private.
- [ code style=”css”]sanitize_title[/code] – Applied to a post title by the [ code style=”css”]sanitize_title[/code] function, after stripping out HTML tags.
- [ code style=”css”]single_post_title[/code] – Applied to the post title when used to create a blog page title by the [ code style=”css”]wp_title[/code] and [ code style=”css”]single_post_title[/code] functions.
- [ code style=”css”]status_edit_pre[/code] – Applied to post status prior to display for editing.
- [ code style=”css”]the_content[/code] – Applied to the post content retrieved from the database, prior to printing on the screen (also used in some other operations, such as trackbacks).
- [ code style=”css”]the_content_rss[/code] – Applied to the post content prior to including in an RSS feed. (Deprecated)
- [ code style=”css”]the_content_feed[/code] – Applied to the post content prior to including in an RSS feed.
- [ code style=”css”]the_editor_content[/code] – Applied to post content before putting it into a rich editor window.
- [ code style=”css”]the_excerpt[/code] – Applied to the post excerpt (or post content, if there is no excerpt) retrieved from the database, prior to printing on the screen (also used in some other operations, such as trackbacks).
- [ code style=”css”]the_excerpt_rss[/code] – Applied to the post excerpt prior to including in an RSS feed.
- [ code style=”css”]the_password_form[/code] – Applied to the password form for protected posts.
- [ code style=”css”]the_tags[/code] – Applied to the tags retrieved from the database, prior to printing on the screen.
- [ code style=”css”]the_tags[/code] – Applied to the post title retrieved from the database, prior to printing on the screen (also used in some other operations, such as trackbacks).
- [ code style=”css”]the_title_rss[/code] – Applied to the post title before including in an RSS feed (after first filtering with [ code style=”css”]the_title[/code].
- [ code style=”css”]title_edit_pre[/code] – Applied to post title prior to display for editing.
- [ code style=”css”]type_edit_pre[/code] – Applied to post type prior to display for editing.
- [ code style=”css”]wp_dropdown_pages[/code] – Applied to the HTML dropdown list of WordPress pages generated by the [ code style=”css”]wp_dropdown_pages[/code] function.
- [ code style=”css”]wp_list_pages[/code] – Applied to the HTML list generated by the [ code style=”css”]wp_list_pages[/code] function.
- [ code style=”css”]wp_list_pages_excludes[/code] – Applied to the list of excluded pages (an array of page IDs) in the [ code style=”css”]wp_list_pages[/code] function.
- [ code style=”css”]wp_get_attachment_metadata[/code] – Applied to the attachment metadata retrieved by the [ code style=”css”]wp_get_attachment_metadata[/code] function.
- [ code style=”css”]wp_get_attachment_thumb_file[/code] – Applied to the attachment thumbnail file retrieved by the [ code style=”css”]wp_get_attachment_thumb_file[/code] function.
- [ code style=”css”]wp_get_attachment_thumb_url[/code] – Applied to the attachment thumbnail URL retrieved by the [ code style=”css”]wp_get_attachment_thumb_URL[/code] function.
- wp_get_attachment_url – Applied to the attachment URL retrieved by the [ code style=”css”]wp_get_attachment_url[/code] function.
- [ code style=”css”]wp_mime_type_icon[/code] – Applied to the MIME type icon for an attachment calculated by the [ code style=”css”]wp_mime_type_icon[/code] function.
- [ code style=”css”]wp_title[/code] – Applied to the blog page title before sending to the browser in the [ code style=”css”]wp_title[/code] function.
Database Writes
- [ code style=”css”]add_ping[/code] – Applied to the new value of the pinged field on a post when a ping is added, prior to saving the new information in the database.
- [ code style=”css”]attachment_fields_to_save[/code] – Applied to fields associated with an attachment prior to saving them in the database. Called in the [ code style=”css”]media_upload_form_handler[/code] function. Filter function arguments: an array of post attributes, an array of attachment fields including the changes submitted from the form.
- [ code style=”css”]attachment_max_dims[/code] – Applied to the maximum image dimensions before reducing an image size. Filter function input (and return value) is either false (if no maximum dimensions have been specified) or a two-item list (width, height).
- [ code style=”css”]category_save_pre[/code] – Applied to post category comma-separated list prior to saving it in the database (also used for attachments).
- [ code style=”css”]comment_status_pre[/code] – Applied to post comment status prior to saving it in the database (also used for attachments).
- [ code style=”css”]content_filtered_save_pre[/code] – Applied to filtered post content prior to saving it in the database (also used for attachments).
- [ code style=”css”]content_save_pre[/code] – Applied to post content prior to saving it in the database (also used for attachments).
- [ code style=”css”]excerpt_save_pre[/code] – Applied to post excerpt prior to saving it in the database (also used for attachments).
- [ code style=”css”]image_save_pre[/code] (deprecated) – Use image_editor_save_pre instead.
- [ code style=”css”]jpeg_quality[/code] (deprecated) – Use [ code style=”css”]wp_editor_set_quality[/code] or [ code style=”css”]WP_Image_Editor::set_quality()[/code] instead.
- [ code style=”css”]name_save_pre[/code] (Deprecated) – Applied to post name prior to saving it in the database (also used for attachments).
- [ code style=”css”]phone_content[/code] – Applied to the content of a post submitted by email, before saving.
- [ code style=”css”]ping_status_pre[/code] – Applied to post ping status prior to saving it in the database (also used for attachments).
- [ code style=”css”]post_mime_type_pre[/code] – Applied to the MIME type for an attachment prior to saving it in the database.
- [ code style=”css”]status_save_pre[/code] – Applied to post status prior to saving it in the database.
- [ code style=”css”]thumbnail_filename[/code] – Applied to the file name for the thumbnail when uploading an image.
- [ code style=”css”]title_save_pre[/code] – Applied to post title prior to saving it in the database (also used for attachments).
- [ code style=”css”]update_attached_file[/code] – Applied to the attachment information prior to saving in post metadata in the update_attached_file function. Filter function arguments: attachment information, attachment ID.
- [ code style=”css”]wp_create_thumbnail[/code] (deprecated)
- [ code style=”css”]wp_delete_file[/code] – Applied to an attachment file name just before deleting.
- [ code style=”css”]wp_generate_attachment_metadata[/code] – Applied to the attachment metadata array before saving in the database.
- [ code style=”css”]wp_save_image_file[/code] (deprecated) – [ code style=”css”]Use[/code] wp_save_image_editor_file instead.
- [ code style=”css”]wp_thumbnail_creation_size_limit[/code] – Applied to the size of the thumbnail when uploading an image. Filter function arguments: max file size, attachment ID, attachment file name.
- [ code style=”css”]wp_thumbnail_max_side_length[/code] – Applied to the size of the thumbnail when uploading an image. Filter function arguments: image side max size, attachment ID, attachment file name.
- [ code style=”css”]wp_update_attachment_metadata[/code] – Applied to the attachment metadata just before saving in the [ code style=”css”]wp_update_attachment_metadata[/code] function. Filter function arguments: meta data, attachment ID.
Comment, Trackback, and Ping Filters
Database Reads
- [ code style=”css”]comment_excerpt[/code] applied to the comment excerpt by the comment_excerpt function. See also [ code style=”css”]get_comment_excerpt[/code].
- [ code style=”css”]comment_flood_filter[/code] – Applied when someone appears to be flooding your blog with comments. Filter function arguments: already blocked (true/false, whether a previous filtering plugin has already blocked it; set to true and return true to block this comment in a plugin), time of previous comment, time of current comment.
- [ code style=”css”]comment_post_redirect[/code] – Applied to the redirect location after someone adds a comment. Filter function arguments: redirect location, comment info array.
- [ code style=”css”]comment_text[/code] – Applied to the comment text before displaying on the screen by the [ code style=”css”]comment_text[/code] function, and in the admin menus.
- [ code style=”css”]comment_text_rss[/code] – Applied to the comment text prior to including in an RSS feed.
- [ code style=”css”]comments_array[/code] – Applied to the array of comments for a post in the comments_template function. Filter function arguments: array of comment information structures, post ID.
- [ code style=”css”]comments_number[/code] – Applied to the formatted text giving the number of comments generated by the comments_number function. See also [ code style=”css”]get_comments_number[/code].
- [ code style=”css”]get_comment_excerpt[/code] – Applied to the comment excerpt read from the database by the [ code style=”css”]get_comment_excerpt[/code] function (which is also called by [ code style=”css”]comment_excerpt[/code]. See also [ code style=”css”]comment_excerpt[/code].
- [ code style=”css”]get_comment_ID[/code] – Applied to the comment ID read from the global [ code style=”css”]$comments[/code] variable by the [ code style=”css”]get_comment_ID[/code] function.
- [ code style=”css”]get_comment_text[/code] – Applied to the comment text of the current comment in the [ code style=”css”]get_comment_text[/code] function, which is also called by the [ code style=”css”]comment_text[/code] function.
- [ code style=”css”]get_comment_type[/code] – Applied to the comment type (“comment”, “trackback”, or “pingback”) by the [ code style=”css”]get_comment_type[/code] function (which is also called by [ code style=”css”]comment_type[/code]).
- [ code style=”css”]get_comments_number[/code] – Applied to the comment count read from the [ code style=”css”]$post[/code] global variable by the [ code style=”css”]get_comments_number[/code] function (which is also called by the comments_number function; see also comments_number filter).
- [ code style=”css”]post_comments_feed_link[/code] – Applied to the feed URL generated for the comments feed by the [ code style=”css”]comments_rss[/code] function.
Database Writes
- [ code style=”css”]comment_save_pre[/code] – Applied to the comment data just prior to updating/editing comment data. Function arguments: comment data array, with indices “[ code style=”css”]comment_post_ID[/code]“, “[ code style=”css”]comment_author[/code]“, “[ code style=”css”]comment_author_email[/code]“, “[ code style=”css”]comment_author_url[/code]“, “[ code style=”css”]comment_content[/code]“, “[ code style=”css”]comment_type[/code]“, and “[ code style=”css”]user_ID[/code]“.
- [ code style=”css”]pre_comment_approved[/code] – Applied to the current comment’s approval status (true/false) to allow a plugin to override. Return true/false and set first argument to true/false to approve/disapprove the comment, and use global variables such as [ code style=”css”]$comment_ID[/code] to access information about this comment.
- [ code style=”css”]pre_comment_content[/code] – Applied to the content of a comment prior to saving the comment in the database.
- [ code style=”css”]preprocess_comment[/code] – Applied to the comment data prior to any other processing, when saving a new comment in the database. Function arguments: comment data array, with indices “[ code style=”css”]comment_post_ID[/code]“, “comment_author”, “[ code style=”css”]comment_author_email[/code]“, “[ code style=”css”]comment_author_url[/code]“, “[ code style=”css”]comment_content[/code]“, “[ code style=”css”]comment_type[/code]“, and “[ code style=”css”]user_ID[/code]“.
- [ code style=”css”]wp_insert_post_data[/code] – Applied to modified and unmodified post data in [ code style=”css”]wp_insert_post()[/code] prior to update or insertion of post into database. Function arguments: modified and extended post array and sanitized post array.
Category and Term Filters
Database Reads
- [ code style=”css”]category_description[/code] – Applied to the “description” field categories by the [ code style=”css”]category_description[/code] and [ code style=”css”]wp_list_categories[/code] functions. Filter function arguments: description, category ID when called from [ code style=”css”]category_description[/code]; description, category information array (all fields from the category table for that particular category) when called from [ code style=”css”]wp_list_categories[/code].
- [ code style=”css”]category_feed_link[/code] – Applied to the feed URL generated for the category feed by the [ code style=”css”]get_category_feed_link[/code] function.
- [ code style=”css”]category_link[/code] – Applied to the URL created for a category by the [ code style=”css”]get_category_link[/code] function. Filter function arguments: link URL, category ID.
- [ code style=”css”]get_ancestors[/code] – Applied to the list of ancestor IDs returned by the [ code style=”css”]get_ancestors[/code] function (which is in turn used by many other functions). Filter function arguments: ancestor IDs array, given object ID, given object type.
- [ code style=”css”]get_categories[/code] – Applied to the category list generated by the [ code style=”css”]get_categories[/code] function (which is in turn used by many other functions). Filter function arguments: category list, get_categories options list.
- [ code style=”css”]get_category[/code] – Applied to the category information that the get_category function looks up, which is basically an array of all the fields in WordPress’s category table for a particular category ID.
- [ code style=”css”]list_cats[/code] – Called for two different purposes: 1. the [ code style=”css”]wp_dropdown_categories[/code] function uses it to filter the show_option_all and [ code style=”css”]show_option_none[/code] arguments (which are used to put options “All” and “None” in category drop-down lists). No additional filter function arguments; and 2: the [ code style=”css”]wp_list_categories[/code] function applies it to the category names. Filter function arguments: category name, category information list (all fields from the category table for that particular category).
- [ code style=”css”]list_cats_exclusions[/code] – Applied to the SQL WHERE statement giving the categories to be excluded by the get_categories function. Typically, a plugin would add to this list, in order to exclude certain categories or groups of categories from category lists. Filter function arguments: excluded category WHERE clause, [ code style=”css”]get_categories[/code] options list.
- [ code style=”css”]single_cat_title[/code] – Applied to the category name when used to create a blog page title by the [ code style=”css”]wp_title[/code] and [ code style=”css”]single_cat_title[/code] functions.
- the_category – Applied to the list of categories (an HTML list with links) created by the [ code style=”css”]get_the_category_list[/code] function. Filter function arguments: generated HTML text, list separator being used (empty string means it is a default LI list), parents argument to [ code style=”css”]get_the_category_list[/code].
- [ code style=”css”]the_category_rss[/code] – Applied to the category list (a list of category XML elements) for a post by the get_the_category_rss function, before including in an RSS feed. Filter function arguments are the list text and the type (“rdf” or “rss” generally).
- [ code style=”css”]wp_dropdown_cats[/code] – Applied to the drop-down category list (a text string containing HTML option elements) generated by the [ code style=”css”]wp_dropdown_categories[/code] function.
- [ code style=”css”]wp_list_categories[/code] – Applied to the category list (an HTML list) generated by the [ code style=”css”]wp_list_categories[/code] function.
- [ code style=”css”]wp_get_object_terms[/code] – Applied to the list of terms (an array of objects) generated by the [ code style=”css”]wp_get_object_terms[/code] function, which is called by a number of category/term related functions, such as [ code style=”css”]get_the_terms[/code] and [ code style=”css”]get_the_category[/code].
Database Writes
- [ code style=”css”]pre_category_description[/code] – Applied to the category description prior to saving in the database.
- [ code style=”css”]wp_update_term_parent[/code] – Filter term parent before update to term is applied, hook to this filter to see if it will cause a hierarchy loop.
- [ code style=”css”]edit_terms[/code] – (actually an action, but often used like a filter) hooked in prior to saving taxonomy/category change in the database
- [ code style=”css”]pre_category_name[/code] – Applied to the category name prior to saving in the database.
- [ code style=”css”]pre_category_nicename[/code] – Applied to the category nice name prior to saving in the database.
Link Filters
These hooks let you filter links related to posts, pages, archives, and feeds.
- [ code style=”css”]attachment_link[/code] – Applied to the calculated attachment permalink by the [ code style=”css”]get_attachment_link[/code] function. Filter function arguments: link URL, attachment ID.
- [ code style=”css”]author_feed_link[/code] – Applied to the feed URL generated for the author feed by the [ code style=”css”]get_author_rss_link[/code] function.
- author_link – Applied to the author’s archive permalink created by the [ code style=”css”]get_author_posts_url[/code] function. Filter function arguments: link URL, author ID, author’s “nice” name. Note that [ code style=”css”]get_author_posts_url[/code] is called within functions [ code style=”css”]wp_list_authors[/code] and [ code style=”css”]the_author_posts_link[/code].
- [ code style=”css”]comment_reply_link[/code] – Applied to the link generated for replying to a specific comment by the [ code style=”css”]get_comment_reply_link[/code] function which is called within function [ code style=”css”]comments_template[/code]. Filter function arguments: link (string), custom options (array), current comment (object), current post (object).
- [ code style=”css”]day_link[/code] – Applied to the link URL for a daily archive by the [ code style=”css”]get_day_link[/code] function. Filter function arguments: URL, year, month number, day number.
- [ code style=”css”]feed_link[/code] – Applied to the link URL for a feed by the [ code style=”css”]get_feed_link[/code] function. Filter function arguments: URL, type of feed (e.g. “rss2”, “atom”, etc.).
- [ code style=”css”]get_comment_author_link[/code] – Applied to the HTML generated for the author’s link on a comment, in the [ code style=”css”]get_comment_author_link[/code] function (which is also called by comment_author_link. Action function arguments: user name.
- [ code style=”css”]get_comment_author_url_link[/code] – Applied to the HTML generated for the author’s link on a comment, in the [ code style=”css”]get_comment_author_url_link[/code] function (which is also called by [ code style=”css”]comment_author_link[/code]).
- [ code style=”css”]month_link[/code] – Applied to the link URL for a monthly archive by the [ code style=”css”]get_month_link[/code] function. Filter function arguments: URL, year, month number.
- [ code style=”css”]page_link[/code] – Applied to the calculated page URL by the get_page_link function. Filter function arguments: URL, page ID. Note that there is also an internal filter called [ code style=”css”]_get_page_link[/code] that can be used to filter the URLS of pages that are not designated as the blog’s home page (same arguments). Note that this only applies to WordPress pages, not posts, custom post types, or attachments.
- [ code style=”css”]post_link[/code] – Applied to the calculated post permalink by the get_permalink function, which is also called by the the_permalink, [ code style=”css”]post_permalink[/code], [ code style=”css”]previous_post_link[/code], and [ code style=”css”]next_post_link[/code] functions. Filter function arguments: permalink URL, post data list. Note that this only applies to WordPress default posts, and not custom post types (nor pages or attachments).
- [ code style=”css”]post_type_link[/code] – Applied to the calculated custom post type permalink by the [ code style=”css”]get_post_permalink[/code] function.
- [ code style=”css”]the_permalink[/code] – Applied to the permalink URL for a post prior to printing by function [ code style=”css”]the_permalink[/code].
- [ code style=”css”]year_link[/code] – Applied to the link URL for a yearly archive by the [ code style=”css”]get_year_link[/code] function. Filter function arguments: URL, year.
- [ code style=”css”]tag_link[/code] – Applied to the URL created for a tag by the [ code style=”css”]get_tag_link[/code] function. Filter function arguments: link URL, tag ID.
- [ code style=”css”]term_link[/code] – Applied to the URL created for a term by the [ code style=”css”]get_term_link[/code] function. Filter function arguments: term link URL, term object and taxonomy slug.
Date and Time Filters
- [ code style=”css”]get_comment_date[/code] – Applied to the formatted comment date generated by the [ code style=”css”]get_comment_date[/code] function (which is also called by [ code style=”css”]comment_date[/code]).
- [ code style=”css”]get_comment_time[/code] – Applied to the formatted comment time in the get_comment_time function (which is also called by comment_time).
- [ code style=”css”]get_the_modified_date[/code] – Applied to the formatted post modification date generated by the [ code style=”css”]get_the_modified_date[/code] function (which is also called by the [ code style=”css”]the_modified_date[/code] function).
- [ code style=”css”]get_the_modified_time[/code] – Applied to the formatted post modification time generated by the [ code style=”css”]get_the_modified_time[/code] and [ code style=”css”]get_post_modified_time[/code] functions (which are also called by the the_modified_time function).
- [ code style=”css”]get_the_time[/code] – Applied to the formatted post time generated by the get_the_time and [ code style=”css”]get_post_time[/code] functions (which are also called by the the_time function).
- [ code style=”css”]the_date[/code] – Applied to the formatted post date generated by the the_date function.
- [ code style=”css”]the_modified_date[/code] – Applied to the formatted post modification date generated by the [ code style=”css”]the_modified_date[/code] function.
- [ code style=”css”]the_modified_time[/code] – Applied to the formatted post modification time generated by the [ code style=”css”]the_modified_time[/code] function.
- [ code style=”css”]the_time[/code] – Applied to the formatted post time generated by the [ code style=”css”]the_time[/code] function.
- [ code style=”css”]the_weekday[/code] – Applied to the post date weekday name generated by the [ code style=”css”]the_weekday[/code] function.
- [ code style=”css”]the_weekday_date[/code] – Applied to the post date weekday name generated by the [ code style=”css”]the_weekday_date[/code] function. Function arguments are the weekday name, before text, and after text (before text and after text are added to the weekday name if the current post’s weekday is different from the previous post’s weekday).
Author and User Filters
- [ code style=”css”]login_body_class[/code] – Allows filtering of the body class applied to the login screen in [ code style=”css”]login_header()[/code].
- [ code style=”css”]login_redirect[/code] – Applied to the [ code style=”css”]redirect_to[/code] post/get variable during the user login process.
- [ code style=”css”]user_contactmethods[/code] – Applied to the contact methods fields on the user profile page. (old page is here: [ code style=”css”]contactmethods[/code])
- [ code style=”css”]update_(meta_type)_metadata[/code] – Applied before a (user) metadata gets updated.
Database Reads
- [ code style=”css”]author_email[/code] – Applied to the comment author’s email address retrieved from the database by the [ code style=”css”]comment_author_email[/code] function. See also [ code style=”css”]get_comment_author_email[/code].
- [ code style=”css”]comment_author[/code] – Applied to the comment author’s name retrieved from the database by the [ code style=”css”]comment_author[/code] function. See also [ code style=”css”]get_comment_author[/code].
- [ code style=”css”]comment_author_rss[/code] – Applied to the comment author’s name prior to including in an RSS feed.
- [ code style=”css”]comment_email[/code] – Applied to the comment author’s email address retrieved from the database by the [ code style=”css”]comment_author_email_link[/code] function.
- [ code style=”css”]comment_url[/code] – Applied to the comment author’s URL retrieved from the database by the [ code style=”css”]comment_author_url[/code] function (see also [ code style=”css”]get_comment_author_url[/code]).
- [ code style=”css”]get_comment_author[/code] – Applied to the comment author’s name retrieved from the database by [ code style=”css”]get_comment_author[/code], which is also called by [ code style=”css”]comment_author[/code]. See also [ code style=”css”]comment_author[/code].
- [ code style=”css”]get_comment_author_email[/code] – Applied to the comment author’s email address retrieved from the database by [ code style=”css”]get_comment_author_email[/code], which is also called by [ code style=”css”]comment_author_email[/code]. See also [ code style=”css”]author_email[/code].
- [ code style=”css”]get_comment_author_IP[/code] – Applied to the comment author’s IP address retrieved from the database by the [ code style=”css”]get_comment_author_IP[/code] function, which is also called by [ code style=”css”]comment_author_IP[/code].
- [ code style=”css”]get_comment_author_url[/code] – Applied to the comment author’s URL retrieved from the database by the [ code style=”css”]get_comment_author_url[/code] function, which is also called by [ code style=”css”]comment_author_url[/code]. See also [ code style=”css”]comment_url[/code].
- [ code style=”css”]login_errors[/code] – Applied to the login error message printed on the login screen.
- [ code style=”css”]login_headertitle[/code] – Applied to the title for the login header URL (Powered by WordPress by default) printed on the login screen.
- [ code style=”css”]login_headerurl[/code] – Applied to the login header URL (points to wordpress.org by default) printed on the login screen.
- [ code style=”css”]login_message[/code] – Applied to the login message printed on the login screen.
- [ code style=”css”]role_has_cap[/code] – Applied to a role’s capabilities list in the [ code style=”css”]WP_Role->has_cap[/code] function. Filter function arguments are the capabilities list to be filtered, the capability being questioned, and the role’s name.
- [ code style=”css”]sanitize_user[/code] – Applied to a user name by the [ code style=”css”]sanitize_user[/code] function. Filter function arguments: user name (after some cleaning up), raw user name, strict (true or false to use strict ASCII or not).
- [ code style=”css”]the_author[/code] – Applied to a post author’s displayed name by the [ code style=”css”]get_the_author[/code] function, which is also called by the [ code style=”css”]the_author[/code] function.
- [ code style=”css”]the_author_email[/code] – Applied to a post author’s email address by the [ code style=”css”]the_author_email[/code] function.
- [ code style=”css”]user_search_columns[/code] – Applied to the list of columns in the [ code style=”css”]wp_users[/code] table to include in the [ code style=”css”]WHERE[/code] clause inside [ code style=”css”]WP_User_Query[/code].
Database Writes
- [ code style=”css”]pre_comment_author_email[/code] – Applied to a comment author’s email address prior to saving the comment in the database.
- [ code style=”css”]pre_comment_author_name[/code] – Applied to a comment author’s user name prior to saving the comment in the database.
- [ code style=”css”]pre_comment_author_url[/code] – Applied to a comment author’s URL prior to saving the comment in the database.
- [ code style=”css”]pre_comment_user_agent[/code] – Applied to the comment author’s user agent prior to saving the comment in the database.
- [ code style=”css”]pre_comment_user_ip[/code] – Applied to the comment author’s IP address prior to saving the comment in the database.
- [ code style=”css”]pre_user_id[/code] – Applied to the comment author’s user ID prior to saving the comment in the database.
- [ code style=”css”]pre_user_description[/code] – Applied to the user’s description prior to saving in the database.
- [ code style=”css”]pre_user_display_name[/code] – Applied to the user’s displayed name prior to saving in the database.
- [ code style=”css”]pre_user_email[/code] – Applied to the user’s email address prior to saving in the database.
- [ code style=”css”]pre_user_first_name[/code] – Applied to the user’s first name prior to saving in the database.
- [ code style=”css”]pre_user_last_name[/code] – Applied to the user’s last name prior to saving in the database.
- [ code style=”css”]pre_user_login[/code] – Applied to the user’s login name prior to saving in the database.
- [ code style=”css”]pre_user_nicename[/code] – Applied to the user’s “nice name” prior to saving in the database.
- [ code style=”css”]pre_user_nickname[/code] – Applied to the user’s nickname prior to saving in the database.
- [ code style=”css”]pre_user_url[/code] – Applied to the user’s URL prior to saving in the database.
- [ code style=”css”]registration_errors[/code] – Applied to the list of registration errors generated while registering a user for a new account.
- [ code style=”css”]user_registration_email[/code] – Applied to the user’s email address read from the registration page, prior to trying to register the person as a new user.
- [ code style=”css”]validate_username[/code] – Applied to the validation result on a new user name. Filter function arguments: valid (true/false), user name being validated.
Blogroll Filters
These hooks are for filtering content related to blogroll links.
- [ code style=”css”]get_bookmarks[/code] – Applied to link/blogroll database query results by the [ code style=”css”]get_bookmarks[/code] function. Filter function arguments: database query results list, [ code style=”css”]get_bookmarks[/code] arguments list.
- [ code style=”css”]link_category[/code] – Applied to the link category by the get_links_list and [ code style=”css”]wp_list_bookmarks[/code] functions (as of WordPress 2.2).
- [ code style=”css”]link_description[/code] – Applied to the link description by the get_links and wp_list_bookmarks functions (as of WordPress 2.2).
- [ code style=”css”]link_rating[/code] – Applied to the link rating number by the [ code style=”css”]get_linkrating[/code] function.
- [ code style=”css”]link_title[/code] – Applied to the link title by the get_links and [ code style=”css”]wp_list_bookmarks[/code] functions (as of WordPress 2.2)
- [ code style=”css”]pre_link_description[/code] – Applied to the link description prior to saving in the database.
- [ code style=”css”]pre_link_image[/code] – Applied to the link image prior to saving in the database.
- [ code style=”css”]pre_link_name[/code] – Applied to the link name prior to saving in the database.
- [ code style=”css”]pre_link_notes[/code] – Applied to the link notes prior to saving in the database.
- [ code style=”css”]pre_link_rel[/code] – Applied to the link relation information prior to saving in the database.
- [ code style=”css”]pre_link_rss[/code] – Applied to the link RSS URL prior to saving in the database.
- [ code style=”css”]pre_link_target[/code] – Applied to the link target information prior to saving in the database.
- [ code style=”css”]pre_link_url[/code] – Applied to the link URL prior to saving in the database.
Blog Information and Option Filters
- [ code style=”css”]all_options[/code] – Applied to the option list retrieved from the database by the [ code style=”css”]get_alloptions[/code] function.
- [ code style=”css”]all_plugins[/code] – Applied to the list of plugins retrieved for display in the plugins list table.
- [ code style=”css”]bloginfo[/code] – Applied to the blog option information retrieved from the database by the [ code style=”css”]bloginfo[/code] function, after first retrieving the information with the [ code style=”css”]get_bloginfo[/code] function. A second argument [ code style=”css”]$show[/code] gives the name of the [ code style=”css”]bloginfo[/code] option that was requested. Note that [ code style=”css”]bloginfo(“url”)[/code], [ code style=”css”]bloginfo(“directory”)[/code] and [ code style=”css”]bloginfo(“home”)[/code] do not use this filtering function (see [ code style=”css”]bloginfo_url[/code]).
- [ code style=”css”]bloginfo_rss[/code] – Applied to the blog option information by function get_bloginfo_rss (which is also called from bloginfo_rss), after first retrieving the information with the get_bloginfo function, stripping out HTML tags, and converting characters appropriately. A second argument $show gives the name of the bloginfo option that was requested.
- [ code style=”css”]bloginfo_url[/code] – Applied to the the output of [ code style=”css”]bloginfo(“url”)[/code], [ code style=”css”]bloginfo(“directory”)[/code] and [ code style=”css”]bloginfo(“home”)[/code] before returning the information.
- [ code style=”css”]loginout[/code] – Applied to the HTML link for logging in and out (generally placed in the sidebar) generated by the wp_loginout function.
- [ code style=”css”]lostpassword_url[/code] – Applied to the URL that allows users to reset their passwords.
- [ code style=”css”]option_(option name)[/code] – Applied to the option value retrieved from the database by the get_option function, after unserializing (which decodes array-based options). To use this filter, you will need to add filters for specific options names, such as “option_foo” to filter the output of get_option(“foo”).
- [ code style=”css”]pre_get_space_used[/code] – Applied to the [ code style=”css”]get_space_used()[/code] function to provide an alternative way of displaying storage space used. Returning false from this filter will revert to default display behavior (used [ code style=”css”]wp_upload_dir()[/code] directory space in megabytes).
- [ code style=”css”]pre_option_(option name)[/code] – Applied to the option value retrieved from the database by the [ code style=”css”]get_alloptions[/code] function, after unserializing (which decodes array-based options). To use this filter, you will need to add filters for specific options names, such as “[ code style=”css”]pre_option_foo[/code]” to filter the option “foo”.
- [ code style=”css”]pre_update_option_(option name)[/code] – Applied the option value before being saving to the database to allow overriding the value to be stored. To use this filter, you will need to add filters for specific options names, such as “[ code style=”css”]pre_update_option_foo[/code]” to filter the option “foo”.
- [ code style=”css”]register[/code] – Applied to the sidebar link created for the user to register (if allowed) or visit the admin panels (if already logged in) by the [ code style=”css”]wp_register[/code] function.
- [ code style=”css”]upload_dir[/code] – Applied to the directory to be used for uploads calculated by the [ code style=”css”]wp_upload_dir[/code] function. Filter function argument is an array with components “dir” (the upload directory path), “url” (the URL of the upload directory), and “error” (which you can set to true if you want to generate an error).
- [ code style=”css”]upload_mimes[/code] – Allows a filter function to return a list of MIME types for uploads, if there is no MIME list input to the [ code style=”css”]wp_check_filetype[/code] function. Filter function argument is an associated list of MIME types whose component names are file extensions (separated by vertical bars) and values are the corresponding MIME types.
General Text Filters
- [ code style=”css”]attribute_escape[/code] – Applied to post text and other content by the attribute_escape function, which is called in many places in WordPress to change certain characters into HTML attributes before sending to the browser.
- [ code style=”css”]js_escape[/code] – Applied to JavaScript code before sending to the browser in the js_escape function.
- [ code style=”css”]sanitize_key[/code] – Applied to key before using it for your settings, field, or other needs, generated by [ code style=”css”]sanitize_key[/code] function
Administrative Filters
These hooks let you filter content related to the WordPress dashboard, including content editing screens.
- [ code style=”css”]admin_user_info_links[/code] – Applied to the user profile and info links in the WordPress admin quick menu.
- [ code style=”css”]autosave_interval[/code] – Applied to the interval for auto-saving posts.
- [ code style=”css”]bulk_actions[/code] – Applied to an array of bulk items in admin bulk action drop-downs.
- [ code style=”css”]bulk_post_updated_messages[/code] – Applied to an array of bulk action updated messages.
- [ code style=”css”]cat_rows[/code] – Applied to the category rows HTML generated for managing categories in the admin menus.
- [ code style=”css”]comment_edit_pre[/code] – Applied to comment content prior to display in the editing screen.
- comment_edit_redirect – Applied to the redirect location after someone edits a comment in the admin [ code style=”css”]menus[/code]. Filter function arguments: redirect location, comment ID.
- [ code style=”css”]comment_moderation_subject[/code] – Applied to the mail subject before sending email notifying the administrator of the need to moderate a new comment. Filter function arguments: mail subject, comment ID. Note that this happens inside the default [ code style=”css”]wp_notify_moderator[/code] function, which is a “pluggable” function, meaning that plugins can override it; see Plugin API).
- [ code style=”css”]comment_moderation_text[/code] – Applied to the body of the mail message before sending email notifying the administrator of the need to moderate a new comment. Filter function arguments: mail body text, comment ID. Note that this happens inside the default [ code style=”css”]wp_notify_moderator[/code] function, which is a “pluggable” function, meaning that plugins can override it; see Plugin API).
- [ code style=”css”]comment_notification_headers[/code] – Applied to the mail headers before sending email notifying the post author of a new comment. Filter function arguments: mail header text, comment ID. Note that this happens inside the default [ code style=”css”]wp_notify_postauthor[/code] function, which is a “pluggable” function, meaning that plugins can override it; see Plugin API).
- [ code style=”css”]comment_notification_subject[/code] – Applied to the mail subject before sending email notifying the post author of a new comment. Filter function arguments: mail subject, comment ID. Note that this happens inside the default [ code style=”css”]wp_notify_postauthor[/code] function, which is a “pluggable” function, meaning that plugins can override it; see Plugin API).
- [ code style=”css”]comment_notification_text[/code] – Applied to the body of the mail message before sending email notifying the post author of a new comment. Filter function arguments: mail body text, comment ID. Note that this happens inside the default [ code style=”css”]wp_notify_postauthor[/code] function, which is a “pluggable” function, meaning that plugins can override it; see Plugin API).
- [ code style=”css”]comment_row_actions[/code] – Applied to the list of action links under each comment row (like Reply, Quick Edit, Edit).
- [ code style=”css”]cron_request[/code] – Allows filtering of the URL, key and arguments passed to [ code style=”css”]wp_remote_post()[/code] in [ code style=”css”]spawn_cron()[/code].
- [ code style=”css”]cron_schedules[/code] – Applied to an empty array to allow a plugin to generate cron schedules in the [ code style=”css”]wp_get_schedules[/code] function.
- [ code style=”css”]custom_menu_order[/code] – Used to activate the ‘[ code style=”css”]menu_order[/code]‘ filter.
- [ code style=”css”]default_content[/code] – Applied to the default post content prior to opening the editor for a new post.
- [ code style=”css”]default_excerpt[/code] – Applied to the default post excerpt prior to opening the editor for a new post.
- [ code style=”css”]default_title[/code] – Applied to the default post title prior to opening the editor for a new post.
- [ code style=”css”]editable_slug[/code] – Applied to the post, page, tag or category slug by the [ code style=”css”]get_sample_permalink[/code] function.
- [ code style=”css”]format_to_edit[/code] – Applied to post content, excerpt, title, and password by the [ code style=”css”]format_to_edit[/code] function, which is called by the admin menus to set up a post for editing. Also applied to when editing comments in the admin menus.
- [ code style=”css”]format_to_post[/code] – Applied to post content by the [ code style=”css”]format_to_post[/code] function, which is not used in WordPress by default.
- [ code style=”css”]manage_edit–${post_type}_columns[/code] – Applied to the list of columns to print on the manage posts screen for a custom post type. Filter function argument/return value is an associative array where the element key is the name of the column, and the value is the header text for that column. See also action [ code style=”css”]manage_${post_type}_posts_custom_column[/code], which puts the column information into the edit screen.
- [ code style=”css”]manage_link–manager_columns[/code] – Was [ code style=”css”]manage_link_columns[/code] until WordPress 2.7. applied to the list of columns to print on the blogroll management screen. Filter function argument/return value is an associative list where the element key is the name of the column, and the value is the header text for that column. See also action [ code style=”css”]manage_link_custom_column[/code], which puts the column information into the edit screen.
- manage_posts_columns – Applied to the list of columns to print on the manage posts screen. Filter function argument/return value is an associative array where the element key is the name of the column, and the value is the header text for that column. See also action [ code style=”css”]manage_posts_custom_column[/code], which puts the column information into the edit screen. (see Scompt’s tutorial for examples and use.)
- [ code style=”css”]manage_pages_columns[/code] – Applied to the list of columns to print on the manage pages screen. Filter function argument/return value is an associative array where the element key is the name of the column, and the value is the header text for that column. See also action [ code style=”css”]manage_pages_custom_column[/code], which puts the column information into the edit screen.
- [ code style=”css”]manage_users_columns[/code]
- [ code style=”css”]manage_users_custom_column[/code]
- [ code style=”css”]manage_users_sortable_columns[/code]
- [ code style=”css”]media_row_actions[/code] – Applied to the list of action links under each file in the Media Library (like View, Edit).
- [ code style=”css”]menu_order[/code] – Applied to the array for the admin menu order. Must be activated with the ‘[ code style=”css”]custom_menu_order[/code]‘ filter before.
- [ code style=”css”]nonce_life[/code] – Applied to the lifespan of a nonce to generate or verify the nonce. Can be used to generate nonces which expire earlier. The value returned by the filter should be in seconds.
- [ code style=”css”]nonce_user_logged_out[/code] – Applied to the current user ID used to generate or verify a nonce when the user is logged out.
- [ code style=”css”]plugin_row_meta[/code] – Add additional links below each plugin on the plugins page.
- [ code style=”css”]postmeta_form_limit[/code] – Applied to the number of post-meta information items shown on the post edit screen.
- [ code style=”css”]post_row_actions[/code] – Applied to the list of action links (like Quick Edit, Edit, View, Preview) under each post in the Posts > All Posts section.
- [ code style=”css”]post_updated_messages[/code] – Applied to the array storing user-visible administrative messages when working with posts, pages and custom post types. This filter is used to change the text of said messages, not to trigger them. See “customizing the messages” in the [ code style=”css”]register_post_type[/code] documentation.
- [ code style=”css”]pre_upload_error[/code] – Applied to allow a plugin to create an XMLRPC error for uploading files.
- [ code style=”css”]preview_page_link[/code] – Applied to the link on the page editing screen that shows the page preview at the bottom of the screen.
- [ code style=”css”]preview_post_link[/code] – Applied to the link on the post editing screen that shows the post preview at the bottom of the screen.
- [ code style=”css”]richedit_pre[/code] – Applied to post content by the [ code style=”css”]wp_richedit_pre[/code] function, before displaying in the rich text editor.
- [ code style=”css”]schedule_event[/code] – Applied to each recurring and single event as it is added to the cron schedule.
- [ code style=”css”]set–screen–option[/code] – Filter a screen option value before it is set.
- [ code style=”css”]show_password_fields[/code] – Applied to the true/false variable that controls whether the user is presented with the opportunity to change their password on the user profile screen (true means to show password changing fields; false means don’t).
- [ code style=”css”]terms_to_edit[/code] – Applied to the CSV of terms (for each taxonomy) that is used to show which terms are attached to the post.
- [ code style=”css”]the_editor[/code] – Applied to the HTML DIV created to house the rich text editor, prior to printing it on the screen. Filter function argument/return value is a string.
- [ code style=”css”]user_can_richedit[/code] – Applied to the calculation of whether the user’s browser has rich editing capabilities, and whether the user wants to use the rich editor, in the [ code style=”css”]user_can_richedit[/code] function. Filter function argument and return value is true/false if the current user can/cannot use the rich editor.
- [ code style=”css”]user_has_cap[/code] – Applied to a user’s capabilities list in the [ code style=”css”]WP_User->has_cap[/code] function (which is called by the [ code style=”css”]current_user_can[/code] function). Filter function arguments are the capabilities list to be filtered, the capability being questioned, and the argument list (which has things such as the post ID if the capability is to edit posts, etc.)
- [ code style=”css”]wp_handle_upload_prefilter[/code] – Applied to the upload information when uploading a file. Filter function argument: array which represents a single element of [ code style=”css”]$_FILES[/code].
- [ code style=”css”]wp_handle_upload[/code] – Applied to the upload information when uploading a file. Filter function argument: array with elements “file” (file name), “url”, “type”.
- [ code style=”css”]wp_revisions_to_keep[/code] – Alters how many revisions are kept for a given post. Filter function arguments: number representing desired revisions saved (default is unlimited revisions), the post object.
- [ code style=”css”]wp_terms_checklist_args[/code] – Applied to arguments of the [ code style=”css”]wp_terms_checklist()[/code] function. Filter function argument: array of checklist arguments, post ID.
- [ code style=”css”]wp_upload_tabs[/code] – Applied to the list of custom tabs to display on the upload management admin screen. Use action [ code style=”css”]upload_files_(tab)[/code] to display a page for your custom tab (see Plugin API/Action Reference).
- [ code style=”css”]media_upload_tabs[/code] – Applied to the list of custom tabs to display on the upload management admin screen. Use action [ code style=”css”]upload_files_(tab)[/code] to display a page for your custom tab (see Plugin API/Action Reference).
- [ code style=”css”]plugin_action_links_[/code](plugin file name) – Applied to the list of links to display on the plugins page (beside the activate/deactivate links).
- [ code style=”css”]views_edit–post[/code] – Applied to the list posts eg All (30) | Published (22) | Draft (5) | Pending (2) | Trash (1)
Rich Text Editor Filters
Using these hooks, you can modify the configuration of TinyMCE, the rich text editor.
- [ code style=”css”]mce_spellchecker_languages[/code] – Applied to the language selection available in the spell checker.
- [ code style=”css”]mce_buttons[/code], [ code style=”css”]mce_buttons_2[/code], [ code style=”css”]mce_buttons_3[/code], [ code style=”css”]mce_buttons_4[/code] – Applied to the rows of buttons for the rich editor toolbar (each is an array of button names).
- [ code style=”css”]mce_css[/code] – Applied to the CSS file URL for the rich text editor.
- [ code style=”css”]mce_external_plugins[/code] – Applied to the array of external plugins to be loaded by the rich text editor.
- [ code style=”css”]mce_external_languages[/code] – Applied to the array of language files loaded by external plugins, allowing them to use the standard translation method (see tinymce/langs/wp-langs.php for reference).
- [ code style=”css”]tiny_mce_before_init[/code] – Applied to the whole init array for the editor.
Template Filters
The filter hooks in this section allow you to work with themes, templates, and style files.
- [ code style=”css”]locale_stylesheet_uri[/code] – Applied to the locale-specific stylesheet URI returned by the [ code style=”css”]get_locale_stylesheet_uri[/code] function. Filter function arguments: URI, stylesheet directory URI.
- [ code style=”css”]stylesheet[/code] – Applied to the stylesheet returned by the [ code style=”css”]get_stylesheet[/code] function.
- [ code style=”css”]stylesheet_directory[/code] – Applied to the stylesheet directory returned by the [ code style=”css”]get_stylesheet_directory[/code] function. Filter function arguments: stylesheet directory, stylesheet.
- [ code style=”css”]stylesheet_directory_uri[/code] – Applied to the stylesheet directory URI returned by the [ code style=”css”]get_stylesheet_directory_uri[/code] function. Filter function arguments: stylesheet directory URI, stylesheet.
- [ code style=”css”]stylesheet_uri[/code] – Applied to the stylesheet URI returned by the [ code style=”css”]get_stylesheet_uri[/code] function. Filter function arguments: stylesheet URI, stylesheet.
- [ code style=”css”]template[/code] – Applied to the template returned by the get_template function.
- [ code style=”css”]template_directory[/code] – Applied to the template directory returned by the [ code style=”css”]get_template_directory[/code] function. Filter function arguments: template directory, template.
- [ code style=”css”]template_directory_uri[/code] – Applied to the template directory URI returned by the [ code style=”css”]get_template_directory_uri[/code] function. Filter function arguments: template directory URI, template.
- [ code style=”css”]theme_root[/code] – Applied to the theme root directory (normally wp-content/themes) returned by the get_theme_root function.
- [ code style=”css”]theme_root_uri[/code] – Applied to the theme root directory URI returned by the [ code style=”css”]get_theme_root_uri[/code] function. Filter function arguments: URI, site URL. You can also replace individual template files from your theme, by using the following filter hooks. See also the [ code style=”css”]template_redirect[/code] action hook. Each of these filters takes as input the path to the corresponding template file in the current theme. A plugin can modify the file to be used by returning a new path to a template file.
- [ code style=”css”]404_template[/code]
- [ code style=”css”]archive_template[/code] – You can use this for example to enforce a specific template for a custom post type archive. This way you can keep all the code in a plugin.
- [ code style=”css”]attachment_template[/code]
- [ code style=”css”]author_template[/code]
- [ code style=”css”]category_template[/code]
- [ code style=”css”]comments_popup_template[/code]
- [ code style=”css”]comments_template[/code] – The “[ code style=”css”]comments_template[/code]” filter can be used to load a custom template form a plugin which replace the themes default comment template.
- [ code style=”css”]date_template[/code]
- [ code style=”css”]home_template[/code]
- [ code style=”css”]page_template[/code]
- [ code style=”css”]paged_template[/code]
- [ code style=”css”]search_template[/code]
- [ code style=”css”]single_template[/code] – You can use this for example to enforce a specific template for a custom post type. This way you can keep all the code in a plugin.
- [ code style=”css”]shortcut_link[/code] – Applied to the “Press This” bookmarklet link.
- template_include
- [ code style=”css”]wp_nav_menu_args[/code] – Applied to the arguments of the [ code style=”css”]wp_nav_menu[/code] function.
- [ code style=”css”]wp_nav_menu_items[/code] – Filter the HTML list content for navigation menus.
Registration & Login Filters
- [ code style=”css”]authenticate[/code] – Allows basic authentication to be performed on login based on username and password.
- [ code style=”css”]registration_errors[/code] – Applied to the list of registration errors generated while registering a user for a new account.
- [ code style=”css”]user_registration_email[/code] – Applied to the user’s email address read from the registration page, prior to trying to register the person as a new user.
- [ code style=”css”]validate_username[/code] – Applied to the validation result on a new user name. Filter function arguments: valid (true/false), user name being validated.
- [ code style=”css”]wp_authenticate_user[/code] – Applied when a user attempted to log in, after WordPress validates username and password, but before validation errors are checked.
Redirect/Rewrite Filters – Advanced
These advanced filters relate to WordPress’s handling of rewrite rules.
- [ code style=”css”]allowed_redirect_hosts[/code] – Applied to the list of host names deemed safe for redirection. wp-login.php uses this to defend against a dangerous ‘[ code style=”css”]redirect_to[/code]‘ request parameter
- [ code style=”css”]author_rewrite_rules[/code] – Applied to the author-related rewrite rules after they are generated.
- [ code style=”css”]category_rewrite_rules[/code] – Applied to the category-related rewrite rules after they are generated.
- [ code style=”css”]comments_rewrite_rules[/code] – Applied to the comment-related rewrite rules after they are generated.
- [ code style=”css”]date_rewrite_rules[/code] – Applied to the date-related rewrite rules after they are generated.
- [ code style=”css”]mod_rewrite_rules[/code] – Applied to the list of rewrite rules given to the user to put into their .htaccess file when they change their permalink structure. (Note: replaces deprecated filter rewrite_rules.)
- [ code style=”css”]page_rewrite_rules[/code] – Applied to the page-related rewrite rules after they are generated.
- [ code style=”css”]post_rewrite_rules[/code] – Applied to the post-related rewrite rules after they are generated.
- [ code style=”css”]redirect_canonical[/code] – Can be used to cancel a “canonical” URL redirect. Accepts 2 parameters: [ code style=”css”]$redirect_url[/code], [ code style=”css”]$requested_url[/code]. To cancel the redirect return [ code style=”css”]FALSE[/code], to allow the redirect return [ code style=”css”]$redirect_url[/code].
- [ code style=”css”]rewrite_rules_array[/code] – Applied to the entire rewrite rules array after it is generated.
- [ code style=”css”]root_rewrite_rules[/code] – Applied to the root-level rewrite rules after they are generated.
- [ code style=”css”]search_rewrite_rules[/code] – Applied to the search-related rewrite rules after they are generated.
- [ code style=”css”]wp_redirect[/code] – Applied to a redirect URL by the default [ code style=”css”]wp_redirect[/code] function. Filter function arguments: URL, HTTP status code. Note that [ code style=”css”]wp_redirect[/code] is also a “pluggable” function, meaning that plugins can override it; see Plugin API).
- [ code style=”css”]wp_redirect_status[/code] – Applied to the HTTP status code when redirecting by the default [ code style=”css”]wp_redirect[/code] function. Filter function arguments: HTTP status code, URL. Note that [ code style=”css”]wp_redirect[/code] is also a “pluggable” function, meaning that plugins can override it; see Plugin API).
WP_Query Filters
These are filters run by the [ code style=”css”]WP_Query[/code] object in the course of building and executing a query to retrieve posts.
- [ code style=”css”]found_posts[/code] – Applied to the list of posts, just after querying from the database.
- [ code style=”css”]found_posts_query[/code] – After the list of posts to display is queried from the database, WordPress selects rows in the query results. This filter allows you to do something other than [ code style=”css”]SELECT FOUND_ROWS()[/code] at that step.
- [ code style=”css”]post_limits[/code] – Applied to the LIMIT clause of the query that returns the post array.
- [ code style=”css”]posts_clauses[/code] – Applied to the entire SQL query, divided into a keyed array for each clause type, that returns the post array. Can be easier to work with than [ code style=”css”]posts_request[/code].
- [ code style=”css”]posts_distinct[/code] – Allows a plugin to add a [ code style=”css”]DISTINCTROW[/code] clause to the query that returns the post array.
- [ code style=”css”]posts_fields[/code] – Applied to the field list for the query that returns the post array.
- [ code style=”css”]posts_groupby[/code] – Applied to the GROUP BY clause of the query that returns the post array (normally empty).
- [ code style=”css”]posts_join[/code] – Applied to the [ code style=”css”]JOIN[/code] clause of the query that returns the post array. This is typically used to add a table to the [ code style=”css”]JOIN[/code], in combination with the [ code style=”css”]posts_where[/code] filter.
- [ code style=”css”]posts_join_paged[/code] – Applied to the [ code style=”css”]JOIN[/code] clause of the query that returns the post array, after the paging is calculated (though paging does not affect the [ code style=”css”]JOIN[/code], so this is actually equivalent to [ code style=”css”]posts_join[/code]).
- posts_orderby – Applied to the [ code style=”css”]ORDER BY[/code] clause of the query that returns the post array.
- [ code style=”css”]posts_request[/code] – Applied to the entire SQL query that returns the post array, just prior to running the query.
- [ code style=”css”]posts_results[/code] – Allows you to manipulate the resulting array returned from the query.
- [ code style=”css”]posts_search[/code] – Applied to the search SQL that is used in the [ code style=”css”]WHERE[/code] clause of [ code style=”css”]WP_Query[/code].
- [ code style=”css”]posts_where[/code] – Applied to the [ code style=”css”]WHERE[/code] clause of the query that returns the post array.
- [ code style=”css”]posts_where_paged[/code] – Applied to the [ code style=”css”]WHERE[/code] clause of the query that returns the post array, after the paging is calculated (though paging does not affect the [ code style=”css”]WHERE[/code], so this is actually equivalent to [ code style=”css”]posts_where[/code]).
- [ code style=”css”]the_posts[/code] – Applied to the list of posts queried from the database after minimal processing for permissions and draft status on single-post pages.
Media Filters
These media filter hooks enabled you to integrate different types of media.
- [ code style=”css”]editor_max_image_size[/code]
- [ code style=”css”]image_downsize[/code]
- [ code style=”css”]get_image_tag_class[/code]
- [ code style=”css”]get_image_tag[/code]
- [ code style=”css”]image_resize_dimensions[/code]
- [ code style=”css”]intermediate_image_sizes[/code]
- [ code style=”css”]icon_dir[/code]
- [ code style=”css”]wp_get_attachment_image_attributes[/code]
- [ code style=”css”]img_caption_shortcode[/code]
- [ code style=”css”]post_gallery[/code]
- [ code style=”css”]use_default_gallery_style[/code]
- [ code style=”css”]gallery_style[/code]
- [ code style=”css”](adjacent)_image_link[/code]
- [ code style=”css”]embed_defaults[/code]
- [ code style=”css”]load_default_embeds[/code]
- [ code style=”css”]embed_googlevideo[/code]
- [ code style=”css”]upload_size_limit[/code]
- [ code style=”css”]wp_image_editors[/code]
- [ code style=”css”]plupload_default_settings[/code]
- [ code style=”css”]plupload_default_params[/code]
- [ code style=”css”]image_size_names_choose[/code]
- [ code style=”css”]wp_prepare_attachment_for_js[/code]
- [ code style=”css”]media_upload_tabs[/code]
- [ code style=”css”]disable_captions[/code]
- [ code style=”css”]media_view_settings[/code]
- [ code style=”css”]media_view_strings[/code]
- [ code style=”css”]wp_handle_upload_prefilter[/code]
Advanced WordPress Filters
The advanced filter hooks in this section related to internationalization, miscellaneous queries, and other fundamental WordPress functions.
- [ code style=”css”]create_user_query[/code] – Applied to the query used to save a new user’s information to the database, just prior to running the query.
- [ code style=”css”]get_editable_authors[/code] – Applied to the list of post authors that the current user is authorized to edit in the [ code style=”css”]get_editable_authors[/code] function.
- [ code style=”css”]get_next_post_join[/code] – In [ code style=”css”]function[/code] get_next_post (which finds the post after the currently-displayed post), applied to the [ code style=”css”]SQL JOIN[/code] clause (which normally joins to the category table if user is viewing a category archive). Filter function arguments: [ code style=”css”]JOIN[/code] clause, stay in same category (true/false), list of excluded categories.
- [ code style=”css”]get_next_post_sort[/code] – In function get_next_post (which finds the post after the currently-displayed post), applied to the [ code style=”css”]SQL ORDER BY[/code] clause (which normally orders by post date in ascending order with a limit of 1 post). Filter function arguments: [ code style=”css”]ORDER BY[/code] clause.
- [ code style=”css”]get_next_post_where[/code] – In function [ code style=”css”]get_next_post[/code] (which finds the post after the currently-displayed post), applied to the [ code style=”css”]SQL WHERE[/code] clause (which normally looks for the next dated published post). Filter function arguments: [ code style=”css”]WHERE[/code] clause, stay in same category (true/false), list of excluded categories.
- [ code style=”css”]get_previous_post_join[/code] – In function get_previous_post (which finds the post before the currently-displayed post), applied to the [ code style=”css”]SQL JOIN[/code] clause (which normally joins to the category table if user is viewing a category archive). Filter function arguments: join clause, stay in same category (true/false), list of excluded categories.
- [ code style=”css”]get_previous_post_sort[/code] – In function get_previous_post (which finds the post before the currently-displayed post), applied to the [ code style=”css”]SQL ORDER BY[/code] clause (which normally orders by post date in descending order with a limit of 1 post). Filter function arguments: [ code style=”css”]ORDER BY[/code] clause.
- [ code style=”css”]get_previous_post_where[/code] – In function [ code style=”css”]get_previous_post[/code] (which finds the post before the currently-displayed post), applied to the [ code style=”css”]SQL WHERE[/code] clause (which normally looks for the previous dated published post). Filter function arguments: [ code style=”css”]WHERE[/code] clause, stay in same category (true/false), list of excluded categories.
- [ code style=”css”]gettext[/code] – Applied to the translated text by the [ code style=”css”]translation()[/code] function (which is called by functions like the [ code style=”css”]__()[/code] and [ code style=”css”]_e()[/code] internationalization functions ). Filter function arguments: translated text, untranslated text and the text domain. Gets applied even if internationalization is not in effect or if the text domain has not been loaded.
- [ code style=”css”]override_load_textdomain[/code]
- [ code style=”css”]get_meta_sql[/code] – In function [ code style=”css”]WP_Meta_Query::get_sql[/code] (which generates SQL clauses to be appended to a main query for advanced meta queries.), applied to the [ code style=”css”]SQL JOIN[/code] and [ code style=”css”]WHERE[/code] clause generated by the advanced meta query. Filter function arguments: [ code style=”css”]array( compact( ‘join’, ‘where’ )[/code], [ code style=”css”]$this->queries[/code], [ code style=”css”]$type[/code], [ code style=”css”]$primary_table[/code], [ code style=”css”]$primary_id_column[/code], [ code style=”css”]$context[/code] )
- [ code style=”css”]get_others_drafts[/code] – Applied to the query that selects the other users’ drafts for display in the admin menus.
- [ code style=”css”]get_users_drafts[/code] – Applied to the query that selects the users’ drafts for display in the admin menus.
- [ code style=”css”]locale[/code] – Applied to the locale by the [ code style=”css”]get_locale[/code] function.
- [ code style=”css”]query[/code] – Applied to all queries (at least all queries run after plugins are loaded).
- [ code style=”css”]query_string[/code] – Deprecated – use [ code style=”css”]query_vars[/code] or request instead.
- [ code style=”css”]query_vars[/code] – Applied to the list of public WordPress query variables before the SQL query is formed. Useful for removing extra permalink information the plugin has dealt with in some other manner.
- [ code style=”css”]request[/code] – Like [ code style=”css”]query_vars[/code], but applied after “extra” and private query variables have been added.
- [ code style=”css”]excerpt_length[/code] – Defines the length of a single-post excerpt.
- [ code style=”css”]excerpt_more[/code] – Defines the more string at the end of the excerpt.
- [ code style=”css”]post_edit_form_tag[/code] – Allows you to append code to the form tag in the default post/page editor.
- [ code style=”css”]update_user_query[/code] – Applied to the update query used to update user information, prior to running the query.
- [ code style=”css”]uploading_iframe_src[/code] (removed since WP 2.5) – Applied to the HTML src tag for the uploading iframe on the post and page editing screens.
- [ code style=”css”]xmlrpc_methods[/code] – Applied to list of defined XMLRPC methods for the XMLRPC server.
- [ code style=”css”]wp_mail_from[/code] – Applied before any mail is sent by the [ code style=”css”]wp_mail[/code] function. Supplied value is the calculated from address which is wordpress at the current hostname (set by [ code style=”css”]$_SERVER[‘SERVER_NAME’][/code]). The filter should return an email address or name/email combo in the form “user@example.com” or “Name <user@example.com>” (without the quotes!).
- [ code style=”css”]wp_mail_from_name[/code] – Applied before any mail is sent by the [ code style=”css”]wp_mail[/code] function. The filter should return a name string to be used as the email from name.
- [ code style=”css”]update_(meta_type)_metadata[/code] – Applied before a metadata gets updated. For example if a user metadata gets updated the hook would be ‘[ code style=”css”]update_user_metadata[/code]‘
Widgets
These filter hooks let you work with the widgets built into WordPress core.
- [ code style=”css”]dynamic_sidebar_params[/code] – Applied to the arguments passed to the [ code style=”css”]widgets_init[/code] function in the WordPress widgets.
- [ code style=”css”]widget_archives_dropdown_args[/code] – Applied to the arguments passed to the [ code style=”css”]wp_get_archives()[/code] function in the WordPress Archives widget.
- [ code style=”css”]widget_categories_args[/code] – Applied to the arguments passed to the [ code style=”css”]wp_list_categories()[/code] function in the WordPress Categories widget.
- [ code style=”css”]widget_links_args[/code] – Applied to the arguments passed to the [ code style=”css”]wp_list_bookmarks()[/code] function in the WordPress Links widget.
- [ code style=”css”]widget_nav_menu_args[/code] – Applied to the arguments passed to the [ code style=”css”]wp_nav_menu()[/code] function in the WordPress Custom Menu widget.
- [ code style=”css”]widget_pages_args[/code] – Applied to the arguments passed to the [ code style=”css”]wp_list_pages()[/code] function in the WordPress Pages widget.
- [ code style=”css”]widget_tag_cloud_args[/code] – Applied to the arguments passed to the [ code style=”css”]wp_tag_cloud()[/code] function in the WordPress Pages widget.
- [ code style=”css”]widget_text[/code] – Applied to the widget text of the WordPress Text widget. May also apply to some third party widgets as well.
- [ code style=”css”]widget_title[/code] – Applied to the widget title of any user editable WordPress Widget. May also apply to some third party widgets as well.
Conclusion
Filters are a fundamental concept in WordPress development, so understanding how they work and how to use them is essential if you’re interested in developing your own plugins and themes.
The Filter cheat sheet above provides an overview of how to code filters and develop with them, as well as a handy filter reference should you need to quickly find the right filter hook while coding. Be sure to bookmark it as a reference for your future WordPress development projects!
If you have any questions or additions for this cheat sheet, let us know in the comments below.