Skip to main content

Hooks & Filters

Customize ThemeRuby Multi Authors behavior using WordPress hooks and filters.

Action Hooks​

tmauthors_assigned​

Fires after authors are successfully assigned to a post.

Usage​

do_action( 'tmauthors_assigned', int $post_id, array $author_ids );

Parameters​

ParameterTypeDescription
$post_idintThe post ID
$author_idsarrayArray of assigned user IDs

Example​

add_action( 'tmauthors_assigned', 'notify_authors', 10, 2 );

function notify_authors( $post_id, $author_ids ) {
    $post = get_post( $post_id );

    foreach ( $author_ids as $author_id ) {
        $user = get_user_by( 'id', $author_id );

        // Send email notification
        wp_mail(
            $user->user_email,
            'You\'ve been added as an author',
            'You were added as an author to: ' . $post->post_title
        );
    }
}

tmauthors_before_authors_display​

Fires before authors are displayed in the frontend.

Usage​

do_action( 'tmauthors_before_authors_display', int $post_id );

Example​

add_action( 'tmauthors_before_authors_display', 'add_author_label' );

function add_author_label( $post_id ) {
    echo '<span class="author-label">Article by:</span>';
}

tmauthors_after_authors_display​

Fires after authors are displayed in the frontend.

Usage​

do_action( 'tmauthors_after_authors_display', int $post_id );

Example​

add_action( 'tmauthors_after_authors_display', 'add_share_buttons' );

function add_share_buttons( $post_id ) {
    echo '<div class="share-authors">Share this article</div>';
}

tmauthors_clear_cache​

Fires when plugin cache should be cleared.

Usage​

do_action( 'tmauthors_clear_cache' );

Example​

// Trigger cache clear
do_action( 'tmauthors_clear_cache' );

// Hook into cache clear
add_action( 'tmauthors_clear_cache', 'my_custom_cache_clear' );

function my_custom_cache_clear() {
    // Clear your custom cache
    delete_transient( 'my_custom_author_data' );
}

Filter Hooks​

tmauthors_post_authors​

Filter the array of post authors before returning.

Usage​

apply_filters( 'tmauthors_post_authors', array $authors, int $post_id );

Parameters​

ParameterTypeDescription
$authorsarrayArray of WP_User objects
$post_idintThe post ID

Example​

Sort authors by name:

add_filter( 'tmauthors_post_authors', 'sort_authors_by_name', 10, 2 );

function sort_authors_by_name( $authors, $post_id ) {
    usort( $authors, function( $a, $b ) {
        return strcmp( $a->display_name, $b->display_name );
    } );

    return $authors;
}

Exclude certain authors:

add_filter( 'tmauthors_post_authors', 'exclude_guest_authors', 10, 2 );

function exclude_guest_authors( $authors, $post_id ) {
    return array_filter( $authors, function( $author ) {
        // Exclude users with 'guest' role
        return ! in_array( 'guest', $author->roles );
    } );
}

tmauthors_display​

Filter the HTML output for a single author.

Usage​

apply_filters( 'tmauthors_display', string $output, WP_User $author, int $post_id );

Parameters​

ParameterTypeDescription
$outputstringThe default HTML output
$authorWP_UserThe author user object
$post_idintThe post ID

Example​

add_filter( 'tmauthors_display', 'add_author_role', 10, 3 );

function add_author_role( $output, $author, $post_id ) {
    $role = $author->roles[0];
    return $output . ' <span class="author-role">(' . ucfirst( $role ) . ')</span>';
}

tmauthors_separator​

Filter the separator between authors.

Usage​

apply_filters( 'tmauthors_separator', string $separator, int $post_id );

Example​

add_filter( 'tmauthors_separator', 'custom_separator' );

function custom_separator( $separator ) {
    return ' | ';
}

tmauthors_box_html​

Filter the complete author box HTML.

Usage​

apply_filters( 'tmauthors_box_html', string $html, int $post_id );

Example​

