Timber\​Image

The Timber\Image class represents WordPress attachments that are images.

PHP

$context = Timber::context();

// Lets say you have an alternate large 'cover image' for your post
// stored in a custom field which returns an image ID.
$cover_image_id = $context['post']->cover_image;

$context['cover_image'] = Timber::get_post($cover_image_id);

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

Twig

<article>
  <img src="{{cover_image.src}}" class="cover-image" />
  <h1 class="headline">{{post.title}}</h1>
  <div class="body">
    {{post.content}}
  </div>

 <img
   src="{{ get_image(post.custom_field_with_image_id).src }}"
   alt="Another way to initialize images as Timber\Image objects, but within Twig" />
</article>

HTML

<article>
  <img src="https://example.org/wp-content/uploads/2015/06/nevermind.jpg" class="cover-image" />
  <h1 class="headline">Now you've done it!</h1>
  <div class="body">
    Whatever whatever
  </div>
  <img
    src="https://example.org/wp-content/uploads/2015/06/kurt.jpg"
    alt="Another way to initialize images as Timber\Image objects, but within Twig" />
</article>

Overview #

This class extends Timber\Attachment
This class implements Timber\ImageInterface

Properties #

Methods #

Class Methods #

__call() #

This is helpful for twig to return properties and methods see: https://github.com/fabpot/Twig/issues/2

This is also here to ensure that {{ post.class }} remains usable

__call( mixed $field, mixed $args )

Returns: mixed

This method is inherited from \Timber\Attachment.

__get() #

This is helpful for twig to return properties and methods see: https://github.com/fabpot/Twig/issues/2

This is also here to ensure that {{ post.class }} remains usable.

__get( mixed $field )

Returns: mixed

This method is inherited from \Timber\Attachment.

__toString() #

Gets the src for an attachment.

Returns: string The src of the attachment.

This method is inherited from \Timber\Attachment.

alt() #

Gets the alt text for an image.

For better accessibility, you should always add an alt attribute to your images, even if it’s empty.

Returns: string|null Alt text stored in WordPress.

Twig

<img src="{{ image.src }}" alt="{{ image.alt }}" />

HTML

<img src="https://example.org/wp-content/uploads/2015/08/pic.jpg"
    alt="You should always add alt texts to your images for better accessibility" />

aspect() #

Gets the aspect ratio of the image.

Returns: float The aspect ratio of the image.

Twig

