This makes it easy for plugin and theme authors to apply various filters and alter the output. However, it gets complicated when there are multiple filters applied for the same output.

It was not possible to check if your filter had been run or not in older versions of WordPress. With WordPress 6.1, the new function did_filter solves this problem. This function returns the number of times the filter has been applied in the current request.

How to Use the did_filter Function

If you are familiar with did_action, then this is easy to guess. The did_action function allows you to check if an action has been fired in the current request.

if( did_action( 'hook_name' ) ){
 // do something
}

The did_filter function works the same way, but it checks for the filter. Let’s take a look at this simple implementation

View the code on Gist.

For this example, let’s imagine a scenario where we want to append the category name to the post title using a filter. And if the category name is already appended, the callback should stop the execution.

• plugin_title_change prepends the category name to the post’s title by using the filter ‘lax_plugin’
• theme_title_change plugin checks if the lax_plugin filter is already executed, then prepends the category name

This prevents the duplicate execution of the filter.

How Does It Work?

Every time when we use apply_filters, the global variable $wp_filters gets incremented. See this snippet from the core apply_filters function.

if ( ! isset( $wp_filters[ $hook_name ] ) ) {
$wp_filters[ $hook_name ] = 1;
} else {
++$wp_filters[ $hook_name ];
}

did_filter just returns the count of the hook from the global $wp_filters array.

function did_filter( $hook_name ) {
global $wp_filters;

if ( ! isset( $wp_filters[ $hook_name ] ) ) {
return 0;
}

return $wp_filters[ $hook_name ];
}

When to Use the did_filter Function

The most common use case is to check whether a filter has been applied. You can also use this function to check the number of times a filter has been applied during the current request.

Side note: At the time of this writing, VS code extension PHP Intelephense v1.9.4, throws a warning “Undefined function ‘did_filter’.intelephense(1010).” You can safely ignore it, and the function should work as expected.

Further Reading

did_filter WordPress official documentation

The post Quick Tip: Using the did_filter Function appeared first on WebDevStudios.

Understanding Register Block Style Function

Before going too far, let’s take a look at how we can register a block style by checking out the parameters in the source code.

View the code on Gist.

blockName: Name of block (example: “core/quote”).

styleVariation: An object containing a name and label property.

Name Property: The name value for the object being passed in is a unique lowercase hyphenated string. This is the string that will be rendered in the block class name attribute. WordPress will render this by default as “is-style-” followed by the provided value.

Label Property: The label value is a string that will display underneath the block style in the editor.

Creating a Register Block Style Filter

Here, we’re registering a filter that will add a block style variation named “Fancy Quote” to the quote block. This will set up a new style on the block in the editor. When the “Fancy Quote” style is selected the class name .is-style-fancy-quote will be applied to the wrapper element of the block. Next, we need to enqueue our Javascript file.

View the code on Gist.

Enqueuing the Filter

For this filter to work, it’s important that we make sure the JavaScript file we created is enqueued into the editor. If you’re unsure how to enqueue a file, check out Enqueuing Block Scripts from the Gutenberg handbook.

View the code on Gist.

Verifying the Filter Works

Now that the file is enqueued, it’s time to verify that everything works as expected.

1. Verify that the expected change happens in the editor.
2. Check that your class name is visible in the front end of the site by inspecting the block wrapper element.
3. Experiment with what happens if the filter is disabled or removed.

Step 3 is very important! Sometimes, a disabled filter can trigger a block recovery in the editor.

Take-Aways

The registerBlockStyle filter is my favorite way to demonstrate what filters can do in the Gutenberg Editor. It’s incredibly simple and can make a big difference when adding custom styles to blocks  in the editor. If you enjoyed this article, check back later for the next article in this series registerBlockType filter.

The post Gutenberg Filters: registerBlockStyle appeared first on WebDevStudios.

One thing I’ve noticed a lot, as a frequent user of the WordPress StackExchange, is that many developers don’t know where to start when trying to figure out which actions or hooks might be available to them. In this blog post, I want to help walk through the process of tracking down various hooks with examples of when you might want to use them and how to implement them.

