{"id":24617,"date":"2018-09-20T12:00:37","date_gmt":"2018-09-20T12:00:37","guid":{"rendered":"https:\/\/www.designbombs.com\/?p=24617"},"modified":"2018-09-19T20:41:36","modified_gmt":"2018-09-19T20:41:36","slug":"wordpress-filters-cheat-sheet","status":"publish","type":"post","link":"https:\/\/www.designbombs.com\/wordpress-filters-cheat-sheet\/","title":{"rendered":"WordPress Filters Cheat Sheet"},"content":{"rendered":"

This cheat sheet explores a fundamental concept in WordPress development: filters<\/b>.<\/p>\n

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.<\/p>\n

Understanding how filters work isn\u2019t all that easy, partly because the concept is difficult to visualize, and also because filters are often confused with WordPress actions. Yet, it\u2019s an important concept to master because filters are one of the most common ways developers interact with WordPress.<\/p>\n

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.<\/p>\n

WordPress Basics: Hooks & Functions<\/h2>\n

Let\u2019s start with a basic overview of how WordPress works to help you understand the context of where filters fit in WordPress core code .<\/p>\n

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\u2019s processing and then displays it all together as one web page.<\/p>\n

Hooks<\/h3>\n

Throughout the core code are hooks<\/b>, which are basically placeholders developers can use to \u201chook\u201d into WordPress and insert their own custom code for processing as a page is loading.<\/p>\n

There are two types of hooks: filters<\/b> and actions<\/b>:<\/p>\n

Filter hooks<\/b> let you intercept and modify data as it\u2019s 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.<\/p>\n

Action hooks<\/b>, 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.<\/p>\n

Basically, filter hooks change stuff<\/b> and action hooks do stuff<\/b>.<\/p>\n

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\u00a0apply_filters()<\/a><\/code> function, which I\u2019ll show you how to use shortly.<\/p>\n

Functions<\/h3>\n

In order to use WordPress hooks, you need to write a function<\/b>.<\/p>\n

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.<\/p>\n

In WordPress, if you want to \u201cchange stuff\u201d in your theme, you need to code a filter function that uses a filter hook.<\/p>\n

Using Filters: Example<\/h2>\n

There are three basic steps involved in adding your own filters to WordPress:<\/p>\n

    \n
  1. Coding a PHP function that filters the data.<\/li>\n
  2. Hooking into and existing and appropriate filter hook in WordPress by calling add_filter()<\/a><\/code>.<\/li>\n
  3. Putting your PHP function in a WordPress\/plugin file and activating it.<\/li>\n<\/ol>\n

    1. Creating a Filter Function<\/h3>\n

    Say you wanted to filter out bad language in blog post comments on your site.<\/p>\n

    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\u2019t want displayed on your site and replace them with a censor flag by creating the following PHP function:<\/p>\n

    function filter_bad_languge( $content ) {\r\n$badwords = array('fopdoogle', 'gobermouch', 'yaldson');\r\n$content = str_ireplace( $badwords, '{censored}', $content );\r\nreturn $content;\r\n}\r\n<\/pre>\n
    Here\u2019s a breakdown of the code above:<\/p>\n
      \n
    1. This is the code that hooks into the filter hook. It\u2019s easy to spot a custom function as it always starts with function()<\/code>.<\/li>\n
    2. filter_badlanguge<\/code> is the name of the filter function.<\/li>\n
    3. $content<\/code> is the function\u2019s single argument.<\/li>\n
    4. $badwords = array('fopdoogle','gobermouch','yaldson');<\/code> is the first work the function carries out. Specifically, it creates an array called $badwords<\/code> and adds the words fopdoogle, gobermouch, and yaldson to that array.<\/li>\n
    5. str_ireplace<\/code><\/a> loops through your content, searching for any of the words stored in the $badwords<\/code> array, replacing them with \u201c{censored}<\/i>,\u201d and then returning them to $content<\/code>.<\/i><\/li>\n
    6. return is very important here: it\u2019s how the function returns the filtered content back to WordPress core.<\/li>\n<\/ol>\n
      2. Using a Filter Hook<\/h3>\n
      Once you\u2019ve coded your filter, you need to \u201chook\u201d it into WordPress core using a hook call. To do this, you use add_filter()<\/code>:<\/p>\n
      add_filter( 'comment_text', 'filter_bad_language' );\r\n<\/pre>\n
      Here\u2019s what the above code means:<\/p>\n
        \n
      1. 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.<\/li>\n
      2. filter_badlanguage<\/code> is the name of the function that we want to use for filtering.<\/li>\n<\/ol>\n
        3. Installing and Activating a Filter<\/h3>\n
        The last step in order to get your filter hook working is to add your function and add_filter()<\/code> call together in a PHP file. Continuing our bad language example, we would combine the code like so:<\/p>\n
        function filter_bad_languge( $content ) {\r\n$badwords = array('fopdoogle', 'gobermouch', 'yaldson');\r\n$content = str_ireplace( $badwords, '{censored}', $content );\r\nreturn $content;\r\n}\r\nadd_filter( 'comment_text', 'filter_bad_language' );\r\n<\/pre>\n
        Typically, you would either add your function and call to your theme\u2019s 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<\/a> and how to create a plugin<\/a> in the WordPress Developer Handbook.<\/p>\n
        If you decide to use your function in a plugin, you\u2019ll need to install and activate your newly created plugin in order for your code to work.<\/p>\n
        Using Custom Filter Hooks<\/h2>\n
        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.<\/p>\n
        Custom hooks can be created and called in the same way that WordPress core hooks are created and called.<\/p>\n
        There are two basic steps involved in creating and using your own custom filter hooks:<\/p>\n
          \n
        1. Adding a custom filter hook to an existing function using apply_filters()<\/code><\/a>.<\/li>\n
        2. You (or another developer) coding a custom function that hooks into the custom filter hook.<\/li>\n<\/ol>\n
          Creating a Filter Hook<\/h3>\n
          To create a custom hook, you add apply_filters()<\/code> in your code where you would like to place a hook.<\/p>\n
          For example, using the bad language example from above, let\u2019s 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:<\/p>\n
          function filter_bad_languge( $content ) {\r\n$badwords = array('fopdoogle', 'gobermouch', 'yaldson');\r\n$badwords = apply_filters('add_bad_language_filter', $badwords );\r\n$content = str_ireplace( $badwords, '{censored}', $content );\r\nreturn $content;\r\n}\r\n<\/pre>\n
          add_badlanguage_filter<\/code> becomes a filter hook that can be used to modify the list of censored words, with $content<\/code> being the default value to be returned.<\/p>\n
          Using a Custom Filter Hook<\/h3>\n
          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:<\/p>\n
          function add_new_bad_words($profanities) {\r\n$extra_bad_words = array('sard', 'bescumber');\r\n$profanities = array_merge($extra_bad_words, $profanities);\r\nreturn $profanities;\r\n}\r\nadd_filter('add_bad_language_filter', 'add_new_bad_words');\r\n<\/pre>\n
          When the add_new_bad_words function displays the list of bad words, we\u2019ll now see this:<\/p>\n