{% if post.thumbnail.aspect < 1 %}
  {# handle vertical image #}
  <img src="{{ post.thumbnail.src|resize(300, 500) }}" alt="A basketball player" />
{% else %}
  <img src="{{ post.thumbnail.src|resize(500) }}" alt="A sumo wrestler" />
{% endif %}

author() #

Return the author of a post

Returns: \Timber\User|null A User object if found, false if not

This method is inherited from \Timber\Attachment.

Twig

<h1>{{post.title}}</h1>
<p class="byline">
    <a href="{{post.author.link}}">{{post.author.name}}</a>
</p>

authors() #

Got more than one author? That's cool, but you'll need Co-Authors plus or another plugin to access any data

Returns: array

This method is inherited from \Timber\Attachment.

can_edit() #

Checks whether the current user can edit the post.

Returns: bool

This method is inherited from \Timber\Attachment.

Twig

{% if post.can_edit %}
    <a href="{{ post.edit_link }}">Edit</a>
{% endif %}

caption() #

Gets the caption of an attachment.

since 2.0

Returns: string|null

This method is inherited from \Timber\Attachment.

Twig

<figure>
    <img src="{{ post.thumbnail.src }}">

    {% if post.thumbnail is not empty %}
        <figcaption>{{ post.thumbnail.caption }}</figcaption
    {% endif %}
</figure>

categories() #

Get the categories on a particular post

Returns: array of Timber\Term objects

This method is inherited from \Timber\Attachment.

category() #

Gets a category attached to a post.

If multiple categories are set, it will return just the first one.

Returns: \Timber\Term|null

This method is inherited from \Timber\Attachment.

children() #

Returns an array of children on the post as Timber\Posts (or other claass as you define).

children( string|array $args = 'any' )

Returns: \Timber\PostCollectionInterface

This method is inherited from \Timber\Attachment.

Twig

{% if post.children %}
    Here are the child pages:
    {% for child in post.children %}
        <a href="{{ child.link }}">{{ child.title }}</a>
    {% endfor %}
{% endif %}

comment_count() #

Gets the number of comments on a post.

Returns: int The number of comments on a post

This method is inherited from \Timber\Attachment.

comment_form() #

Gets the comment form for use on a single article page

comment_form( array $args = [] )

Returns: string of HTML for the form

This method is inherited from \Timber\Attachment.

comments() #

Gets the comments on a Timber\Post and returns them as an array of Timber\Comment objects (or whatever comment class you set).

see Timber\CommentThread for an example with nested comments

comments( int $count = null, string $order = 'wp', string $type = 'comment', string $status = 'approve' )

Returns: bool|\Timber\CommentThread

This method is inherited from \Timber\Attachment.

single.twig

Twig

<div id="post-comments">
  <h4>Comments on {{ post.title }}</h4>
  <ul>
    {% for comment in post.comments() %}
      {% include 'comment.twig' %}
    {% endfor %}
  </ul>
  <div class="comment-form">
    {{ function('comment_form') }}
  </div>
</div>

comment.twig

Twig

{# comment.twig #}
<li>
  <p class="comment-author">{{ comment.author.name }} says:</p>
  <div>{{ comment.content }}</div>
</li>

content() #

Gets the actual content of a WordPress post.

As opposed to using {{ post.post_content }}, this will run the hooks/filters attached to the the_content filter. It will return your post’s content with WordPress filters run on it – which means it will parse blocks, convert shortcodes or run wpautop() on the content.

If you use page breaks in your content to split your post content into multiple pages, use {{ post.paged_content }} to display only the content for the current page.

content( int $page = '', int $len = -1, bool $remove_blocks = false )

Returns: string The content of the post.

This method is inherited from \Timber\Attachment.

Twig

<article>
    <h1>{{ post.title }}</h1>

    <div class="content">{{ post.content }}</div>
</article>

convert() #

Finds any WP_Post objects and converts them to Timber\Post objects.

convert( array|\WP_Post $data )

This method is inherited from \Timber\Attachment.

date() #

Gets the publishing date of the post.

This function will also apply the get_the_date filter to the output.

If you use {{ post.date }} with the |time_ago filter, then make sure that you use a time format including the full time and not just the date.

date( string|null $date_format = null )

Returns: string

This method is inherited from \Timber\Attachment.

Twig

{# Uses date format set in Settings → General #}
Published on {{ post.date }}
OR
Published on {{ post.date('F jS') }}
which was
{{ post.date('U')|time_ago }}
{{ post.date('Y-m-d H:i:s')|time_ago }}
{{ post.date(constant('DATE_ATOM'))|time_ago }}

HTML

Published on January 12, 2015
OR
Published on Jan 12th
which was
8 years ago

edit_link() #

Gets the edit link for a post if the current user has the correct rights.

Returns: string|null The edit URL of a post in the WordPress admin or null if the current user can’t edit the post.

This method is inherited from \Timber\Attachment.

Twig

{% if post.can_edit %}
    <a href="{{ post.edit_link }}">Edit</a>
{% endif %}

excerpt() #

Gets a excerpt of your post.

If you have an excerpt is set on the post, the excerpt will be used. Otherwise it will try to pull from an excerpt from post_content. If there’s a <!-- more --> tag in the post content, it will use that to mark where to pull through.

see Timber\PostExcerpt

excerpt( array $options = [] )

Returns: \Timber\PostExcerpt

This method is inherited from \Timber\Attachment.

Twig

<h2>{{ post.title }}</h2>
<div>{{ post.excerpt({ words: 100, read_more: 'Keep reading' }) }}</div>

extension() #

Gets the extension of the attached file.

since 2.0.0

Returns: string An uppercase extension string.

This method is inherited from \Timber\Attachment.

Use extension information in a link that downloads a file:

Twig

<a class="download" href="{{ attachment.src }}" download="{{ attachment.title }}">
    <span class="download-title">{{ attachment.title }}</span>
    <span class="download-info">
        (Download {{ attachment.extension|upper }}, {{ attachment.size }})
    </span>
</a>

field_object() #

Gets the field object data from Advanced Custom Fields.

This includes metadata on the field like whether it's conditional or not.

since 1.6.0

field_object( string $field_name )

Returns: mixed

This method is inherited from \Timber\Attachment.

file() #

Gets the relative path to the uploads folder of an attachment.

Returns: string

This method is inherited from \Timber\Attachment.

file_loc() #

Gets the absolute path to an attachment.

Returns: string

This method is inherited from \Timber\Attachment.

format() #

Returns: mixed

This method is inherited from \Timber\Attachment.

gallery() #

Returns galleries from the post’s content.

gallery( mixed $html = true )

Returns: array A list of arrays, each containing gallery data and srcs parsed from the expanded shortcode.

This method is inherited from \Timber\Attachment.

Twig

{{ post.gallery }}

get_field() #

Gets a post meta value.

DEPRECATED since 2.0.0, use {{ post.meta('field_name') }} instead.

see Timber\Post::meta()

get_field( string $field_name = null )

Returns: mixed The meta field value.

This method is inherited from \Timber\Attachment.

has_field() #

has_field( string $field_name )

Returns: bool

This method is inherited from \Timber\Attachment.

has_term() #

has_term( string|int $term_name_or_id, string $taxonomy = 'all' )

Returns: bool

This method is inherited from \Timber\Attachment.

height() #

Gets the height of the image in pixels.

Returns: int The height of the image in pixels.

Twig

<img src="{{ image.src }}" height="{{ image.height }}" />

HTML

<img src="https://example.org/wp-content/uploads/2015/08/pic.jpg" height="900" />

img_sizes() #

Gets the sizes attribute for an image based on a WordPress image size.

img_sizes( string $size = 'full' )

Returns: string|null

Twig

<h1>{{ post.title }}</h1>
<img src="{{ post.thumbnail.src }}" srcset="{{ post.thumbnail.srcset }}" sizes="{{ post.thumbnail.img_sizes }}" />

HTML

<img src="https://example.org/wp-content/uploads/2018/10/pic.jpg" srcset="https://example.org/wp-content/uploads/2018/10/pic.jpg 1024w, https://example.org/wp-content/uploads/2018/10/pic-600x338.jpg 600w, https://example.org/wp-content/uploads/2018/10/pic-300x169.jpg 300w sizes="(max-width: 1024px) 100vw, 102" />

import_field() #

Import field data onto this object

DEPRECATED since since 2.0.0

import_field( string $field_name )

This method is inherited from \Timber\Attachment.

link() #

Gets the link to an attachment.

This returns a link to an attachment’s page, but not the link to the image src itself.

Returns: string The URL of the attachment.

This method is inherited from \Timber\Attachment.

Twig

<a href="{{ image.link }}"><img src="{{ image.src }} "></a>

HTML

<a href="https://example.org/my-cool-picture">
    <img src="https://example.org/wp-content/uploads/2015/whatever.jpg"/>
</a>

meta() #

Gets an object meta value.

Returns a meta value or all meta values for all custom fields of an object saved in the meta database table.

Fetching all values is only advised during development, because it can have a big performance impact, when all filters are applied.

meta( string $field_name = '', array $args = [] )

Returns: mixed The custom field value or an array of custom field values. Null if no value could be found.

This method is inherited from \Timber\Attachment.

modified_author() #

Get the author (WordPress user) who last modified the post

Returns: \Timber\User|null A User object if found, false if not

This method is inherited from \Timber\Attachment.

Twig

Last updated by {{ post.modified_author.name }}

HTML

Last updated by Harper Lee

modified_date() #

Gets the date the post was last modified.

This function will also apply the get_the_modified_date filter to the output.

modified_date( string|null $date_format = null )

Returns: string

This method is inherited from \Timber\Attachment.

Twig

{# Uses date format set in Settings → General #}
Last modified on {{ post.modified_date }}
OR
Last modified on {{ post.modified_date('F jS') }}

HTML

Last modified on January 12, 2015
OR
Last modified on Jan 12th

modified_time() #

Gets the time of the last modification of the post to use in your template.

This function will also apply the get_the_time filter to the output.

modified_time( string|null $time_format = null )

Returns: string

This method is inherited from \Timber\Attachment.

Twig

{# Uses time format set in Settings → General #}
Published at {{ post.time }}
OR
Published at {{ post.time|time('G:i') }}

HTML

Published at 1:25 pm
OR
Published at 13:25

modified_timestamp() #

Gets the timestamp when the post was last modified.

since 2.0.0

Returns: false|int Unix timestamp on success, false on failure.

This method is inherited from \Timber\Attachment.

name() #

Returns: string

This method is inherited from \Timber\Attachment.

next() #

Gets the next post that is adjacent to the current post in a collection.

Works pretty much the same as get_next_post().

next( bool|string $in_same_term = false )

Returns: mixed

This method is inherited from \Timber\Attachment.

Twig

{% if post.next %}
    <a href="{{ post.next.link }}">{{ post.next.title }}</a>
{% endif %}

pagination() #

Gets a data array to display a pagination for your paginated post.

Use this in combination with {{ post.paged_content }}.

Returns: array An array with data to build your paginated content.

This method is inherited from \Timber\Attachment.

Using simple links to the next an previous page. Twig

{% if post.pagination.next is not empty %}
    <a href="{{ post.pagination.next.link|esc_url }}">Go to next page</a>
{% endif %}

{% if post.pagination.prev is not empty %}
    <a href="{{ post.pagination.prev.link|esc_url }}">Go to previous page</a>
{% endif %}

Using a pagination for all pages. Twig

{% if post.pagination.pages is not empty %}
   <nav aria-label="pagination">
       <ul>
           {% for page in post.pagination.pages %}
               <li>
                   {% if page.current %}
                       <span aria-current="page">Page {{ page.title }}</span>
                   {% else %}
                       <a href="{{ page.link|esc_ur }}">Page {{ page.title }}</a>
                   {% endif %}
               </li>
           {% endfor %}
       </ul>
   </nav>
{% endif %}

parent() #

Gets the parent object.

The parent object of an attachment is a post it is assigned to.

Returns: null|\Timber\Post Parent object as a Timber\Post. Returns false if no parent object is defined.

This method is inherited from \Timber\Attachment.

Twig

This image is assigned to {{ image.parent.title }}

password_required() #

whether post requires password and correct password has been provided

Returns: bool

This method is inherited from \Timber\Attachment.

path() #

Gets the relative path to an attachment.

Returns: string The relative path to an attachment.

This method is inherited from \Timber\Attachment.

Twig

<img src="{{ image.path }}" />

HTML

<img src="/wp-content/uploads/2015/08/pic.jpg" />

prev() #

Get the previous post that is adjacent to the current post in a collection.

Works pretty much the same as get_previous_post().

prev( bool|string $in_same_term = false )

Returns: mixed

This method is inherited from \Timber\Attachment.

Twig

{% if post.prev %}
    <a href="{{ post.prev.link }}">{{ post.prev.title }}</a>
{% endif %}

preview() #

Gets an excerpt of your post.

DEPRECATED since 2.0.0, use {{ post.excerpt }} instead.

If you have an excerpt is set on the post, the excerpt will be used. Otherwise it will try to pull from an excerpt from post_content. If there’s a <!-- more --> tag in the post content, it will use that to mark where to pull through.

This method returns a Timber\PostExcerpt object, which is a chainable object. This means that you can change the output of the excerpt by adding more methods. Refer to the documentation of the Timber\PostExcerpt class to get an overview of all the available methods.

see Timber\PostExcerpt

Returns: \Timber\PostExcerpt

This method is inherited from \Timber\Attachment.

Twig

{# Use default excerpt #}
<p>{{ post.excerpt }}</p>

{# Change the post excerpt text #}
<p>{{ post.excerpt.read_more('Continue Reading') }}</p>

{# Additionally restrict the length to 50 words #}
<p>{{ post.excerpt.length(50).read_more('Continue Reading') }}</p>

raw_meta() #

Gets an object meta value directly from the database.

Returns a raw meta value or all raw meta values saved in the meta database table. In comparison to meta(), this function will return raw values that are not filtered by third- party plugins.

Fetching raw values for all custom fields will not have a big performance impact, because WordPress gets all meta values, when the first meta value is accessed.

since 2.0.0

raw_meta( string $field_name = '' )

Returns: null|mixed The meta field value(s). Null if no value could be found, an empty array if all fields were requested but no values could be found.

This method is inherited from \Timber\Attachment.

setup() #

Sets up a post.

Sets up the $post global, and other global variables as well as variables in the $wp_query global that makes Timber more compatible with WordPress.

This function will be called automatically when you loop over Timber posts as well as in Timber::context().

since 2.0.0

Returns: \Timber\Post The post instance.

This method is inherited from \Timber\Attachment.

size() #

Gets the raw filesize in bytes.

Use the size_format filter to format the raw size into a human readable size («1 MB» instead of «1048576»)

see https://developer.wordpress.org/reference/functions/size_format/ Use filesize information in a link that downloads a file:

<a class="download" href="{{ attachment.src }}" download="{{ attachment.title }}">
    <span class="download-title">{{ attachment.title }}</span>
    <span class="download-info">(Download, {{ attachment.size|size_format }})</span>
</a>

since 2.0.0

Returns: int|null The raw filesize or null if it could not be read.

This method is inherited from \Timber\Attachment.

src() #

Gets the source URL for the image.

You can use WordPress image sizes (including the ones you registered with your theme or plugin) by passing the name of the size to this function (like medium or large). If the WordPress size has not been generated, it will return an empty string.

src( string $size = 'full' )

Returns: string The src URL for the image.

Twig

<img src="{{ post.thumbnail.src }}">
<img src="{{ post.thumbnail.src('medium') }}">

HTML

<img src="https://example.org/wp-content/uploads/2015/08/pic.jpg" />
<img src="https://example.org/wp-content/uploads/2015/08/pic-800-600.jpg">

srcset() #

Gets the srcset attribute for an image based on a WordPress image size.

srcset( string $size = 'full' )

Returns: string|null

Twig

<h1>{{ post.title }}</h1>
<img src="{{ post.thumbnail.src }}" srcset="{{ post.thumbnail.srcset }}" />

HTML

<img src="https://example.org/wp-content/uploads/2018/10/pic.jpg" srcset="https://example.org/wp-content/uploads/2018/10/pic.jpg 1024w, https://example.org/wp-content/uploads/2018/10/pic-600x338.jpg 600w, https://example.org/wp-content/uploads/2018/10/pic-300x169.jpg 300w" />

tags() #

Gets the tags on a post, uses WP's post_tag taxonomy

Returns: array

This method is inherited from \Timber\Attachment.

teardown() #

Resets variables after post has been used.

This function will be called automatically when you loop over Timber posts.

since 2.0.0

Returns: \Timber\Post The post instance.

This method is inherited from \Timber\Attachment.

terms() #

Gets the terms associated with the post.

terms( string|array $query_args = [], array $options = [] )

Returns: array An array of taxonomies.

This method is inherited from \Timber\Attachment.

Twig

<section id="job-feed">
{% for post in job %}
    <div class="job">
        <h2>{{ post.title }}</h2>
        <p>{{ post.terms({
            taxonomy: 'category',
            orderby: 'name',
            order: 'ASC'
        })|join(', ') }}</p>
    </div>
{% endfor %}
</section>

HTML

<section id="job-feed">
    <div class="job">
        <h2>Cheese Maker</h2>
        <p>Cheese, Food, Fromage</p>
    </div>
    <div class="job">
        <h2>Mime</h2>
        <p>Performance, Silence</p>
    </div>
</section>

PHP

// Get all terms of a taxonomy.
$terms = $post->terms( 'category' );

// Get terms of multiple taxonomies.
$terms = $post->terms( array( 'books', 'movies' ) );

// Use custom arguments for taxonomy query and options.
$terms = $post->terms( [
    'taxonomy' => 'custom_tax',
    'orderby'  => 'count'
], [
    'merge' => false
] );

thumbnail() #

get the featured image as a Timber/Image

Returns: \Timber\Image|null of your thumbnail

This method is inherited from \Timber\Attachment.

Twig

<img src="{{ post.thumbnail.src }}" />

thumbnail_id() #

Gets the post’s thumbnail ID.

since 2.0.0

Returns: false|int The default post’s ID. False if no thumbnail was defined.

This method is inherited from \Timber\Attachment.

time() #

Gets the time the post was published to use in your template.

This function will also apply the get_the_time filter to the output.

time( string|null $time_format = null )

Returns: string

This method is inherited from \Timber\Attachment.

Twig

{# Uses time format set in Settings → General #}
Published at {{ post.time }}
OR
Published at {{ post.time|time('G:i') }}

HTML

Published at 1:25 pm
OR
Published at 13:25

timestamp() #

Gets the timestamp when the post was published.

since 2.0.0

Returns: false|int Unix timestamp on success, false on failure.

This method is inherited from \Timber\Attachment.

title() #

Returns the processed title to be used in templates. This returns the title of the post after WP's filters have run. This is analogous to the_title() in standard WP template tags.

Returns: string

This method is inherited from \Timber\Attachment.

Twig

<h1>{{ post.title }}</h1>

type() #

Returns the PostType object for a post’s post type with labels and other info.

since 1.0.4

Returns: \Timber\PostType

This method is inherited from \Timber\Attachment.

Twig

This post is from <span>{{ post.type.labels.name }}</span>

HTML

This post is from <span>Recipes</span>

width() #

Gets the width of the image in pixels.

Returns: int The width of the image in pixels.

Twig

<img src="{{ image.src }}" width="{{ image.width }}" />

HTML

<img src="https://example.org/wp-content/uploads/2015/08/pic.jpg" width="1600" />