add_filter( 'tmauthors_box_html', 'custom_author_box', 10, 2 );

function custom_author_box( $html, $post_id ) {
    $authors = tmauthors_get_post_authors( $post_id );

    $custom_html = '<div class="my-author-box">';
    $custom_html .= '<h3>Written by</h3>';

    foreach ( $authors as $author ) {
        $custom_html .= '<div class="author">';
        $custom_html .= get_avatar( $author->ID, 50 );
        $custom_html .= '<strong>' . $author->display_name . '</strong>';
        $custom_html .= '</div>';
    }

    $custom_html .= '</div>';

    return $custom_html;
}

tmauthors_show_author_box​

Filter whether to show the author box.

Usage​

apply_filters( 'tmauthors_show_author_box', bool $show, int $post_id );

Example​

Hide on specific post types:

add_filter( 'tmauthors_show_author_box', 'hide_on_pages', 10, 2 );

function hide_on_pages( $show, $post_id ) {
    if ( get_post_type( $post_id ) === 'page' ) {
        return false;
    }
    return $show;
}

Show only for multiple authors:

add_filter( 'tmauthors_show_author_box', 'show_for_multiple_only', 10, 2 );

function show_for_multiple_only( $show, $post_id ) {
    return tmauthors_has_multiple_authors( $post_id );
}

tmauthors_assignable_roles​

Filter which user roles can be assigned as authors.

Usage​

apply_filters( 'tmauthors_assignable_roles', array $roles );

Example​

Add subscriber role:

add_filter( 'tmauthors_assignable_roles', 'add_subscriber_role' );

function add_subscriber_role( $roles ) {
    $roles[] = 'subscriber';
    return $roles;
}

Limit to specific roles:

add_filter( 'tmauthors_assignable_roles', 'limit_to_editors' );

function limit_to_editors( $roles ) {
    return array( 'administrator', 'editor' );
}

tmauthors_assignable_users​

Filter the list of assignable users.

Usage​

apply_filters( 'tmauthors_assignable_users', array $users, int $post_id );

Parameters​

ParameterTypeDescription
$usersarrayArray of WP_User objects
$post_idintCurrent post ID

Example​

Only show users from specific department:

add_filter( 'tmauthors_assignable_users', 'filter_by_department', 10, 2 );

function filter_by_department( $users, $post_id ) {
    return array_filter( $users, function( $user ) {
        $dept = get_user_meta( $user->ID, 'department', true );
        return $dept === 'editorial';
    } );
}

tmauthors_user_can_assign_authors​

Filter whether current user can assign authors.

Usage​

apply_filters( 'tmauthors_user_can_assign_authors', bool $can_assign, int $user_id, int $post_id );

Example​

Allow authors to assign others:

add_filter( 'tmauthors_user_can_assign_authors', 'authors_can_assign', 10, 3 );

function authors_can_assign( $can_assign, $user_id, $post_id ) {
    $user = get_user_by( 'id', $user_id );

    if ( in_array( 'author', $user->roles ) ) {
        return true;
    }

    return $can_assign;
}

tmauthors_validate_author_assignment​

Validate author assignment before saving.

Usage​

apply_filters( 'tmauthors_validate_author_assignment', bool|WP_Error $valid, int $post_id, array $author_ids );

Example​

Limit maximum authors:

add_filter( 'tmauthors_validate_author_assignment', 'limit_max_authors', 10, 3 );

function limit_max_authors( $valid, $post_id, $author_ids ) {
    if ( count( $author_ids ) > 5 ) {
        return new WP_Error(
            'too_many_authors',
            'Maximum 5 authors allowed per post.'
        );
    }

    return $valid;
}

Require minimum authors for certain categories:

add_filter( 'tmauthors_validate_author_assignment', 'require_multiple', 10, 3 );

function require_multiple( $valid, $post_id, $author_ids ) {
    if ( has_category( 'collaborative', $post_id ) && count( $author_ids ) < 2 ) {
        return new WP_Error(
            'insufficient_authors',
            'Collaborative posts must have at least 2 authors.'
        );
    }

    return $valid;
}

