5690057835

pending completion

Build # 5690057835

Build Type

push

github

Committed by

nlemoine

Commit Message

Merge branch '2.x' of github.com:timber/timber into 2.x-refactor-file-models

# Conflicts:
#	src/Attachment.php
#	src/ExternalImage.php
#	src/FileSize.php
#	src/URLHelper.php

Run Details

1134 of 1134 new or added lines in 55 files covered. (100.0%)

3923 of 4430 relevant lines covered (88.56%)

59.08 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

44.44

/src/Image.php

<?php

namespace Timber;

/**
 * Class Image
 *
 * The `Timber\Image` class represents WordPress attachments that are images.
 *
 * @api
 * @example
 * ```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="http://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="http://example.org/wp-content/uploads/2015/06/kurt.jpg"
 *     alt="Another way to initialize images as Timber\Image objects, but within Twig" />
 * </article>
 * ```
 */
class Image extends Attachment implements ImageInterface
{
    /**
     * Representation.
     *
     * @api
     * @var string What does this class represent in WordPress terms?
     */
    public static $representation = 'image';

    /**
     * Image sizes.
     *
     * @api
     * @var array An array of available sizes for the image.
     */
    protected array $sizes;

    /**
     * Image dimensions.
     *
     * @internal
     * @var ImageDimensions stores Image Dimensions in a structured way.
     */
    protected ImageDimensions $image_dimensions;

    /**
     * Gets the Image information.
     *
     * @internal
     *
     * @param array $data Data to update.
     * @return array
     */
    protected function get_info(array $data): array
    {
        $data = parent::get_info($data);

        if ($this->file_loc()) {
            $data['image_dimensions'] = new ImageDimensions($this->file_loc());
        }

        return $data;
    }

    /**
     * Processes an image's dimensions.
     * @deprecated 2.0.0, use `{{ image.width }}` or `{{ image.height }}` in Twig
     * @internal
     * @param string $dim
     * @return array|int
     */
    protected function get_dimensions($dim)
    {
        Helper::deprecated(
            'Image::get_dimensions()',
            'Image::get_width() | Image::get_height()',
            '2.0.0'
        );
        return [$this->image_dimensions->width(), $this->image_dimensions->height()];
    }

    /**
     * @deprecated 2.0.0, use Image::get_dimension_loaded
     * @internal
     * @param string|null $dim
     * @return array|int
     */
    protected function get_dimensions_loaded($dim)
    {
        Helper::deprecated(
            'Image::get_dimensions()',
            'Image::get_width() or Image::get_height()',
            '2.0.0'
        );

        return $this->image_dimensions->get_dimension($dim);
    }

    /**
     * @deprecated 2.0.0, use Image::meta to retrieve specific fields
     * @return array
     */
    protected function get_post_custom($iid)
    {
        Helper::deprecated(
            '{{ image.get_post_custom( image.id ) }}',
            "{{ image.meta('my_field') }}",
            '2.0.0'
        );
        $pc = \get_post_custom($iid);
        if (\is_bool($pc)) {
            return [];
        }
        return $pc;
    }

    /**
     * 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.
     *
     * @api
     * @example
     * ```twig
     * <img src="{{ post.thumbnail.src }}">
     * <img src="{{ post.thumbnail.src('medium') }}">
     * ```
     * ```html
     * <img src="http://example.org/wp-content/uploads/2015/08/pic.jpg" />
     * <img src="http://example.org/wp-content/uploads/2015/08/pic-800-600.jpg">
     * ```
     *
     * @param string $size Optional. The requested image size. This can be a size that was in
     *                     WordPress. Example: `medium` or `large`. Default `full`.
     *
     * @return string The src URL for the image.
     */
    public function src($size = 'full'): string
    {
        if (isset($this->abs_url)) {
            return URLHelper::maybe_secure_url($this->abs_url);
        }

        $src = \wp_get_attachment_image_src($this->ID, $size);
        $src = $src[0];

        /**
         * Filters the src URL for a `Timber\Image`.
         *
         * @see \Timber\Image::src()
         * @since 0.21.7
         *
         * @param string $src The image src.
         * @param int    $id  The image ID.
         */
        $src = \apply_filters('timber/image/src', $src, $this->ID);

        /**
         * Filters the src URL for a `Timber\Image`.
         *
         * @deprecated 2.0.0, use `timber/image/src`
         */
        $src = \apply_filters_deprecated(
            'timber_image_src',
            [$src, $this->ID],
            '2.0.0',
            'timber/image/src'
        );

        return $src;
    }

