Filter Hooks

timber/meta/transform_value #

Filters whether to transform a meta value.

If the filter returns true, all meta value will be transformed to Timber/standard PHP objects if possible.

since 2.0.0

PHP

// Transforms all meta value.
add_filter( 'timber/meta/transform_value', '__return_true' );

timber/{$object_type}/pre_meta #

Filters object meta data before it is fetched from the database.

since 2.0.0

PHP

// Disable fetching meta values.
add_filter( 'timber/post/pre_meta', '__return_false' );

// Add your own meta data.
add_filter( 'timber/post/pre_meta', function( $post_meta, $post_id, $post ) {
    $post_meta = array_merge( $post_meta, [
        'custom_data_1' => 73,
        'custom_data_2' => 274,
    ] );

    return $post_meta;
}, 10, 3 );

timber_{$object_type}_get_meta_field_pre #

Filters the value for a post meta field before it is fetched from the database.

DEPRECATED since 2.0.0, use timber/{object_type}/pre_meta

timber/{$object_type}/meta #

Filters the value for a post meta field.

This filter is used by the ACF Integration.

see Timber\Post::meta()

since 2.0.0

PHP

add_filter( 'timber/post/meta', function( $post_meta, $post_id, $field_name, $post ) {
    if ( 'event' === $post->post_type ) {
        // Do something special.
        $post_meta['foo'] = $post_meta['foo'] . ' bar';
    }

    return $post_meta;
}, 10, 4 );

timber/term/meta/field #

Filters the value for a term meta field.

DEPRECATED since 2.0.0, use timber/term/meta

timber_{$object_type}_get_meta_field #

Filters the value for an object meta field.

DEPRECATED since 2.0.0, use timber/{object_type}/meta

timber_{$object_type}_get_meta #

Filters object meta data fetched from the database.

DEPRECATED since 2.0.0, use timber/{object_type}/meta

timber/comment/class #

Filters the comment class based on your custom criteria.

Maybe you want to set a custom class based upon the comment type? This allows you to filter the PHP class, utilizing data from the WP_Comment object.

since 2.0.0

add_filter( 'timber/comment/class', function( $class, $comment ) {
    if ( $comment->comment_type === 'pingback' ) {
        return PingBackComment::class;
    }
    return $class;
}, 10, 2 );

timber/menu/classmap #

Filters the class(es) used for different menus.

Read more about this in the documentation for Menu Class Maps.

The default Menu Class Map will contain class names for locations that map to Timber\Menu.

since 2.0.0

add_filter( 'timber/menu/classmap', function( $classmap ) {
    $custom_classmap = [
        'primary'   => MenuPrimary::class,
        'secondary' => MenuSecondary::class,
    ];

    return array_merge( $classmap, $custom_classmap );
} );

timber/menu/class #

Filters the menu class based on your custom criterias.

Maybe the location is not appropriate in some cases. This filter will allow you to filter the class on whatever data is available.

since 2.0.0

add_filter( 'timber/menu/class', function( $class, $term, $args ) {
    if ( $args['depth'] === 1 ) {
        return SingleLevelMenu::class;
    }

    return MultiLevelMenu::class;
}, 10, 3 );

timber/menuitem/classmap #

Filters the class(es) used for different menu items.

Read more about this in the documentation for Menu Item Class Maps.

The default Menu Item Class Map will contain class names for locations that map to Timber\MenuItem.

since 2.0.0

add_filter( 'timber/menuitem/classmap', function( $classmap ) {
    $custom_classmap = [
        'primary'   => MenuItemFooter::class,
        'secondary' => MenuItemHeader::class,
    ];

    return array_merge( $classmap, $custom_classmap );
} );

timber/menuitem/class #

Filters the menu item class

since 2.0.0

add_filter( 'timber/menuitem/class', function( $class, $item, $menu ) {
    if ( $item->post_parent ) {
        return SubMenuItem::class;
    }

    return MenuItem::class;
}, 10, 3 );