tmauthors_get_author_posts_url​

Filter the author archive URL.

Usage​

apply_filters( 'tmauthors_get_author_posts_url', string $url, int $user_id );

Example​

Custom author URL structure:

add_filter( 'tmauthors_get_author_posts_url', 'custom_author_url', 10, 2 );

function custom_author_url( $url, $user_id ) {
    $user = get_user_by( 'id', $user_id );
    return home_url( '/writers/' . $user->user_nicename . '/' );
}

Query Modification Filters​

tmauthors_pre_get_posts​

Modify author query before execution.

Usage​

apply_filters( 'tmauthors_pre_get_posts', WP_Query $query );

Example​

add_action( 'pre_get_posts', 'modify_author_query' );

function modify_author_query( $query ) {
    if ( ! $query->is_main_query() || ! $query->is_author() ) {
        return;
    }

    // Exclude certain categories from author archives
    $query->set( 'category__not_in', array( 5, 10 ) );
}

Complete Examples​

Notify Authors on Assignment​

add_action( 'tmauthors_assigned', 'send_author_notifications', 10, 2 );

function send_author_notifications( $post_id, $author_ids ) {
    $post = get_post( $post_id );
    $permalink = get_permalink( $post_id );

    foreach ( $author_ids as $author_id ) {
        $user = get_user_by( 'id', $author_id );

        $subject = sprintf(
            'You\'ve been added as an author to: %s',
            $post->post_title
        );

        $message = sprintf(
            "Hello %s,\n\nYou have been added as an author to the post:\n\n%s\n\nView post: %s\n\nThanks!",
            $user->display_name,
            $post->post_title,
            $permalink
        );

        wp_mail( $user->user_email, $subject, $message );
    }
}

Custom Author Display with Roles​

add_filter( 'tmauthors_display', 'show_author_with_role', 10, 3 );

function show_author_with_role( $output, $author, $post_id ) {
    $role_names = array(
        'administrator' => 'Admin',
        'editor'        => 'Editor',
        'author'        => 'Writer',
    );

    $user_role = $author->roles[0];
    $role_label = isset( $role_names[ $user_role ] ) ? $role_names[ $user_role ] : ucfirst( $user_role );

    return $output . ' <span class="author-role">(' . $role_label . ')</span>';
}

Department-Based Author Filtering​

add_filter( 'tmauthors_assignable_users', 'filter_by_post_category', 10, 2 );

function filter_by_post_category( $users, $post_id ) {
    // Only show tech writers for tech posts
    if ( has_category( 'technology', $post_id ) ) {
        return array_filter( $users, function( $user ) {
            return get_user_meta( $user->ID, 'department', true ) === 'tech';
        } );
    }

    return $users;
}

Log Author Changes​

add_action( 'tmauthors_assigned', 'log_author_changes', 10, 2 );

function log_author_changes( $post_id, $author_ids ) {
    $log_entry = array(
        'post_id'    => $post_id,
        'authors'    => $author_ids,
        'changed_by' => get_current_user_id(),
        'timestamp'  => current_time( 'mysql' ),
    );

    // Save to custom log
    $log = get_option( 'tmauthors_change_log', array() );
    $log[] = $log_entry;
    update_option( 'tmauthors_change_log', $log );
}

Filter Priority Guide​

Use priorities to control filter execution order:

// Run first (before default)
add_filter( 'tmauthors_post_authors', 'my_filter', 5, 2 );

// Default priority
add_filter( 'tmauthors_post_authors', 'my_filter', 10, 2 );

// Run last (after default)
add_filter( 'tmauthors_post_authors', 'my_filter', 20, 2 );

Removing Filters​

// Remove specific filter
remove_filter( 'tmauthors_post_authors', 'function_name', 10 );

// Remove all filters
remove_all_filters( 'tmauthors_post_authors' );

Next Steps​