    /**
     * Get image sizes.
     *
     * @return array
     */
    public function sizes(): array
    {
        if (isset($this->sizes)) {
            return $this->sizes;
        }

        return $this->sizes = (array) $this->metadata('sizes');
    }

    /**
     * Gets the width of the image in pixels.
     *
     * @api
     * @example
     * ```twig
     * <img src="{{ image.src }}" width="{{ image.width }}" />
     * ```
     * ```html
     * <img src="http://example.org/wp-content/uploads/2015/08/pic.jpg" width="1600" />
     * ```
     *
     * @return int The width of the image in pixels.
     */
    public function width()
    {
        return $this->image_dimensions->width();
    }

    /**
     * Gets the height of the image in pixels.
     *
     * @api
     * @example
     * ```twig
     * <img src="{{ image.src }}" height="{{ image.height }}" />
     * ```
     * ```html
     * <img src="http://example.org/wp-content/uploads/2015/08/pic.jpg" height="900" />
     * ```
     *
     * @return int The height of the image in pixels.
     */
    public function height()
    {
        return $this->image_dimensions->height();
    }

    /**
     * Gets the aspect ratio of the image.
     *
     * @api
     * @example
     * ```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 %}
     * ```
     *
     * @return float The aspect ratio of the image.
     */
    public function aspect()
    {
        return $this->image_dimensions->aspect();
    }

    /**
     * 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.
     *
     * @api
     * @example
     * ```twig
     * <img src="{{ image.src }}" alt="{{ image.alt }}" />
     * ```
     * ```html
     * <img src="http://example.org/wp-content/uploads/2015/08/pic.jpg"
     *     alt="You should always add alt texts to your images for better accessibility" />
     * ```
     *
     * @return string Alt text stored in WordPress.
     */
    public function alt(): string
    {
        $alt = $this->meta('_wp_attachment_image_alt');
        return \trim(\wp_strip_all_tags($alt));
    }

    /**
     * Gets dimension for an image.
     * @deprecated 2.0.0, use `{{ image.width }}` or `{{ image.height }}` in Twig
     * @internal
     *
     * @param string $dimension The requested dimension. Either `width` or `height`.
     * @return int|null The requested dimension. Null if image file couldn’t be found.
     */
    protected function get_dimension($dimension)
    {
        Helper::deprecated(
            'Image::get_dimension()',
            'Image::get_width() or Image::get_height()',
            '2.0.0'
        );
        return $this->image_dimensions->get_dimension($dimension);
    }

    /**
     * Gets already loaded dimension values.
     *
     * @internal
     *
     * @param string|null $dim Optional. The requested dimension. Either `width` or `height`.
     * @return int The requested dimension in pixels.
     */
    protected function get_dimension_loaded($dim = null)
    {
        return $this->image_dimensions->get_dimension($dim);
    }

    /**
     * Gets the srcset attribute for an image based on a WordPress image size.
     *
     * @api
     * @example
     * ```twig
     * <h1>{{ post.title }}</h1>
     * <img src="{{ post.thumbnail.src }}" srcset="{{ post.thumbnail.srcset }}" />
     * ```
     * ```html
     * <img src="http://example.org/wp-content/uploads/2018/10/pic.jpg" srcset="http://example.org/wp-content/uploads/2018/10/pic.jpg 1024w, http://example.org/wp-content/uploads/2018/10/pic-600x338.jpg 600w, http://example.org/wp-content/uploads/2018/10/pic-300x169.jpg 300w" />
     * ```
     * @param string $size An image size known to WordPress (like "medium").
     *
     * @return string|null
     */
    public function srcset(string $size = 'full'): ?string
    {
        return \wp_get_attachment_image_srcset($this->ID, $size) ?: null;
    }