timber/pages_menu/class #

Filters the class used for different menus.

Read more about this in the documentation for Pages Menu Class filter.

since 2.0.0

add_filter( 'timber/pages_menu/class', function( $class ) {
    return ExtendedPagesMenu::class;
} );

timber/post/classmap #

Filters the class(es) used for different post types.

Read more about this in the documentation for Post Class Maps.

The default Post Class Map will contain class names for posts, pages that map to Timber\Post and a callback that will map attachments to Timber\Attachment and attachments that are images to Timber\Image.

Make sure to merge in your additional classes instead of overwriting the whole Class Map.

since 2.0.0

use Book;
use Page;

add_filter( 'timber/post/classmap', function( $classmap ) {
    $custom_classmap = [
        'page' => Page::class,
        'book' => Book::class,
    ];

    return array_merge( $classmap, $custom_classmap );
} );

timber/post/class #

Filters the post class based on your custom criteria.

Maybe you want to set a custom class based upon how blocks are used? This allows you to filter the PHP class, utilizing data from the WP_Post object.

since 2.0.0

add_filter( 'timber/post/class', function( $class, $post ) {
    if ( has_blocks($post) ) {
        return GutenbergPost::class;
    }

    return $class;
}, 10, 2 );

timber/term/class #

Filters the term class based on your custom criteria.

Maybe you want to set a custom class based upon a certain category? This allows you to filter the PHP class, utilizing data from the WP_Term object.

since 2.0.0

add_filter( 'timber/term/class', function( $class, $term ) {
    if ( get_term_meta($term->term_id, 'is_special_category', true) ) {
        return MyCustomTermClass::class;
    }

    return $class;
}, 10, 2 );

timber/user/class #

Filters the name of the PHP class used to instantiate Timber\User objects.

The User Class Map receives the default Timber\User class and a WP_User object. You should be able to decide which class to use based on that user object.

since 2.0.0

PHP

use Administrator;
use Editor;

add_filter( 'timber/user/class', function( $class, \WP_User $user ) {
    if ( in_array( 'editor', $user->roles, true ) ) {
        return Editor::class;
    } elseif ( in_array( 'author', $user->roles, true ) ) {
        return Author::class;
    }

    return $class;
}, 10, 2 );

timber/transient/slug #

Filters the transient slug.

This might be useful if you are using a multilingual solution.

since 0.22.6

timber/transient/force_transients #

Filters …

since 2.0.0

timber_force_transients #

Filters …

DEPRECATED since 2.0.0, use timber/transient/force_transients

timber/transient/force_transient_{$slug} #

Filters …

Here is a description about the filter. $slug The transient slug.

since 2.0.0

timber_force_transient_{$slug} #

Filters …

DEPRECATED since 2.0.0, use timber/transient/force_transient_{$slug}

timber/helper/wp_title_separator #

Filters the separator used for the page title.

since 2.0.0

timber_wp_title_seperator #

Filters the separator used for the page title.

DEPRECATED since 2.0.0, use timber/helper/wp_title_separator

timber/image/src #

Filters the src URL for a Timber\Image.

see Timber\Image::src()

since 0.21.7

timber_image_src #

Filters the src URL for a Timber\Image.

DEPRECATED since 2.0.0, use timber/image/src

timber/sideload_image/subdir #

Filters to directory that should be used for sideloaded images.

since 2.0.0

PHP

// Change the subdirectory used for sideloaded images.
add_filter( 'timber/sideload_image/subdir', function( $subdir ) {
    return 'sideloaded';
} );

// Disable subdirectory used for sideloaded images.
add_filter( 'timber/sideload_image/subdir', '__return_false' );

timber/image/new_url #

Filters the URL for the resized version of a Timber\Image.

You’ll probably need to use this in combination with timber/image/new_path.

since 1.0.0

timber/image/new_path #

Filters the destination path for the resized version of a Timber\Image.

A possible use case for this would be to store all images generated by Timber in a separate directory. You’ll probably need to use this in combination with timber/image/new_url.

since 1.0.0

timber/cache/mode #

Filters the cache mode.

You can read more about Caching in the [Performance/Caching]({{<relref "performance.md" >}}) guide.

since 0.20.10

timber_cache_mode #

Filters the cache mode.

DEPRECATED since 2.0.0, use timber/cache/mode

timber/loader/render_data #

Filters …

since 0.20.10

timber_loader_render_data #

Filters …

DEPRECATED since 2.0.0, use timber/loader/render_data

timber/output #

Filters …

since 0.20.10

timber_output #

Filters …

DEPRECATED since 2.0.0, use timber/output

timber/loader/paths #

Filters the template paths used by the Loader.

DEPRECATED since 2.0.0, use timber/locations

since 0.20.10

timber/loader/loader #

Filters …

link https://github.com/timber/timber/pull/1254

since 1.1.11

timber/twig/environment/options #

Filters the environment options that are used when creating a Twig Environment instance.

By default, Timber sets the following values:

• 'debug' => WP_DEBUG
• 'autoescape' => false
• 'cache' => false

link https://twig.symfony.com/doc/2.x/api.html#environment-options

since 1.9.5

PHP

add_filter( 'timber/twig/environment/options', 'update_twig_environment_options' );

/**
 * Updates Twig environment options.
 *
 * @link https://twig.symfony.com/doc/2.x/api.html#environment-options
 *
 * \@param array $options An array of environment options.
 *
 * @return array
 */
function update_twig_environment_options( $options ) {
    $options['cache']       = true;
    $options['auto_reload'] = true;

    return $options;
}

timber/cache/location #

Filters the cache location used for Twig.

DEPRECATED since 2.0.0

Allows you to set a new cache location for Twig. If the folder doesn’t exist yet, it will be created automatically.

since 0.20.10

timber/cache/enable_extension #

Filters the cache extension activation.

Allows users to disable the cache extension and use their own

since 2.0.0

timber/loader/twig #

Filters …

since 0.20.10

timber/twig #

Filters the Twig environment used in the global context.

You can use this filter if you want to add additional functionality to Twig, like global variables, filters or functions.

since 0.21.9

PHP

/**
 * Adds Twig functionality.
 *
 * \@param \Twig\Environment $twig The Twig Environment to which you can add additional functionality.
 */
add_filter( 'timber/twig', function( $twig ) {
    // Make get_theme_file_uri() usable as {{ theme_file() }} in Twig.
    $twig->addFunction( new Twig\TwigFunction( 'theme_file', 'get_theme_file_uri' ) );

    return $twig;
} );

Twig

<a class="navbar-brand" href="{{ site.url }}">
    <img src="{{ theme_file( 'build/img/logo-example.svg' ) }}" alt="Logo {{ site.title }}">
</a>

timber/cache/extension/lifetime #

Filters the Twig environment used in the global context.

DEPRECATED since 2.0.0

timber/locations #

Filters …

since 0.20.10

timber_locations #

Filters …

DEPRECATED since 2.0.0, use timber/locations

timber/menu/item_objects #

Filters the sorted list of menu item objects before creating the Menu object.

since 2.0.0

add_filter( 'timber/menu/item_objects', function ( $items ) {
    return array_map(function ($item) {
        if ( is_object( $item ) && ! ( $item instanceof \WP_Post ) ) {
            return new \WP_Post( get_object_vars( $item ) );
        }

        return $item;
    }, $items);
} );

timber/post/import_data #

Filters the imported post data.

Used internally for previews.

see Timber::init()

since 2.0.0

timber/post/meta_object_field #

Filters field object data from Advanced Custom Fields.

This filter is used by the ACF Integration.

see Timber\Post::field_object()

since 1.6.0

timber/post/authors #

Filters authors for a post.

This filter is used by the CoAuthorsPlus integration.

see Timber\Post::authors()

since 1.1.4

timber/post/content/show_password_form_for_protected #

