class-wpseo-image-utils.php — Yoast SEO – Advanced SEO with real-time guidance and built-in AI 19.7.2

wordpress-seo / inc / class-wpseo-image-utils.php

wordpress-seo / inc Last commit date

class-wpseo-image-utils.php

492 lines

1	<?php
2	/**
3	* WPSEO plugin file.
4	*
5	* @package WPSEO
6	*/
7
8	/**
9	* WPSEO_Image_Utils.
10	*/
11	class WPSEO_Image_Utils {
12
13	/**
14	* Find an attachment ID for a given URL.
15	*
16	* @param string $url The URL to find the attachment for.
17	*
18	* @return int The found attachment ID, or 0 if none was found.
19	*/
20	public static function get_attachment_by_url( $url ) {
21	/*
22	* As get_attachment_by_url won't work on resized versions of images,
23	* we strip out the size part of an image URL.
24	*/
25	$url = preg_replace( '/(.*)-\d+x\d+\.(jpg\|png\|gif)$/', '$1.$2', $url );
26
27	static $uploads;
28
29	if ( $uploads === null ) {
30	$uploads = wp_get_upload_dir();
31	}
32
33	// Don't try to do this for external URLs.
34	if ( strpos( $url, $uploads['baseurl'] ) !== 0 ) {
35	return 0;
36	}
37
38	if ( function_exists( 'wpcom_vip_attachment_url_to_postid' ) ) {
39	// @codeCoverageIgnoreStart -- We can't test this properly.
40	return (int) wpcom_vip_attachment_url_to_postid( $url );
41	// @codeCoverageIgnoreEnd -- The rest we _can_ test.
42	}
43
44	return self::attachment_url_to_postid( $url );
45	}
46
47	/**
48	* Implements the attachment_url_to_postid with use of WP Cache.
49	*
50	* @param string $url The attachment URL for which we want to know the Post ID.
51	*
52	* @return int The Post ID belonging to the attachment, 0 if not found.
53	*/
54	protected static function attachment_url_to_postid( $url ) {
55	$cache_key = sprintf( 'yoast_attachment_url_post_id_%s', md5( $url ) );
56
57	// Set the ID based on the hashed URL in the cache.
58	$id = wp_cache_get( $cache_key );
59
60	if ( $id === 'not_found' ) {
61	return 0;
62	}
63
64	// ID is found in cache, return.
65	if ( $id !== false ) {
66	return $id;
67	}
68
69	// Note: We use the WP COM version if we can, see above.
70	$id = attachment_url_to_postid( $url );
71
72	if ( empty( $id ) ) {
73	wp_cache_set( $cache_key, 'not_found', '', ( 12 * HOUR_IN_SECONDS + wp_rand( 0, ( 4 * HOUR_IN_SECONDS ) ) ) );
74	return 0;
75	}
76
77	// We have the Post ID, but it's not in the cache yet. We do that here and return.
78	wp_cache_set( $cache_key, $id, '', ( 24 * HOUR_IN_SECONDS + wp_rand( 0, ( 12 * HOUR_IN_SECONDS ) ) ) );
79	return $id;
80	}
81
82	/**
83	* Retrieves the image data.
84	*
85	* @param array $image Image array with URL and metadata.
86	* @param int $attachment_id Attachment ID.
87	*
88	* @return false\|array {
89	* Array of image data
90	*
91	* @type string $alt Image's alt text.
92	* @type string $path Path of image.
93	* @type int $width Width of image.
94	* @type int $height Height of image.
95	* @type string $type Image's MIME type.
96	* @type string $size Image's size.
97	* @type string $url Image's URL.
98	* @type int $filesize The file size in bytes, if already set.
99	* }
100	*/
101	public static function get_data( $image, $attachment_id ) {
102	if ( ! is_array( $image ) ) {
103	return false;
104	}
105
106	// Deals with non-set keys and values being null or false.
107	if ( empty( $image['width'] ) \|\| empty( $image['height'] ) ) {
108	return false;
109	}
110
111	$image['id'] = $attachment_id;
112	$image['alt'] = self::get_alt_tag( $attachment_id );
113	$image['pixels'] = ( (int) $image['width'] * (int) $image['height'] );
114
115	if ( ! isset( $image['type'] ) ) {
116	$image['type'] = get_post_mime_type( $attachment_id );
117	}
118
119	/**
120	* Filter: 'wpseo_image_data' - Filter image data.
121	*
122	* Elements with keys not listed in the section will be discarded.
123	*
124	* @api array {
125	* Array of image data
126	*
127	* @type int id Image's ID as an attachment.
128	* @type string alt Image's alt text.
129	* @type string path Image's path.
130	* @type int width Width of image.
131	* @type int height Height of image.
132	* @type int pixels Number of pixels in the image.
133	* @type string type Image's MIME type.
134	* @type string size Image's size.
135	* @type string url Image's URL.
136	* @type int filesize The file size in bytes, if already set.
137	* }
138	* @api int Attachment ID.
139	*/
140	$image = apply_filters( 'wpseo_image_data', $image, $attachment_id );
141
142	// Keep only the keys we need, and nothing else.
143	return array_intersect_key( $image, array_flip( [ 'id', 'alt', 'path', 'width', 'height', 'pixels', 'type', 'size', 'url', 'filesize' ] ) );
144	}
145
146	/**
147	* Checks a size version of an image to see if it's not too heavy.
148	*
149	* @param array $image Image to check the file size of.
150	*
151	* @return bool True when the image is within limits, false if not.
152	*/
153	public static function has_usable_file_size( $image ) {
154	if ( ! is_array( $image ) \|\| $image === [] ) {
155	return false;
156	}
157
158	/**
159	* Filter: 'wpseo_image_image_weight_limit' - Determines what the maximum weight
160	* (in bytes) of an image is allowed to be, default is 2 MB.
161	*
162	* @api int - The maximum weight (in bytes) of an image.
163	*/
164	$max_size = apply_filters( 'wpseo_image_image_weight_limit', 2097152 );
165
166	// We cannot check without a path, so assume it's fine.
167	if ( ! isset( $image['path'] ) ) {
168	return true;
169	}
170
171	return ( self::get_file_size( $image ) <= $max_size );
172	}
173
174	/**
175	* Find the right version of an image based on size.
176	*
177	* @param int $attachment_id Attachment ID.
178	* @param string $size Size name.
179	*
180	* @return array\|false Returns an array with image data on success, false on failure.
181	*/
182	public static function get_image( $attachment_id, $size ) {
183	$image = false;
184	if ( $size === 'full' ) {
185	$image = self::get_full_size_image_data( $attachment_id );
186	}
187
188	if ( ! $image ) {
189	$image = image_get_intermediate_size( $attachment_id, $size );
190	}
191
192	if ( ! $image ) {
193	return false;
194	}
195
196	$image['size'] = $size;
197
198	return self::get_data( $image, $attachment_id );
199	}
200
201	/**
202	* Returns the image data for the full size image.
203	*
204	* @param int $attachment_id Attachment ID.
205	*
206	* @return array\|false Array when there is a full size image. False if not.
207	*/
208	protected static function get_full_size_image_data( $attachment_id ) {
209	$image = wp_get_attachment_metadata( $attachment_id );
210	if ( ! is_array( $image ) ) {
211	return false;
212	}
213
214	$image['url'] = wp_get_attachment_image_url( $attachment_id, 'full' );
215	$image['path'] = get_attached_file( $attachment_id );
216	$image['size'] = 'full';
217
218	return $image;
219	}
220
221	/**
222	* Finds the full file path for a given image file.
223	*
224	* @param string $path The relative file path.
225	*
226	* @return string The full file path.
227	*/
228	public static function get_absolute_path( $path ) {
229	static $uploads;
230
231	if ( $uploads === null ) {
232	$uploads = wp_get_upload_dir();
233	}
234
235	// Add the uploads basedir if the path does not start with it.
236	if ( empty( $uploads['error'] ) && strpos( $path, $uploads['basedir'] ) !== 0 ) {
237	return $uploads['basedir'] . DIRECTORY_SEPARATOR . ltrim( $path, DIRECTORY_SEPARATOR );
238	}
239
240	return $path;
241	}
242
243	/**
244	* Get the relative path of the image.
245	*
246	* @param string $img Image URL.
247	*
248	* @return string The expanded image URL.
249	*/
250	public static function get_relative_path( $img ) {
251	if ( $img[0] !== '/' ) {
252	return $img;
253	}
254
255	// If it's a relative URL, it's relative to the domain, not necessarily to the WordPress install, we
256	// want to preserve domain name and URL scheme (http / https) though.
257	$parsed_url = wp_parse_url( home_url() );
258	$img = $parsed_url['scheme'] . '://' . $parsed_url['host'] . $img;
259
260	return $img;
261	}
262
263	/**
264	* Get the image file size.
265	*
266	* @param array $image An image array object.
267	*
268	* @return int The file size in bytes.
269	*/
270	public static function get_file_size( $image ) {
271	if ( isset( $image['filesize'] ) ) {
272	return $image['filesize'];
273	}
274
275	if ( ! isset( $image['path'] ) ) {
276	return 0;
277	}
278
279	// If the file size for the file is over our limit, we're going to go for a smaller version.
280	if ( function_exists( 'wp_filesize' ) ) {
281	return wp_filesize( self::get_absolute_path( $image['path'] ) );
282	}
283
284	return file_exists( $image['path'] ) ? (int) filesize( $image['path'] ) : 0;
285	}
286
287	/**
288	* Returns the different image variations for consideration.
289	*
290	* @param int $attachment_id The attachment to return the variations for.
291	*
292	* @return array The different variations possible for this attachment ID.
293	*/
294	public static function get_variations( $attachment_id ) {
295	$variations = [];
296
297	foreach ( self::get_sizes() as $size ) {
298	$variation = self::get_image( $attachment_id, $size );
299
300	// The get_image function returns false if the size doesn't exist for this attachment.
301	if ( $variation ) {
302	$variations[] = $variation;
303	}
304	}
305
306	return $variations;
307	}
308
309	/**
310	* Check original size of image. If original image is too small, return false, else return true.
311	*
312	* Filters a list of variations by a certain set of usable dimensions.
313	*
314	* @param array $usable_dimensions {
315	* The parameters to check against.
316	*
317	* @type int $min_width Minimum width of image.
318	* @type int $max_width Maximum width of image.
319	* @type int $min_height Minimum height of image.
320	* @type int $max_height Maximum height of image.
321	* }
322	* @param array $variations The variations that should be considered.
323	*
324	* @return array Whether a variation is fit for display or not.
325	*/
326	public static function filter_usable_dimensions( $usable_dimensions, $variations ) {
327	$filtered = [];
328
329	foreach ( $variations as $variation ) {
330	$dimensions = $variation;
331
332	if ( self::has_usable_dimensions( $dimensions, $usable_dimensions ) ) {
333	$filtered[] = $variation;
334	}
335	}
336
337	return $filtered;
338	}
339
340	/**
341	* Filters a list of variations by (disk) file size.
342	*
343	* @param array $variations The variations to consider.
344	*
345	* @return array The validations that pass the required file size limits.
346	*/
347	public static function filter_usable_file_size( $variations ) {
348	foreach ( $variations as $variation ) {
349	// We return early to prevent measuring the file size of all the variations.
350	if ( self::has_usable_file_size( $variation ) ) {
351	return [ $variation ];
352	}
353	}
354
355	return [];
356	}
357
358	/**
359	* Retrieve the internal WP image file sizes.
360	*
361	* @return array An array of image sizes.
362	*/
363	public static function get_sizes() {
364	/**
365	* Filter: 'wpseo_image_sizes' - Determines which image sizes we'll loop through to get an appropriate image.
366	*
367	* @api array - The array of image sizes to loop through.
368	*/
369	return apply_filters( 'wpseo_image_sizes', [ 'full', 'large', 'medium_large' ] );
370	}
371
372	/**
373	* Grabs an image alt text.
374	*
375	* @param int $attachment_id The attachment ID.
376	*
377	* @return string The image alt text.
378	*/
379	public static function get_alt_tag( $attachment_id ) {
380	return (string) get_post_meta( $attachment_id, '_wp_attachment_image_alt', true );
381	}
382
383	/**
384	* Checks whether an img sizes up to the parameters.
385	*
386	* @param array $dimensions The image values.
387	* @param array $usable_dimensions The parameters to check against.
388	*
389	* @return bool True if the image has usable measurements, false if not.
390	*/
391	private static function has_usable_dimensions( $dimensions, $usable_dimensions ) {
392	foreach ( [ 'width', 'height' ] as $param ) {
393	$minimum = $usable_dimensions[ 'min_' . $param ];
394	$maximum = $usable_dimensions[ 'max_' . $param ];
395
396	$current = $dimensions[ $param ];
397	if ( ( $current < $minimum ) \|\| ( $current > $maximum ) ) {
398	return false;
399	}
400	}
401
402	return true;
403	}
404
405	/**
406	* Gets the post's first usable content image. Null if none is available.
407	*
408	* @param int\|null $post_id The post id.
409	*
410	* @return string\|null The image URL.
411	*/
412	public static function get_first_usable_content_image_for_post( $post_id = null ) {
413	$post = get_post( $post_id );
414
415	// We know get_post() returns the post or null.
416	if ( ! $post ) {
417	return null;
418	}
419
420	$image_finder = new WPSEO_Content_Images();
421	$images = $image_finder->get_images( $post->ID, $post );
422
423	return self::get_first_image( $images );
424	}
425
426	/**
427	* Gets the term's first usable content image. Null if none is available.
428	*
429	* @param int $term_id The term id.
430	*
431	* @return string\|null The image URL.
432	*/
433	public static function get_first_content_image_for_term( $term_id ) {
434	$term_description = term_description( $term_id );
435
436	// We know term_description() returns a string which may be empty.
437	if ( $term_description === '' ) {
438	return null;
439	}
440
441	$image_finder = new WPSEO_Content_Images();
442	$images = $image_finder->get_images_from_content( $term_description );
443
444	return self::get_first_image( $images );
445	}
446
447	/**
448	* Retrieves an attachment ID for an image uploaded in the settings.
449	*
450	* Due to self::get_attachment_by_url returning 0 instead of false.
451	* 0 is also a possibility when no ID is available.
452	*
453	* @param string $setting The setting the image is stored in.
454	*
455	* @return int\|bool The attachment id, or false or 0 if no ID is available.
456	*/
457	public static function get_attachment_id_from_settings( $setting ) {
458	$image_id = WPSEO_Options::get( $setting . '_id', false );
459	if ( ! $image_id ) {
460	$image = WPSEO_Options::get( $setting, false );
461	if ( $image ) {
462	// There is not an option to put a URL in an image field in the settings anymore, only to upload it through the media manager.
463	// This means an attachment always exists, so doing this is only needed once.
464	$image_id = self::get_attachment_by_url( $image );
465	WPSEO_Options::set( $setting . '_id', $image_id );
466	}
467	}
468
469	return $image_id;
470	}
471
472	/**
473	* Retrieves the first possible image url from an array of images.
474	*
475	* @param array $images The array to extract image url from.
476	*
477	* @return string\|null The extracted image url when found, null when not found.
478	*/
479	protected static function get_first_image( $images ) {
480	if ( ! is_array( $images ) ) {
481	return null;
482	}
483
484	$images = array_filter( $images );
485	if ( empty( $images ) ) {
486	return null;
487	}
488
489	return reset( $images );
490	}
491	}
492