media_handle_upload() の使い方｜説明・引数・注意点

説明

基本構文

media_handle_upload( string $file_id, int $post_id, array $post_data = array(), array $overrides = array( 'test_form' => false ) ): int|WP_Error

引数

• $file_id：$_FILES のキー名
• $post_id：紐付ける投稿のID
• $post_data：添付ファイルの情報
• $overrides：アップロードの上書き設定

戻り値

添付ファイルのID。失敗時は WP_Error。

使い方（サンプル）

require_once ABSPATH . 'wp-admin/includes/file.php';
require_once ABSPATH . 'wp-admin/includes/media.php';
require_once ABSPATH . 'wp-admin/includes/image.php';
$id = media_handle_upload( 'my_file', 0 );

注意点

• フロントエンドで使うには、管理画面用のファイルを手動で読み込む必要があります。
• ファイル種別やサイズの検証、nonce検証を必ず行います。

実務での使いどころ

• フォームから送られたファイルを受け取り、メディアとして登録するとき。
• フロントのフォームで、画像のアップロードを受け付けるとき。

よくあるミスと対処

• フロント側で、管理画面用のファイル（file.php・image.php・media.php）を、読み込んでいない。関数が未定義になる。
• $file_id を、$_FILES のキーとして指定していない。
• 戻り値が WP_Error のときを、考えていない。
• 権限や、nonceの確認をしていない。

NG例

$id = media_handle_upload( 'photo', 0 ); // 必要なファイルを読み込んでいない

OK例

require_once ABSPATH . 'wp-admin/includes/file.php';
require_once ABSPATH . 'wp-admin/includes/image.php';
require_once ABSPATH . 'wp-admin/includes/media.php';

$id = media_handle_upload( 'photo', 0 );
if ( is_wp_error( $id ) ) {
	return;
}

使い分け早見表

関連項目

wp_handle_upload()、wp_insert_attachment()

公式リファレンス：media_handle_upload() | Function | WordPress Developer Resources