Actions and Filters: What’s the Difference?

This is a very basic mistake I see often when helping people figure out their WordPress issues. Say for example someone wants to modify the post before editing, but they can’t figure out why their code isn’t doing anything. Well, let’s take a look at a basic example that makes a post’s content all-uppercase:

add_action( 'content_edit_pre', function( $post_content ) {
	return strtoupper( $post_content );
} );

Pretty straightforward, right?

On the surface, this looks like a proper filter but it will never work. The reason is that WordPress makes a distinction between actions and filters. Actions are assigned via add_action, while filters are assigned via add_filter. The corresponding methods to call these are do_action and apply_filters, respectively. Under the hood, there’s actually not much difference. In fact, add_action calls add_filter. Here’s the full source code from WordPress:

function add_action($tag, $function_to_add, $priority = 10, $accepted_args = 1) {
    return add_filter($tag, $function_to_add, $priority, $accepted_args);
}

Kind of crazy, right?

It’s because add_filter and add_action do roughly the same thing at the core level, with one minor exception: the returned value of apply_filters can be used to modify existing data structures, while do_action returns literally nothing (void in PHP).

So, our above example will never return any value to modify the content, as do_action simply doesn’t do that. While these differences may make you want to ask, “Why even have different methods?” the distinction is very important.

Actions are for when you want something to happen as a result of something else happening, while filters are used to modify data at run time. Our above example will work with the exact same code, with one minor modification:

add_filter( 'content_edit_pre', function( $post_content ) {
	return strtoupper( $post_content );
} );

[Edit: thanks @Anton Serednii for the correction!]
In WordPress-speak, we use the term “hook” to refer to actions and filters interchangeably, as they are roughly the same thing. When talking about a specific hook, we use either action or term. (Example: “You want to use the admin_enqueue_scripts action to add scripts to WP Admin,” or, “You can use the body_class filter to add additional CSS classes to a page’s <body> tag.”)

Finding the Right Hook

WordPress has a lot of hooks to use. I mean, a lot. A rough count of the WordPress codebase puts the number of hooks called at around 2,744. That’s a lot of hooks!

So, how do you find the right one? Well, you can refer to the action and filter references linked above (and also check out the Plugin API landing page), but those references cover everything and, as we just discussed. That’s a lot of things.

Furthermore, some of the hooks are still undocumented to this day in the Codex. In some cases, the best way is to identify the method that you want to hook into and then check it out in the source code. Additionally, you might learn some interesting things about the hooks once you dive into where they are called from.

Example 1: The save_post Action

The save_post action is triggered by wp_insert_post and wp_publish_post. Both methods are defined in wp-includes/post.php. If we dig into the source code, we’ll first find this definition of save_post:

/**
 * Fires once a post has been saved.
 *
 * @since 1.5.0
 *
 * @param int $post_ID Post ID.
 * @param WP_Post $post Post object.
 * @param bool $update Whether this is an existing post being updated or not.
 */
do_action( 'save_post', $post_ID, $post, $update );

What’s interesting here is that directly above it we can also see this:

/**
 * Fires once a post has been saved.
 *
 * The dynamic portion of the hook name, `$post->post_type`, refers to
 * the post type slug.
 *
 * @since 3.7.0
 *
 * @param int $post_ID Post ID.
 * @param WP_Post $post Post object.
 * @param bool $update Whether this is an existing post being updated or not.
 */
do_action( "save_post_{$post->post_type}", $post_ID, $post, $update );

That’s neat! We can actually target save_post for our own specific post type. This saves a few lines of doing a check like this:

if ( 'my_custom_post_type' !== $post->post_type ) {
    return;
}

Another important note when it comes to hooks is not to hook something that might bite you later. For example, save_post is a great action to use when you want to do something after a post saves. For instance, you might want to record a new post entry for your publish_log custom post type that tracks when posts are published. Let’s take a look at an example:

function maybe_create_publish_log( $post_id, $post ) {
    if ( 'publish' !== $post->post_status ) {
        return;
    }

    wp_insert_post( [
        'post_type' => 'publish_log',
        'post_author' => $post->post_author,
        'post_status' => 'publish',
        'post_content' => "New post {$post->post_title} published on {$post->post_date}.",
        // etc...
    ] );
}

add_action( 'save_post', 'maybe_create_publish_log', 10, 2 );

At first glance, this seems fine. But remember earlier when we learned that save_post is called by wp_insert_post? With this code, you might find yourself creating tons of  publish_log posts because your hook to save_post is being called over and over by wp_insert_post. So, how do you get around this?

The answer is the aptly named remove_action (if you guessed that its sister function is remove_filter and that remove_action simply calls remove_filter, you get a cookie). Let’s take a look at our code now:

function maybe_create_publish_log( $post_id, $post ) {
    if ( 'publish' !== $post->post_status ) {
        return;
    }

    remove_action( 'save_post', 'maybe_create_publish_log' );
    wp_insert_post( [
       'post_type' => 'publish_log',
       'post_author' => $post->post_author,
       'post_status' => 'publish',
       'post_content' => "New post {$post->post_title} published on {$post->post_date}.",
        // etc...
    ] );
    add_action( 'save_post', 'maybe_create_publish_log', 10, 2 );
}

add_action( 'save_post', 'maybe_create_publish_log', 10, 2 );

This is one of the benefits to diving into the core files: if you look up where your action is called from, you will know if you’re about to get into a publishing loop, or avoid other possible “gotchas” when developing your plugins and themes.

Example 2: Modifying the Edit User Screen

Recently at WebDevStudios, we’ve had a couple of clients that needed specific sections added to the user profile page. You may be looking to integrate a service, such as Medium, to your user accounts, or you may want to give administrators the ability to modify fields specific to a plugin. But where do you start?

If you look in the action reference, well, you might be looking for a long time. You’d eventually find what you’re looking for, but there is an easier way.

First, on a WordPress install, you’ll notice you’re at this page when editing a User: /wp-admin/user-edit.php?user_id=3. If you’re editing your own user, you’ll find that you’re at /wp-admin/profile.php. You might be thinking, “Oh geez, I have to dig into two files to find the action I want?!”

But fear not, because upon opening profile.php you’ll see it’s actually rather simple:

<?php
/**
 * User Profile Administration Screen.
 *
 * @package WordPress
 * @subpackage Administration
 */

/**
 * This is a profile page.
 *
 * @since 2.5.0
 * @var bool
 */
define('IS_PROFILE_PAGE', true);

/** Load User Editing Page */
require_once( dirname( __FILE__ ) . '/user-edit.php' );

Well, that saves us some time. Now, if you dig into user-edit.php, you’re going to be looking for calls to do_action. Let’s do a quick check with ag – the silver searcher:

  ag do_action wp-admin/user-edit.php

Which gives us the following output:

132: do_action( 'personal_options_update', $user_id );
141: do_action( 'edit_user_profile_update', $user_id );
230: do_action( 'user_edit_form_tag' );
285: do_action( 'admin_color_scheme_picker', $user_id );
347:do_action( 'personal_options', $profileuser );
362: do_action( 'profile_personal_options', $profileuser );
658: do_action( 'show_user_profile', $profileuser );
667: do_action( 'edit_user_profile', $profileuser );

Now, let’s dig into the actual file itself. Odds are we want to be looking at edit_user_profile specifically:

if ( IS_PROFILE_PAGE ) {
	/**
	 * Fires after the 'About Yourself' settings table on the 'Your Profile' editing screen.
	 *
	 * The action only fires if the current user is editing their own profile.
	 *
	 * @since 2.0.0
	 *
	 * @param WP_User $profileuser The current WP_User object.
	 */
	do_action( 'show_user_profile', $profileuser );
} else {
	/**
	 * Fires after the 'About the User' settings table on the 'Edit User' screen.
	 *
	 * @since 2.0.0
	 *
	 * @param WP_User $profileuser The current WP_User object.
	 */
	do_action( 'edit_user_profile', $profileuser );
}

You’ll notice that I copied out the surrounding if conditional. As well, you might notice something familiar on the first line: the if ( IS_PROFILE_PAGE ) check lets you hook in just on your own user page, or only on other users’ pages, or both by a combination of both actions.

With these actions, we can render a custom set of fields to modify the user edit page and bring custom functionality right into the core of WordPress. While the Codex’s action list is quite extensive and sometimes difficult to navigate, it is a wonderful resource for finding additional information on most actions and filters once you know what to look for. Have a peek at the page for edit_user_profile, for example.

Example 3: Modifying Query SQL with Filters

This is a slightly more advanced example, but an important one. WordPress does a lot of things under the hood to construct the MySQL queries that ultimately find your posts, tags, etc. Let’s start with an example WP Query from get_posts:

$args = [
    'post_type'      => 'post',
    'posts_per_page' => 5,
    'orderby'        => 'post_date',
    'order'          => 'ASC',
    's'              => 'Test',
];

$posts = get_posts( $args );

The resulting SQL looks something like this:

SELECT
    wp_posts.ID
FROM
    wp_posts
WHERE 1=1
AND (((wp_posts.post_title LIKE '%Test%') OR (wp_posts.post_excerpt LIKE '%Test%') OR (wp_posts.post_content LIKE '%Test%')))
AND (wp_posts.post_password = '')
AND wp_posts.post_type = 'post'
AND ((wp_posts.post_status = 'publish'))
ORDER BY wp_posts.post_date ASC
LIMIT 0, 5

This query, although simple, is filtered several times before it is passed to the database for record retrieval. A quick aside—the “%” signs may be encoded as long hashes when you view the query, as a placeholder to help with how $wpdb parses placeholders.

Next, we’ll step through some of the more useful filters used. The following code can be found in wp-includes/class-wp-query.php. 

posts_where

This is one of the earliest filters on the query, and filters the WHERE clause of the query. For the above example, this filter’s parameters are the WHERE clause as the first parameter, and a reference to the query object as the second. The WHERE clause looks like this:

    [0] =>  AND (((wp_posts.post_title LIKE '{67feda5925d0533a58f19e45c96ff1c761ddaa2263949b4ae0023a90b3f25b1f}Test{67feda5925d0533a58f19e45c96ff1c761ddaa2263949b4ae0023a90b3f25b1f}') OR (wp_posts.post_excerpt LIKE '{67feda5925d0533a58f19e45c96ff1c761ddaa2263949b4ae0023a90b3f25b1f}Test{67feda5925d0533a58f19e45c96ff1c761ddaa2263949b4ae0023a90b3f25b1f}') OR (wp_posts.post_content LIKE '{67feda5925d0533a58f19e45c96ff1c761ddaa2263949b4ae0023a90b3f25b1f}Test{67feda5925d0533a58f19e45c96ff1c761ddaa2263949b4ae0023a90b3f25b1f}')))  AND (wp_posts.post_password = '') 

Two notes about the above: first, you can see the expanded version of the placeholder for the “%” symbol. Second, the query clause starts with an AND. You may have noticed in the original query that this clause starts with WHERE 1=1. This is a simple trick to allow adding more conditions to the WHERE clause. If we wanted to add an extra field to check against when someone searches, say from another table, we could do something like this:

add_filter( 'posts_where', function( $where, $query ) {
    if ( 'post' !== $query->get( 'post_type' ) {
        return $where;
    }

    if ( ! $query->get( 's' ) ) {
        return $where;
    }

    $search = $query->get( 's' );
    $where .= " AND mycustomtable.ad_keywords LIKE '%{$search}%'";
    return $where;
}, 10, 2 );

This would allow us to search across our custom table for rows with a matching search in the ad_keywords column. If you’re familiar with SQL, you’re probably wondering how we’re querying the mycustomtable table without a JOIN. Well, right below the call to filter posts_where is our next guest…

posts_join

The posts_join filter allows us to write JOIN clauses to other tables we might need in our query. Currently, our query doesn’t join to any other tables since we aren’t doing a taxonomy query or meta query. However, if we want to JOIN our custom table, it’s pretty straight forward.

add_filter( 'posts_join', function( $joins, $query ) {
    if ( 'post' !== $query->get( 'post_type' ) {
        return $joins;
    }

    if ( ! $query->get( 's' ) ) {
        return $joins;
    }

    $joins .= 'JOIN mycustomtable ON( wp_posts.ID = mycustomtable.post_id )';
    return $joins;
}, 10, 2 );

Other Filters

While the above two filters make up the bulk of useful filters for most cases, the following may also be relevant depending on your use-case:

• posts_where_paged and posts_join_paged – Similar to the above two filters, but used expressly when pagination is concerned
• posts_orerby – Direct access to the ORDER BY clause, responsible for the order in which your posts appear when queried
• post_limits – The query’s LIMIT clause
• posts_fields – Determines which fields are returned from the database (note that WordPress does a lot of this for you when it gets the actual post objects, typically you wouldn’t need to modify this outside of very specific use-cases)
• posts_clauses – This is kind of a catchall for various parts of the query, including WHERE, GROUP BY, JOIN, ORDER BY, DISTINCT, selected fields, and LIMIT.

Conclusion

With the above, I hope you have a better understanding of how and where WordPress filters certain things, and I hope you go off and explore the codebase the next time you say, “Geez, I really wish I could modify that!” WordPress has plenty of actions for developers to tap into once you know where to look. Happy coding!

The post Debugging WordPress Core: Actions and Filters appeared first on WebDevStudios.

An Example — LEGO^®

Most people have at least heard of, if not directly experienced, LEGO^® toy bricks. With these toys, you can follow instructions in a set and build your own toys to play with. You can also creatively build something entirely new using your own imagination. Or you can combine the two approaches and customize a pre-designed set with your own modifications. All of this is made possible by the way that individual LEGO^® pieces fit together: the bumps on the top and the gaps on the bottom, as well as a few other types of connections.

In our analogy, the bumps and gaps in the LEGO^® bricks work the same way as Hooks in WordPress. You can add new functionality, remove default functionality, or just modify the current piece of data. Getting a firm understanding of this process will help you start to unlock the real power of WordPress.

Types of Hooks

There are two types of Hooks in WordPress: Actions and Filters. They work almost the same way, but it’s important to understand how they are different. Actions intend for you to simply do something, while filters intend for you to change something. Also, actions may provide variables to your code to give you more context, while filters will always provide at least one variable: the data you’re modifying.

Actions

Actions are used to insert your own code into a specific point of the WordPress core execution. Actions in WordPress look like this:

    /**
     * Print scripts or data in the head tag on the front end.
     *
     * @since 1.5.0
     */
    do_action( 'wp_head' );

The function do_action() is used to trigger an action. In the example above, “wp_head” is the name of the action. If you want to hook into this action, you’ll need to know the name of the action so that WordPress runs your code in the correct place.

Filters

Just like actions, filters are used to insert your own code into a specific point of the WordPress core execution. What makes them different from actions is that filters always provide data to your code, and they always expect your code to provide data back again. Filters in WordPress typically look like this:

    /**
     * Filter the list of CSS body classes for the current post or page.
     *
     * @since 2.8.0
     *
     * @param array  $classes An array of body classes.
     * @param string $class   A comma-separated list of additional classes added to the body.
     */
    $classes = apply_filters( 'body_class', $classes, $class );

The function apply_filters() is used to trigger a filter. In the example above, “body_class” is the name of the filter, and there are two variables passed in for context: $classes and $class. The result of the filter is assigned to the $classes variable. This is essentially how the filter works: A piece of data is passed through the filter and the filtered version is used by WordPress. In this case, the piece of data is the variable $classes.

Using Hooks

Adding your own functionality to the WordPress hooks is very straightforward. You’ll need the add_action() function for actions, and the add_filter() function for filters. Let’s get into some practical examples using the two hooks we mentioned before: “wp_head” and “body_class”. In each of the cases below, we’ll give a code example, and then explain what’s happening in that example.

Actions

/**
 * Add our own output to the HTML <head> element.
 */
function jpry_wp_head_action() {
    echo '<!-- This comment will show up inside the HTML <head> element! -->';
}
add_action( 'wp_head', 'jpry_wp_head_action', 10, 0 );

In the code above, you can see that we’re calling the add_action() function with four parameters. The parameters are:

1. 'wp_head' — This is the name of the hook that we want to tie into.
2. 'jpry_wp_head_action' — This is the name of our function that WordPress should execute. In my example, you can see that it corresponds to a function name.
3. 10 — This is the priority level of our function.
4. 0 — This is the number of arguments (parameters) that our function (jpry_wp_head_action()) expects to receive.

In this example, I’m simply adding an HTML comment to the <head> block. When you view the source of the site, you will be able to see this comment within the <head> block after the code is added.

While I’ve included all of the available parameters in this example, it’s important to note that the last two parameters are optional. You should only include them if you want to override the default value that WordPress uses. I will explain this in more detail in the Optional Parameters section below.

Filters

/**
 * Add the "jpry" class to the HTML <body> element.
 *
 * @param array $classes The array of body classes.
 * @return array The modified array of classes.
 */
function jpry_body_class_filter( $classes ) {
    $classes[] = 'jpry';

    return $classes;
}
add_filter( 'body_class', 'jpry_body_class_filter', 10, 1 );

Just like the add_action() function, we call the add_filter() function with 4 parameters:

1. 'body_class' — This is the name of the hook that we want to tie into.
2. 'jpry_body_class_filter' — This is the name of our function that WordPress should execute. Just like above, it corresponds to the function name that I created just above it.
3. 10 — The priority level.
4. 1 — The number of arguments that our function (jpry_body_class_filter()) expects to receive.

As I mentioned before about filters, they always expect to pass you data, and they always expect you to return data when you’re done. In the above example, you can see that my function jpry_body_class_filter() accepts a single parameter, named $classes. I know from looking at the documentation of this filter that $classes is an array of class names. I’m adding my own class and so I simply append my own data to the existing array. In order for this to work, it’s absolutely crucial to return the $classes variable back to the filter.

Not returning data back to a filter is a common cause of obscure bugs and support requests. Without the return statement, not only will your filter not add your data, but it will also cause the existing data to be empty! If you’re using a filter and you don’t seem to be getting any data back when you’re done, or if you’re seeing some strange bug somewhere that is hard to figure out, double-check to make sure you’ve included that return statement.

Optional Parameters

I previously mentioned that there are two optional parameters with each of these functions: priority and number of arguments.

The priority parameter does exactly what it says: it prioritizes your function with everything else that has been added to that same hook. WordPress executes functions in lowest-to-highest priority. When multiple functions have been added at the same priority level, then they are executed in the order that they were added.

The number of arguments parameter ensures that your function receives the correct number of parameters when it is called. This is relevant when you’re using an action or filter that passes more than one value. If we look at the body_class filter definition above, we can see that there are two pieces of data available to us: $classes and $class. While we don’t need both pieces of data for our specific use, there may be other developers who do need the extra data. In order to have the second variable passed to their function so that they can use it, they would set the number of arguments to 2 instead of 1.

Resources

Hooks are an integral part of how WordPress functions, and so there are plenty of resources available to help you utilize them:

• WordPress Hook Reference
• WordPress Codex: Plugin API
• Adam Brown’s Hook Database

Do you have any questions or comments? Did you find an error, or think I missed something? Leave a comment below!

The post Getting Started with WordPress Hooks appeared first on WebDevStudios.