    /**
     * Gets the sizes attribute for an image based on a WordPress image size.
     *
     * @api
     * @example
     * ```twig
     * <h1>{{ post.title }}</h1>
     * <img src="{{ post.thumbnail.src }}" srcset="{{ post.thumbnail.srcset }}" sizes="{{ post.thumbnail.img_sizes }}" />
     * ```
     * ```html
     * <img src="http://example.org/wp-content/uploads/2018/10/pic.jpg" srcset="http://example.org/wp-content/uploads/2018/10/pic.jpg 1024w, http://example.org/wp-content/uploads/2018/10/pic-600x338.jpg 600w, http://example.org/wp-content/uploads/2018/10/pic-300x169.jpg 300w sizes="(max-width: 1024px) 100vw, 102" />
     * ```
     *        @param string $size An image size known to WordPress (like "medium").
     * @return string|null
     */
    public function img_sizes(string $size = 'full'): ?string
    {
        return \wp_get_attachment_image_sizes($this->ID, $size) ?: null;
    }
}

1	<?php
2
3	namespace Timber;
4
5	/**
6	* Class Image
7	*
8	* The `Timber\Image` class represents WordPress attachments that are images.
9	*
10	* @api
11	* @example
12	* ```php
13	* $context = Timber::context();
14	*
15	* // Lets say you have an alternate large 'cover image' for your post
16	* // stored in a custom field which returns an image ID.
17	* $cover_image_id = $context['post']->cover_image;
18	*
19	* $context['cover_image'] = Timber::get_post($cover_image_id);
20	*
21	* Timber::render('single.twig', $context);
22	* ```
23	*
24	* ```twig
25	* <article>
26	* <img src="{{cover_image.src}}" class="cover-image" />
27	* <h1 class="headline">{{post.title}}</h1>
28	* <div class="body">
29	* {{post.content}}
30	* </div>
31	*
32	* <img
33	* src="{{ get_image(post.custom_field_with_image_id).src }}"
34	* alt="Another way to initialize images as Timber\Image objects, but within Twig" />
35	* </article>
36	* ```
37	*
38	* ```html
39	* <article>
40	* <img src="http://example.org/wp-content/uploads/2015/06/nevermind.jpg" class="cover-image" />
41	* <h1 class="headline">Now you've done it!</h1>
42	* <div class="body">
43	* Whatever whatever
44	* </div>
45	* <img
46	* src="http://example.org/wp-content/uploads/2015/06/kurt.jpg"
47	* alt="Another way to initialize images as Timber\Image objects, but within Twig" />
48	* </article>
49	* ```
50	*/
51	class Image extends Attachment implements ImageInterface
52	{
53	/**
54	* Representation.
55	*
56	* @api
57	* @var string What does this class represent in WordPress terms?
58	*/
59	public static $representation = 'image';
60
61	/**
62	* Image sizes.
63	*
64	* @api
65	* @var array An array of available sizes for the image.
66	*/
67	protected array $sizes;
68
69	/**
70	* Image dimensions.
71	*
72	* @internal
73	* @var ImageDimensions stores Image Dimensions in a structured way.
74	*/
75	protected ImageDimensions $image_dimensions;
76
77	/**
78	* Gets the Image information.
79	*
80	* @internal
81	*
82	* @param array $data Data to update.
83	* @return array
84	*/
85	protected function get_info(array $data): array
86	{
87	$data = parent::get_info($data);	68✔
88
89	if ($this->file_loc()) {	68✔
90	$data['image_dimensions'] = new ImageDimensions($this->file_loc());	68✔
91	}
92
93	return $data;	68✔
94	}
95
96	/**
97	* Processes an image's dimensions.
98	* @deprecated 2.0.0, use `{{ image.width }}` or `{{ image.height }}` in Twig
99	* @internal
100	* @param string $dim
101	* @return array\|int
102	*/
103	protected function get_dimensions($dim)
104	{
105	Helper::deprecated(	×
106	'Image::get_dimensions()',	×
107	'Image::get_width() \| Image::get_height()',	×
108	'2.0.0'	×
109	);	×
110	return [$this->image_dimensions->width(), $this->image_dimensions->height()];	×
111	}
112
113	/**
114	* @deprecated 2.0.0, use Image::get_dimension_loaded
115	* @internal
116	* @param string\|null $dim
117	* @return array\|int
118	*/
119	protected function get_dimensions_loaded($dim)
120	{
121	Helper::deprecated(	×
122	'Image::get_dimensions()',	×
123	'Image::get_width() or Image::get_height()',	×
124	'2.0.0'	×
125	);	×
126
127	return $this->image_dimensions->get_dimension($dim);	×
128	}
129
130	/**
131	* @deprecated 2.0.0, use Image::meta to retrieve specific fields
132	* @return array
133	*/
134	protected function get_post_custom($iid)
135	{
136	Helper::deprecated(	×
137	'{{ image.get_post_custom( image.id ) }}',	×
138	"{{ image.meta('my_field') }}",	×
139	'2.0.0'	×
140	);	×
141	$pc = \get_post_custom($iid);	×
142	if (\is_bool($pc)) {	×
143	return [];	×
144	}
145	return $pc;	×
146	}
147
148	/**
149	* Gets the source URL for the image.
150	*
151	* You can use WordPress image sizes (including the ones you registered with your theme or
152	* plugin) by passing the name of the size to this function (like `medium` or `large`). If the
153	* WordPress size has not been generated, it will return an empty string.
154	*
155	* @api
156	* @example
157	* ```twig
158	* <img src="{{ post.thumbnail.src }}">
159	* <img src="{{ post.thumbnail.src('medium') }}">
160	* ```
161	* ```html
162	* <img src="http://example.org/wp-content/uploads/2015/08/pic.jpg" />
163	* <img src="http://example.org/wp-content/uploads/2015/08/pic-800-600.jpg">
164	* ```
165	*
166	* @param string $size Optional. The requested image size. This can be a size that was in
167	* WordPress. Example: `medium` or `large`. Default `full`.
168	*
169	* @return string The src URL for the image.
170	*/
171	public function src($size = 'full'): string
172	{
173	if (isset($this->abs_url)) {	40✔
174	return URLHelper::maybe_secure_url($this->abs_url);	×
175	}
176
177	$src = \wp_get_attachment_image_src($this->ID, $size);	40✔
178	$src = $src[0];	40✔
179
180	/**
181	* Filters the src URL for a `Timber\Image`.
182	*
183	* @see \Timber\Image::src()
184	* @since 0.21.7
185	*
186	* @param string $src The image src.
187	* @param int $id The image ID.
188	*/
189	$src = \apply_filters('timber/image/src', $src, $this->ID);	40✔
190
191	/**
192	* Filters the src URL for a `Timber\Image`.
193	*
194	* @deprecated 2.0.0, use `timber/image/src`
195	*/
196	$src = \apply_filters_deprecated(	40✔
197	'timber_image_src',	40✔
198	[$src, $this->ID],	40✔
199	'2.0.0',	40✔
200	'timber/image/src'	40✔
201	);	40✔
202
203	return $src;	40✔
204	}
205
206	/**
207	* Get image sizes.
208	*
209	* @return array
210	*/
211	public function sizes(): array
212	{
213	if (isset($this->sizes)) {	4✔
214	return $this->sizes;	×
215	}
216
217	return $this->sizes = (array) $this->metadata('sizes');	4✔
218	}
219
220	/**
221	* Gets the width of the image in pixels.
222	*
223	* @api
224	* @example
225	* ```twig
226	* <img src="{{ image.src }}" width="{{ image.width }}" />
227	* ```
228	* ```html
229	* <img src="http://example.org/wp-content/uploads/2015/08/pic.jpg" width="1600" />
230	* ```
231	*
232	* @return int The width of the image in pixels.
233	*/
234	public function width()
235	{
236	return $this->image_dimensions->width();	2✔
237	}
238
239	/**
240	* Gets the height of the image in pixels.
241	*
242	* @api
243	* @example
244	* ```twig
245	* <img src="{{ image.src }}" height="{{ image.height }}" />
246	* ```
247	* ```html
248	* <img src="http://example.org/wp-content/uploads/2015/08/pic.jpg" height="900" />
249	* ```
250	*
251	* @return int The height of the image in pixels.
252	*/
253	public function height()
254	{
255	return $this->image_dimensions->height();	2✔
256	}
257
258	/**
259	* Gets the aspect ratio of the image.
260	*
261	* @api
262	* @example
263	* ```twig
264	* {% if post.thumbnail.aspect < 1 %}
265	* {# handle vertical image #}
266	* <img src="{{ post.thumbnail.src\|resize(300, 500) }}" alt="A basketball player" />
267	* {% else %}
268	* <img src="{{ post.thumbnail.src\|resize(500) }}" alt="A sumo wrestler" />
269	* {% endif %}
270	* ```
271	*
272	* @return float The aspect ratio of the image.
273	*/
274	public function aspect()
275	{
276	return $this->image_dimensions->aspect();	1✔
277	}
278
279	/**
280	* Gets the alt text for an image.
281	*
282	* For better accessibility, you should always add an alt attribute to your images, even if it’s
283	* empty.
284	*
285	* @api
286	* @example
287	* ```twig
288	* <img src="{{ image.src }}" alt="{{ image.alt }}" />
289	* ```
290	* ```html
291	* <img src="http://example.org/wp-content/uploads/2015/08/pic.jpg"
292	* alt="You should always add alt texts to your images for better accessibility" />
293	* ```
294	*
295	* @return string Alt text stored in WordPress.
296	*/
297	public function alt(): string
298	{
299	$alt = $this->meta('_wp_attachment_image_alt');	1✔
300	return \trim(\wp_strip_all_tags($alt));	1✔
301	}
302
303	/**
304	* Gets dimension for an image.
305	* @deprecated 2.0.0, use `{{ image.width }}` or `{{ image.height }}` in Twig
306	* @internal
307	*
308	* @param string $dimension The requested dimension. Either `width` or `height`.
309	* @return int\|null The requested dimension. Null if image file couldn’t be found.
310	*/
311	protected function get_dimension($dimension)
312	{
313	Helper::deprecated(	×
314	'Image::get_dimension()',	×
315	'Image::get_width() or Image::get_height()',	×
316	'2.0.0'	×
317	);	×
318	return $this->image_dimensions->get_dimension($dimension);	×
319	}
320
321	/**
322	* Gets already loaded dimension values.
323	*
324	* @internal
325	*
326	* @param string\|null $dim Optional. The requested dimension. Either `width` or `height`.
327	* @return int The requested dimension in pixels.
328	*/
329	protected function get_dimension_loaded($dim = null)
330	{
331	return $this->image_dimensions->get_dimension($dim);	×
332	}
333
334	/**
335	* Gets the srcset attribute for an image based on a WordPress image size.
336	*
337	* @api
338	* @example
339	* ```twig
340	* <h1>{{ post.title }}</h1>
341	* <img src="{{ post.thumbnail.src }}" srcset="{{ post.thumbnail.srcset }}" />
342	* ```
343	* ```html
344	* <img src="http://example.org/wp-content/uploads/2018/10/pic.jpg" srcset="http://example.org/wp-content/uploads/2018/10/pic.jpg 1024w, http://example.org/wp-content/uploads/2018/10/pic-600x338.jpg 600w, http://example.org/wp-content/uploads/2018/10/pic-300x169.jpg 300w" />
345	* ```
346	* @param string $size An image size known to WordPress (like "medium").
347	*
348	* @return string\|null
349	*/
350	public function srcset(string $size = 'full'): ?string
351	{
352	return \wp_get_attachment_image_srcset($this->ID, $size) ?: null;	1✔
353	}
354
355	/**
356	* Gets the sizes attribute for an image based on a WordPress image size.
357	*
358	* @api
359	* @example
360	* ```twig
361	* <h1>{{ post.title }}</h1>
362	* <img src="{{ post.thumbnail.src }}" srcset="{{ post.thumbnail.srcset }}" sizes="{{ post.thumbnail.img_sizes }}" />
363	* ```
364	* ```html
365	* <img src="http://example.org/wp-content/uploads/2018/10/pic.jpg" srcset="http://example.org/wp-content/uploads/2018/10/pic.jpg 1024w, http://example.org/wp-content/uploads/2018/10/pic-600x338.jpg 600w, http://example.org/wp-content/uploads/2018/10/pic-300x169.jpg 300w sizes="(max-width: 1024px) 100vw, 102" />
366	* ```
367	* @param string $size An image size known to WordPress (like "medium").
368	* @return string\|null
369	*/
370	public function img_sizes(string $size = 'full'): ?string
371	{
372	return \wp_get_attachment_image_sizes($this->ID, $size) ?: null;	1✔
373	}
374	}

timber / timber / 5690057835

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous