Timber Logo

You are reading the documentation for Timber v2.x. Switch to the documentation for Timber v1.x.

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 #

NameTypeDescription
$alt_textstring
$captionstring
$file_locstringThe absolute path to the attachmend file in the filesystem (Example: /var/www/htdocs/wp-content/themes/my-theme/images/)
$file_extensionstringA file extension.

Methods #

NameReturn TypeSummary/Returns
__toString()stringGets the src for an attachment.

Returns: The src of the attachment.
alt()stringGets the alt text for an image.

Returns: Alt text stored in WordPress.
aspect()floatGets the aspect ratio of the image.

Returns: The aspect ratio of the image.
extension()string or nullGets the extension of the attached file.

Returns: An uppercase extension string.
file_loc()stringGets the absolute path to the image.
height()int or nullGets the height of the image in pixels.

Returns: The height of the image in pixels. Null if the height can’t be read, e.g. because the file doesn’t exist.
path()stringGets the relative path to the file.

Returns: The relative path to the image file.
size()null or intGets filesize in a human-readable format.

Returns: Filsize or null if the filesize couldn't be determined.
src()stringGets the source URL for the image.

Returns: The src URL for the image.
width()int or nullGets the width of the image in pixels.

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

Class Methods #

src() #

Gets the source URL for the image.

src( string $size = 'full' )

Returns: string The src URL for the image.

NameTypeDescription
$sizestringIgnored. For compatibility with Timber\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">

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

file_loc() #

Gets the absolute path to the image.

Returns: string


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>

__toString() #

Gets the src for an attachment.

Returns: string The src of the attachment.


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>

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

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

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 %}

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