# media_sideload_image()

URL: https://chugunov.pro/api-wordpress/functions/media_sideload_image/
Проверено на WordPress 6.9, обновлено 06.08.2026.
Источник: независимый русскоязычный справочник chugunov.pro. Не является официальной документацией WordPress.

Тип: функция.
Появился в версии: 4.8.0.

## Сигнатура

```php
media_sideload_image( string $file, int $post_id, string $desc = null, string $return_type = 'html' ): string|int|WP_Error
```

## Описание

Скачивает изображение по указанному URL, сохраняет его как вложение и при необходимости прикрепляет к записи.

## Параметры

- `$file` `string` — обязательный. URL изображения для скачивания.
- `$post_id` `int` — необязательный. ID записи, с которой должно быть связано медиа.
- `$desc` `string` — необязательный, по умолчанию `null`. Описание изображения.
- `$return_type` `string` — необязательный, по умолчанию `'html'`. Принимает 'html' (HTML тега изображения), 'src' (URL) или 'id' (ID вложения). Значение по умолчанию 'html'.

## Возвращаемое значение

`string|int|WP_Error` — WP_Error

## Исходный код

Файл: `wp-admin/includes/media.php:1032`

```php
function media_sideload_image( $file, $post_id = 0, $desc = null, $return_type = 'html' ) {
	if ( ! empty( $file ) ) {

		$allowed_extensions = array( 'jpg', 'jpeg', 'jpe', 'png', 'gif', 'webp' );

		/**
		 * Filters the list of allowed file extensions when sideloading an image from a URL.
		 *
		 * The default allowed extensions are:
		 *
		 *  - `jpg`
		 *  - `jpeg`
		 *  - `jpe`
		 *  - `png`
		 *  - `gif`
		 *  - `webp`
		 *
		 * @since 5.6.0
		 * @since 5.8.0 Added 'webp' to the default list of allowed file extensions.
		 *
		 * @param string[] $allowed_extensions Array of allowed file extensions.
		 * @param string   $file               The URL of the image to download.
		 */
		$allowed_extensions = apply_filters( 'image_sideload_extensions', $allowed_extensions, $file );
		$allowed_extensions = array_map( 'preg_quote', $allowed_extensions );

		// Set variables for storage, fix file filename for query strings.
		preg_match( '/[^\?]+\.(' . implode( '|', $allowed_extensions ) . ')\b/i', $file, $matches );

		if ( ! $matches ) {
			return new WP_Error( 'image_sideload_failed', __( 'Invalid image URL.' ) );
		}

		$file_array         = array();
		$file_array['name'] = wp_basename( $matches[0] );

		// Download file to temp location.
		$file_array['tmp_name'] = download_url( $file );

		// If error storing temporarily, return the error.
		if ( is_wp_error( $file_array['tmp_name'] ) ) {
			return $file_array['tmp_name'];
		}

		// Do the validation and storage stuff.
		$id = media_handle_sideload( $file_array, $post_id, $desc );

		// If error storing permanently, unlink.
		if ( is_wp_error( $id ) ) {
			@unlink( $file_array['tmp_name'] );
			return $id;
		}

		// Store the original attachment source in meta.
		add_post_meta( $id, '_source_url', $file );

		// If attachment ID was requested, return it.
		if ( 'id' === $return_type ) {
			return $id;
		}

		$src = wp_get_attachment_url( $id );
	}

	// Finally, check to make sure the file has been saved, then return the HTML.
	if ( ! empty( $src ) ) {
		if ( 'src' === $return_type ) {
			return $src;
		}

		$alt  = isset( $desc ) ? esc_attr( $desc ) : '';
		$html = "<img src='$src' alt='$alt' />";

		return $html;
	} else {
		return new WP_Error( 'image_sideload_failed' );
	}
}
```

## История изменений

- 5.8.0 — Added 'webp' to the default list of allowed file extensions.
- 5.4.0 — The original URL of the attachment is stored in the _source_url post meta value.
- 5.3.0 — The $post_id parameter was made optional.
- 4.8.0 — Introduced the 'id' option for the $return_type parameter.
- 4.2.0 — Introduced the $return_type parameter.
- 2.6.0 — Introduced.

## Связанные

Использует: [`media_handle_sideload`](https://chugunov.pro/api-wordpress/functions/media_handle_sideload/), [`media_handle_upload`](https://chugunov.pro/api-wordpress/functions/media_handle_upload/), [`download_url`](https://chugunov.pro/api-wordpress/functions/download_url/), [`wp_get_attachment_url`](https://chugunov.pro/api-wordpress/functions/wp_get_attachment_url/), [`add_post_meta`](https://chugunov.pro/api-wordpress/functions/add_post_meta/), [`__`](https://chugunov.pro/api-wordpress/functions/__/), [`wp_basename`](https://chugunov.pro/api-wordpress/functions/wp_basename/), [`esc_attr`](https://chugunov.pro/api-wordpress/functions/esc_attr/), [`apply_filters`](https://chugunov.pro/api-wordpress/functions/apply_filters/), [`is_wp_error`](https://chugunov.pro/api-wordpress/functions/is_wp_error/), `WP_Error::__construct`.

Оригинал в официальной документации: https://developer.wordpress.org/reference/functions/media_sideload_image/