Filters whether the password form should be shown for password protected posts.

This filter runs only when you call {{ post.content }} for a password protected post. When this filter returns true, a password form will be shown instead of the post content. If you want to modify the form itself, you can use the timber/post/content/password_form filter.

since 1.1.4

PHP

// Always show password form for password protected posts.
add_filter( 'timber/post/content/show_password_form_for_protected', '__return_true' );

timber/post/content/password_form #

Filters the password form output.

As an alternative to this filter, you could also use WordPress’s the_password_form filter. The difference to this filter is, that you’ll also have the post object available as a second parameter, in case you need that.

since 1.1.4

PHP

// Modify the password form.
add_filter( 'timber/post/content/password_form', function( $form, $post ) {
    return Timber::compile( 'assets/password-form.twig', array( 'post' => $post ) );
}, 10, 2 );

timber/post/excerpt/defaults #

Filters the default options used for post excerpts.

since 2.0.0

PHP

add_filter( 'timber/post/excerpt/defaults', function( $defaults ) {
    // Only add a read more link if the post content isn’t longer than the excerpt.
    $defaults['always_add_read_more'] = false;

    // Set a default character limit.
    $defaults['words'] = 240;

    return $defaults;
} );

timber/post/excerpt/read_more_class #

Filters the CSS class used for excerpt links.

since 2.0.0

PHP

// Change the CSS class for excerpt links.
add_filter( 'timber/post/excerpt/read_more_class', function( $class ) {
    return 'read-more__link';
} );

timber/post/preview/read_more_class #

Filters the CSS class used for excerpt links.

DEPRECATED since 2.0.0

since 1.0.4

timber/post/excerpt/read_more_link #

Filters the link used for a read more text in an excerpt.

since 2.0.0

timber/post/get_preview/read_more_link #

Filters the link used for a read more text in an excerpt.

DEPRECATED since 2.0.0

since 1.1.3

timber/site/update_option #

Filters a value before it is updated in the site options.

since 2.0.0

timber_site_set_meta #

Filters a value before it is updated in the site options.

DEPRECATED since 2.0.0, use timber/site/update_option

since 0.20.0

timber/term/link #

Filters the link to the term archive page.

see Timber\Term::link()

since 0.21.9

timber_term_link #

Filters the link to the term archive page.

DEPRECATED since 0.21.9, use timber/term/link

timber/term/path #

Filters the relative link (path) to a term archive page.

see Timber\Term::path()

since 0.21.9

timber_term_path #

Filters the relative link (path) to a term archive page.

DEPRECATED since 2.0.0, use timber/term/path

timber_term_set_meta #

Filters term meta value that is going to be updated.

DEPRECATED since 2.0.0 with no replacement

timber/term/meta/set #

Filters term meta value that is going to be updated.

DEPRECATED since 2.0.0, with no replacement

This filter is used by the ACF Integration.

timber/trim_words/allowed_tags #

Filters allowed tags for trim_words() helper.

The trim_words() helper strips all HTML tags from a text it trims, except for a list of allowed tags. Instead of passing the allowed tags every time you use trim_words() (or {{ text|truncate }} in Twig), you can use this filter to set the allowed tags.

see Timber\TextHelper::trim_words()

since 0.21.9

timber/integrations #

Filters the integrations that should be initialized by Timber.

since 2.0.0

timber/context #

Filters the global Timber context.

By using this filter, you can add custom data to the global Timber context, which means that this data will be available on every page that is initialized with Timber::context().

Be aware that data will be cached as soon as you call Timber::context() for the first time. That’s why you should add this filter before you call Timber::context().

see Timber\Timber::context()

since 0.21.7

PHP

add_filter( 'timber/context', function( $context ) {
    // Example: A custom value
    $context['custom_site_value'] = 'Hooray!';

    // Example: Add a menu to the global context.
    $context['menu'] = new \Timber\Menu( 'primary-menu' );

    // Example: Add all ACF options to global context.
    $context['options'] = get_fields( 'options' );

    return $context;
} );

Twig

<h1>{{ custom_site_value|e }}</h1>

{% for item in menu.items %}
    {# Display menu item #}
{% endfor %}

<footer>
    {% if options.footer_text is not empty %}
        {{ options.footer_text|e }}
    {% endif %}
</footer>

timber_context #

Filters the global Timber context.

DEPRECATED since 2.0.0, use timber/context

timber/render/file #

Filters the Twig template that should be rendered.

since 2.0.0

timber_render_file #

Filters the Twig file that should be rendered.

DEPRECATED since 2.0.0, use timber/render/file

timber/compile/file #

Filters the Twig template that should be compiled.

since 2.0.0

timber_compile_file #

Filters the Twig template that should be compiled.

DEPRECATED since 2.0.0

timber/render/data #

Filters the data that should be passed for rendering a Twig template.

since 2.0.0

timber_render_data #

Filters the data that should be passed for rendering a Twig template.

DEPRECATED since 2.0.0

timber/compile/data #

Filters the data that should be passed for compiling a Twig template.

since 2.0.0

timber_compile_data #

Filters the data that should be passed for compiling a Twig template.

DEPRECATED since 2.0.0, use timber/compile/data

timber/compile/result #

Filters the compiled result before it is returned in Timber::compile().

It adds the posibility to filter the output ready for render.

since 2.0.0

timber_compile_result #

Filters the compiled result before it is returned.

DEPRECATED since 2.0.0 use timber/compile/result

see Timber\Timber::fetch()

since 0.16.7

timber/twig/functions #

Filters the functions that are added to Twig.

The $functions array is an associative array with the filter name as a key and an arguments array as the value. In the arguments array, you pass the function to call with a callable entry.

This is an alternative filter that you can use instead of adding your function in the timber/twig filter.

since 2.0.0

PHP

add_filter( 'timber/twig/functions', function( $functions ) {
    // Add your own function.
    $functions['url_to_domain'] = [
        'callable' => 'url_to_domain',
    ];

    // Replace a function.
    $functions['get_image'] = [
        'callable' => 'custom_image_get',
    ];

    // Remove a function.
    unset( $functions['bloginfo'] );

    return $functions;
} );

timber/twig/filters #

Filters the filters that are added to Twig.

The $filters array is an associative array with the filter name as a key and an arguments array as the value. In the arguments array, you pass the function to call with a callable entry.

This is an alternative filter that you can use instead of adding your filter in the timber/twig filter.

since 2.0.0

PHP

add_filter( 'timber/twig/default_filters', function( $filters ) {
    // Add your own filter.
    $filters['price'] = [
        'callable' => 'format_price',
    ];

    // Replace a filter.
    $filters['list'] = [
        'callable' => 'custom_list_filter',
    ];

    // Remove a filter.
    unset( $filters['list'] );

    return $filters;
} );

timber/url_helper/url_to_file_system/path #

Filters the path of a parsed URL.

This filter is used by the WPML integration.

see Timber\URLHelper::url_to_file_system()

since 1.3.2

timber/URLHelper/url_to_file_system/path #

Filters the path of a parsed URL.

DEPRECATED since 2.0.0, use timber/url_helper/url_to_file_system/path

timber/url_helper/file_system_to_url #

Filters the home URL …

This filter is used by the WPML integration.

see Timber\URLHelper::file_system_to_url()

since 1.3.2

timber/URLHelper/file_system_to_url #

Filters the home URL …

DEPRECATED since 2.0.0, use timber/url_helper/file_system_to_url

timber/url_helper/get_content_subdir/home_url #

Filters the home URL that is used to get the path relative to the content directory.

since 1.3.2

timber/URLHelper/get_content_subdir/home_url #

Filters the home URL that is used to get the path relative to the content directory.

DEPRECATED since 2.0.0, use timber/url_helper/get_content_subdir/home_url

timber/user/name #

Filters the name of a user.

since 1.1.4