アイキャッチ画像をコードで設定する方法取り込みと set_post_thumbnail
画像ファイルをメディアライブラリに取り込み、投稿のアイキャッチに設定するコードを解説。media_handle_sideload と media_handle_upload の違い、必要な require、失敗時の WP_Error を実行結果つきで整理します。
結論
画像を取り込んでアイキャッチにする流れは、3段階です。
- 画像をメディアライブラリに登録して、添付ファイルIDを得る。
set_post_thumbnail( $post_id, $attachment_id )でアイキャッチに設定する(内部では_thumbnail_idというメタが保存される)。- 表示側で
has_post_thumbnail()とthe_post_thumbnail()を使う。
1 の方法は、入力元で選びます。
| 入力元 | 使う関数 | 備考 |
|---|---|---|
フォームからのアップロード($_FILES) |
media_handle_upload() |
multipart/form-data の form が必要 |
| サーバー上の一時ファイルや、配列で渡せるファイル | media_handle_sideload() |
name と tmp_name を持つ配列 |
| 外部 URL の画像 | media_sideload_image() |
戻り値の形式を id にできる |
フロントエンドや CLI から使う場合は、wp-admin/includes/ の3ファイル(file.php、image.php、media.php)の読み込みが必要です。
原因・仕組み
公式リファレンスによると、media_handle_upload() は $_FILES の指定キーのファイルを処理して添付ファイルを作り、成功時は添付ファイルID、失敗時は WP_Error を返します。第2引数は親投稿のID(未添付なら 0)です。media_sideload_image() は URL を受け取り、第4引数で html、src、id のいずれかを返せます。失敗時は WP_Error です。いずれも、フロントエンドで使う前に上記3ファイルを読み込みます。
どの関数も、WordPress が許可する MIME タイプ・拡張子のチェックを通ります。許可されないファイルは WP_Error になるため、任意の PHP ファイルなどはアップロードできません。
手順(サンプルコード)
ファイル配列を受け取って取り込み、アイキャッチに設定する関数です。
function ks_set_featured_from_file( $post_id, array $file ) {
require_once ABSPATH . 'wp-admin/includes/image.php';
require_once ABSPATH . 'wp-admin/includes/file.php';
require_once ABSPATH . 'wp-admin/includes/media.php';
if ( ! current_user_can( 'edit_post', $post_id ) ) {
return new WP_Error( 'ks_cap', '権限がありません' );
}
$attachment_id = media_handle_sideload( $file, $post_id, null, array( 'post_title' => 'ks featured' ) );
if ( is_wp_error( $attachment_id ) ) {
return $attachment_id;
}
if ( ! set_post_thumbnail( $post_id, $attachment_id ) ) {
return new WP_Error( 'ks_thumb', 'アイキャッチを設定できませんでした' );
}
return $attachment_id;
}
フォームから受け取る場合は、$_FILES['ks_image'] を使い、media_handle_upload( 'ks_image', $post_id ) を呼びます。このとき nonce の検証と、current_user_can( 'upload_files' ) などの権限確認を行ってください。
// フォーム側(nonce 付き)
// <form method="post" enctype="multipart/form-data"> ... wp_nonce_field( 'ks_upload', 'ks_nonce' ) ... </form>
if ( isset( $_POST['ks_nonce'] ) && wp_verify_nonce( sanitize_text_field( wp_unslash( $_POST['ks_nonce'] ) ), 'ks_upload' ) && current_user_can( 'upload_files' ) && current_user_can( 'edit_post', $post_id ) ) {
$id = media_handle_upload( 'ks_image', $post_id );
}
動作確認(検証環境と結果)
WordPress 7.1.2、PHP 8.2.12(GD 拡張を有効化)、MariaDB 10.4.32 で、上の関数を実行しました(php -d extension=gd run.php featured-image-set-by-code.php)。
- 設定前の
has_post_thumbnail()は false、設定後は true。 get_post_thumbnail_id()と、メタ_thumbnail_idの値が、取り込んだ添付ファイルIDと一致した。get_the_post_thumbnail_url( $post_id, 'full' )は、.../uploads/2026/10/feat.pngを返した。get_the_post_thumbnail( $post_id, 'medium' )は、feat-300x225.pngを指すimgタグ(wp-post-imageクラス付き)を返した。- 拡張子
.phpのファイルを渡すと、「このファイルタイプをアップロードする権限がありません。」のWP_Errorになり、受理されなかった。
media_handle_upload() の実フォーム経由の動作($_FILES は CLI では再現できない)と、media_sideload_image() による外部 URL からの取得は、この環境では実行しておらず、未検証です。公式リファレンスの記載に基づいて記述しています。
アイキャッチ画像をコードで設定する方法の注意点
- 外部 URL から取り込む場合、URL が信頼できるものか確認します。ユーザー入力の URL をそのまま渡すと、意図しない通信の原因になります。
- 大量の画像を一括で取り込むと、タイムアウトします。WP-CLI や、分割処理を使います。
set_post_thumbnail()は、投稿タイプがthumbnailをサポートしていないと、表示側で使えません。- 公式リファレンスによると、
set_post_thumbnail()は、失敗時だけでなく、すでに同じIDが設定済みのときもfalseを返します。上のコードのようにfalseをエラー扱いにすると、再実行時に誤って失敗と判定されるため、必要ならget_post_thumbnail_id()で先に確認します。trueや初回のメタIDなど、成功時の戻り値は一定でないことにも注意してください。`n- 取り込んだ画像のサイズ別ファイルは、そのときに登録されているサイズで作られます(add_image_size が反映されない原因と再生成)。 - 画像の
altは、update_post_meta( $id, '_wp_attachment_image_alt', $text )で設定できます。
アイキャッチ画像をコードで設定する方法でよくあるミス
wp-admin/includes/の3ファイルを読み込まず、「undefined function」の致命的エラーになる。$_FILESのキー名と、media_handle_upload()に渡す名前が一致していない。- form に
enctype="multipart/form-data"が無く、$_FILESが空。 - 戻り値の
WP_Errorを確認せずに、そのままset_post_thumbnail()に渡す。 - nonce と権限の確認を省略する。
アイキャッチ画像をコードで設定する方法のチェックリスト
- 3つの include を入れたか。
- 戻り値を
is_wp_error()で確認したか。 - nonce と権限(
upload_files、edit_post)を確認したか。 - 投稿タイプが
thumbnailをサポートしているか。 - 取り込み後、メディアライブラリと表示を確認したか。
アイキャッチ画像をコードで設定する方法のFAQ(よくある質問)
Q. 既存のメディアを、別の投稿のアイキャッチにするには?
A. 取り込みは不要です。添付ファイルIDで set_post_thumbnail() を呼びます(set_post_thumbnail() の使い方|説明・引数・注意点)。
Q. アイキャッチを外すには?
A. delete_post_thumbnail( $post_id ) を使います。本検証では実行していません。
Q. 取り込みに失敗する理由は?
A. ファイル種別の制限、容量、権限、ディスク容量などが考えられます。WP_Error のメッセージを確認してください。
筆者の見解(アイキャッチ画像をコードで設定する方法)
画像の取り込み処理は、成功のコードより、失敗時の扱いに品質の差が出ると考えます。WP_Error をログに残し、ユーザーには簡潔なメッセージを返す設計にしておくと、運用中の原因調査が楽になります。また、権限とnonce は、アップロード系の処理では最初に書くべき部分だと思います。
PR エックスサーバー
WordPressを、速く・止まらずに運営したい方へ
サーバー選びを間違えると、表示が遅い・サイトが止まるリスクがあります
こんなお悩みはありませんか?
- どのレンタルサーバーを選べばよいか分からない
- 表示が遅い・サイトが落ちるのが心配
- WordPressの設定やセキュリティに自信がない
サーバーは、あとから乗り換えると、データの移行やドメインの設定に手間がかかります。表示が遅い、突然止まるといったトラブルは、訪問者が離れる原因にもなります。最初に、稼働率の保証や実績を確認して選ぶのが安全です。
エックスサーバーなら、WordPressの運営に強いレンタルサーバーを、迷わず選べます。国内でWordPressを利用して運用されているサイトの集計(Dataprovider.com調べ、2025年6月)で、国内シェアNo.1と公式サイトに記載されています。
選ばれるポイント
- WordPressサイトの国内シェアNo.1。実績で選びたいときの安心材料(Dataprovider.com調べ、2025年6月)
- サイトが止まりにくい。月間稼働率99.99%以上を保証し、下回ると月額費用の一部を返金
- 攻撃に強い。WordPressを狙った攻撃の99%以上を未然に防ぐ機能(2024年9月15日〜11月15日の当社調べ)
- ドメイン代を節約できる。独自ドメインが永久無料(対象ドメイン・契約期間などの条件あり)
- テーマ選びも安心。人気テーマ「Cocoon」の開発・提供元が運営
- 10日間の無料お試しで、契約前に操作や表示の速さを確かめられる
10日間の無料お試しで、契約前に試せます
10日間無料でお試し
広告(アフィリエイト)を含みます。特長は2026年11月8日時点の公式サイトの記載で、数値・順位は各調査・調べの時点のものです。料金・条件は公式サイトでご確認ください。
アイキャッチ画像をコードで設定する方法の関連項目
- set_post_thumbnail() の使い方|説明・引数・注意点
- media_handle_upload() の使い方|説明・引数・注意点
- wp_handle_upload() の使い方|説明・引数・注意点
- has_post_thumbnail() の使い方|説明・引数・注意点
- the_post_thumbnail() の使い方|説明・引数・注意点
出典(一次情報)
本記事は情報提供を目的としています。WordPress本体やテーマ・プラグインのバージョンによって動作が異なる場合があるため、本番環境に反映する前に、必ずテスト環境で動作を確認してください。