Timber\​ExternalImage

The Timber\ExternalImage class represents an image that is not part of the WordPress content (Attachment). Instead, it’s an image that can be either a path (relative/absolute) on the same server, or a URL (either from the same or from a different website). When you use a URL of an image on a different website, Timber will load it into your WordPress installation once and then load it from there.

PHP

$context = Timber::context();

// Lets say you have an external image that you want to use in your theme

$context['cover_image'] = Timber::get_external_image($url);

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>
</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>
</article>

Overview #

This class implements Timber\ImageInterface

Properties #

Methods #

Class Methods #

__toString() #

Gets the src for an attachment.

Returns: string The src of the 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 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 %}

extension() #

Gets the extension of the attached file.

since 2.0.0

Returns: string|null An uppercase extension string.

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>

file_loc() #

Gets the absolute path to the image.

Returns: string

height() #

Gets the height of the image in pixels.

Returns: int|null The height of the image in pixels. Null if the height can’t be read, e.g. because the file doesn’t exist.

Twig

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

HTML

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

path() #

Gets the relative path to the file.

Returns: string The relative path to the image file.

Twig

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

HTML

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

size() #

Gets filesize in a human-readable format.

This can be useful if you want to display the human-readable filesize for a file. It’s easier to read «16 KB» than «16555 bytes» or «1 MB» than «1048576 bytes».

since 2.0.0

Returns: null|int Filsize or null if the filesize couldn't be determined.

Use filesize 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.size }})</span>
</a>

src() #

Gets the source URL for the image.

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">

width() #

Gets the width of the image in pixels.

Returns: int|null The width of the image in pixels. Null if the width can’t be read, e.g. because the file doesn’t exist.

Twig

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

HTML

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