Timber\​Timber

Main class called Timber for this plugin.

PHP

// Get default posts on an archive page
$posts = Timber::get_posts();

// Query for some posts
$posts = Timber::get_posts( [
    'post_type' => 'article',
    'category_name' => 'sports',
] );

$context = Timber::context( [
    'posts' => $posts,
] );

Timber::render( 'index.twig', $context );

Overview #

Methods #

Class Methods #

get_post() #

Gets a Timber Post from a post ID, WP_Post object, a WP_Query object, or an associative array of arguments for WP_Query::__construct().

By default, Timber will use the Timber\Post class to create a new post object. To control which class is instantiated for your Post object, use Class Maps

see https://developer.wordpress.org/reference/classes/wp_query/__construct/

get_post( mixed $query = false, array $options = [] )

Returns: \Timber\Post|null Timber\Post object if a post was found, null if no post was found.

PHP

// Using a post ID.
$post = Timber::get_post( 75 );

// Using a WP_Post object.
$wp_post = get_post( 123 );
$post    = Timber::get_post( $wp_post );

// Using a WP_Query argument array
$post = Timber::get_post( [
  'post_type' => 'page',
] );

// Use currently queried post. Same as using get_the_ID() as a parameter.
$post = Timber::get_post();

// From an associative array with an `ID` key. For ACF compatibility. Using this
// approach directly is not recommended. If you can, configure the return type of your
// ACF field to just the ID.
$post = Timber::get_post( get_field('associated_post_array') ); // Just OK.
$post = Timber::get_post( get_field('associated_post_id') ); // Better!

get_attachment() #

Gets an attachment.

Behaves just like Timber::get_post(), except that it returns null if it finds a Timber\Post that is not an Attachment. Honors Class Maps and falsifies return value after Class Map for the found Timber\Post has been resolved.

see Timber\Timber::get_post()

since 2.0.0

get_attachment( mixed $query = false, array $options = [] )

Returns: \Timber\Attachment|null Timber\Attachment object if an attachment was found, null if no attachment was found.

get_image() #

Gets an image.

Behaves just like Timber::get_post(), except that it returns null if it finds a Timber\Post that is not an Image. Honors Class Maps and falsifies return value after Class Map for the found Timber\Post has been resolved.

see Timber\Timber::get_post()

since 2.0.0

get_image( mixed $query = false, array $options = [] )

Returns: \Timber\Image|null

get_external_image() #

Gets an external image.

Behaves just like Timber::get_image(), except that you can use an absolute or relative path or a URL to load an image. You can also pass in an external URL. In that case, Timber will sideload the image and store it in the uploads folder of your WordPress installation. The next time the image is accessed, it will be loaded from there.

see Timber\Timber::get_image()

since 2.0.0

get_external_image( bool $url = false, array $args = [] )

Returns: \Timber\ExternalImage|null

get_posts() #

Gets a collection of posts.

Refer to the official documentation for WP_Query for a list of all the arguments that can be used for the $query parameter.

get_posts( mixed $query = false, array $options = [] )

Returns: \Timber\PostCollectionInterface|null Null if no query could be run with the used query parameters.

PHP

// Use the global query.
$posts = Timber::get_posts();

// Using the WP_Query argument format.
$posts = Timber::get_posts( [
   'post_type'     => 'article',
   'category_name' => 'sports',
] );

// Using a WP_Query instance.
$posts = Timber::get_posts( new WP_Query( [ 'post_type' => 'any' ) );

// Using an array of post IDs.
$posts = Timber::get_posts( [ 47, 543, 3220 ] );

get_post_by() #

Gets a post by title or slug.

since 2.0.0

get_post_by( string $type, string $search_value, array $args = [] )

Returns: \Timber\Post|null A Timber post or null if no post could be found. If multiple posts with the same slug or title were found, it will select the post with the oldest date.

PHP

// By slug
$post = Timber::get_post_by( 'slug', 'about-us' );

// By title
$post = Timber::get_post_by( 'title', 'About us' );

query_post() #

Query post.

DEPRECATED since since 2.0.0 Use Timber::get_post() instead.

query_post( mixed $query = false, array $options = [] )

Returns: \Timber\Post|array|bool|null

query_posts() #

Query posts.

DEPRECATED since since 2.0.0 Use Timber::get_posts() instead.

query_posts( mixed $query = false, array $options = [] )

Returns: \Timber\PostCollectionInterface

get_attachment_by() #

Gets an attachment by its URL or absolute file path.

Honors the timber/post/image_extensions filter, returning a Timber\Image if the found attachment is identified as an image. Also honors Class Maps.

since 2.0.0

get_attachment_by( string $field_or_ident, string $ident = '' )

Returns: \Timber\Attachment|null

PHP

// Get attachment by URL.
$attachment = Timber::get_attachment_by( 'url', 'https://example.com/uploads/2020/09/cat.gif' );

// Get attachment by filepath.
$attachment = Timber::get_attachment_by( 'path', '/path/to/wp-content/uploads/2020/09/cat.gif' );

// Try to handle either case.
$mystery_string = some_function();
$attachment     = Timber::get_attachment_by( $mystery_string );

get_terms() #

Gets terms.

see https://developer.wordpress.org/reference/classes/wp_term_query/__construct/

get_terms( string|array $args = null, array $options = [] )

Returns: iterable

PHP

// Get all tags.
$tags = Timber::get_terms( 'post_tag' );
// Note that this is equivalent to:
$tags = Timber::get_terms( 'tag' );
$tags = Timber::get_terms( 'tags' );

// Get all categories.
$cats = Timber::get_terms( 'category' );

// Get all terms in a custom taxonomy.
$cats = Timber::get_terms('my_taxonomy');

// Perform a custom Term query.
$cats = Timber::get_terms( [
  'taxonomy' => 'my_taxonomy',
  'orderby'  => 'slug',
  'order'    => 'DESC',
] );

get_term() #

Gets a term.

get_term( int|\WP_Term $term = null )

Returns: \Timber\Term|null

PHP

// Get a Term.
$tag = Timber::get_term( 123 );

get_term_by() #

Gets a term by field.

This function works like get_term_by(), but returns a Timber\Term object.

since 2.0.0

get_term_by( string $field, int|string $value, string $taxonomy = '' )

Returns: \Timber\Term|null

PHP

// Get a term by slug.
$term = Timber::get_term_by( 'slug', 'security' );

// Get a term by name.
$term = Timber::get_term_by( 'name', 'Security' );

// Get a term by slug from a specific taxonomy.
$term = Timber::get_term_by( 'slug', 'security', 'category' );

get_users() #

Gets one or more users as an array.

By default, Timber will use the Timber\User class to create a your post objects. To control which class is used for your post objects, use Class Maps.

since 2.0.0

get_users( array $query = [], array $options = [] )

Returns: iterable An array of users objects. Will be empty if no users were found.

PHP

// Get users with on an array of user IDs.
$users = Timber::get_users( [ 24, 81, 325 ] );

// Get all users that only have a subscriber role.
$subscribers = Timber::get_users( [
    'role' => 'subscriber',
] );

// Get all users that have published posts.
$post_authors = Timber::get_users( [
    'has_published_posts' => [ 'post' ],
] );

get_user() #

Gets a single user.

By default, Timber will use the Timber\User class to create a your post objects. To control which class is used for your post objects, use Class Maps.

since 2.0.0

get_user( int|\WP_User $user = null )

Returns: \Timber\User|null

PHP

$current_user = Timber::get_user();

// Get user by ID.
$user = Timber::get_user( $user_id );

// Convert a WP_User object to a Timber\User object.
$user = Timber::get_user( $wp_user_object );

// Check if a user is logged in.

$user = Timber::get_user();

if ( $user ) {
    // Yay, user is logged in.
}

get_user_by() #

Gets a user by field.

This function works like get_user_by(), but returns a Timber\User object.

since 2.0.0

get_user_by( string $field, int|string $value )

Returns: \Timber\User|null

PHP

// Get a user by email.
$user = Timber::get_user_by( 'email', 'user@example.com' );

// Get a user by login.
$user = Timber::get_user_by( 'login', 'keanu-reeves' );

get_menu() #

Gets a nav menu object.

since 2.0.0

get_menu( int|string $identifier = null, array $args = [] )

Returns: \Timber\Menu|null

PHP

// Get a menu by location
$menu = Timber::get_menu( 'primary-menu' );

// Get a menu by slug
$menu = Timber::get_menu( 'my-menu' );

// Get a menu by name
$menu = Timber::get_menu( 'Main Menu' );

// Get a menu by ID (term_id)
$menu = Timber::get_menu( 123 );

get_menu_by() #

Gets a menu by field.

since 2.0.0

get_menu_by( string $field, int|string $value, array $args = [] )

Returns: \Timber\Menu|null

PHP

// Get a menu by location.
$menu = Timber::get_menu_by( 'location', 'primary' );

// Get a menu by slug.
$menu = Timber::get_menu_by( 'slug', 'primary-menu' );

get_pages_menu() #

Gets a menu from the existing pages.

since 2.0.0

get_pages_menu( array $args = [] )

PHP

$menu = Timber::get_pages_menu();

get_comments() #

Get comments.

since 2.0.0

get_comments( array|\WP_Comment_Query $query = [], array $options = [] )

Returns: array

get_comment() #

Gets comment.

since 2.0.0

get_comment( int|\WP_Comment $comment )

Returns: \Timber\Comment|null

get_sites() #

Get sites.

get_sites( array|bool $blog_ids = false )

Returns: array

get_context() #

Get context.

DEPRECATED since 2.0.0, use Timber::context() instead.

Returns: array

context() #

Gets the global context.

The context always contains the global context with the following variables:

• site – An instance of Timber\Site.
• request - An instance of Timber\Request.
• theme - An instance of Timber\Theme.
• user - An instance of Timber\User.
• http_host - The HTTP host.
• wp_title - Title retrieved for the currently displayed page, retrieved through wp_title().
• body_class - The body class retrieved through get_body_class().

The global context will be cached, which means that you can call this function again without losing performance.

In addition to that, the context will contain template contexts depending on which template is being displayed. For archive templates, a posts variable will be present that will contain a collection of Timber\Post objects for the default query. For singular templates, a post variable will be present that that contains a Timber\Post object of the $post global.

since 2.0.0

context( array $extra = [] )

Returns: array An array of context variables that is used to pass into Twig templates through a render or compile function.

context_global() #

Gets the global context.

This function is used by Timber::context() to get the global context. Usually, you don’t call this function directly, except when you need the global context in a partial view.

The global context will be cached, which means that you can call this function again without losing performance.

since 2.0.0

Returns: array An array of global context variables.

PHP

add_shortcode( 'global_address', function() {
    return Timber::compile(
        'global_address.twig',
        Timber::context_global()
    );
} );

compile() #

Compiles a Twig file.

Passes data to a Twig file and returns the output. If the template file doesn't exist it will throw a warning when WP_DEBUG is enabled.

compile( array|string $filenames, array $data = [], bool|int|array $expires = false, string $cache_mode = Loader::CACHE_USE_DEFAULT, bool $via_render = false )

Returns: bool|string The returned output.

PHP

$data = array(
    'firstname' => 'Jane',
    'lastname' => 'Doe',
    'email' => 'jane.doe@example.org',
);

$team_member = Timber::compile( 'team-member.twig', $data );

compile_string() #

Compile a string.

compile_string( string $string, array $data = [] )

Returns: bool|string

PHP

$data = array(
    'username' => 'Jane Doe',
);

$welcome = Timber::compile_string( 'Hi {{ username }}, I’m a string with a custom Twig variable', $data );

fetch() #

Fetch function.

DEPRECATED since 2.0.0 use Timber::compile()

fetch( array|string $filenames, array $data = [], bool|int $expires = false, string $cache_mode = Loader::CACHE_USE_DEFAULT )

Returns: bool|string The returned output.

render() #

Renders a Twig file.

Passes data to a Twig file and echoes the output.

render( array|string $filenames, array $data = [], bool|int|array $expires = false, string $cache_mode = Loader::CACHE_USE_DEFAULT )

PHP

$context = Timber::context();

Timber::render( 'index.twig', $context );

render_string() #

Render a string with Twig variables.

render_string( string $string, array $data = [] )

PHP

$data = array(
    'username' => 'Jane Doe',
);

Timber::render_string( 'Hi {{ username }}, I’m a string with a custom Twig variable', $data );

get_sidebar() #

Get sidebar.

get_sidebar( string $sidebar = 'sidebar.php', array $data = [] )

Returns: bool|string

get_sidebar_from_php() #

Get sidebar from PHP

get_sidebar_from_php( string $sidebar = '', array $data = [] )

Returns: string

get_widgets() #

Get widgets.

get_widgets( int|string $widget_id )

Returns: string

get_pagination() #

Get pagination.

DEPRECATED since 2.0.0

link https://timber.github.io/docs/v2/guides/pagination/

get_pagination( array $prefs = [] )

Returns: array|mixed