Tips

アイキャッチ画像をコードで設定する方法取り込みと set_post_thumbnail

画像ファイルをメディアライブラリに取り込み、投稿のアイキャッチに設定するコードを解説。media_handle_sideload と media_handle_upload の違い、必要な require、失敗時の WP_Error を実行結果つきで整理します。

結論

画像を取り込んでアイキャッチにする流れは、3段階です。

  1. 画像をメディアライブラリに登録して、添付ファイルIDを得る。
  2. set_post_thumbnail( $post_id, $attachment_id ) でアイキャッチに設定する(内部では _thumbnail_id というメタが保存される)。
  3. 表示側で 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と公式サイトに記載されています。

No.1WordPressサイトの国内シェア(Dataprovider.com調べ・2025年6月)
99.99%以上サーバー月間稼働率を保証
99%以上WordPressへの攻撃を未然に防ぐ(2024年9月15日〜11月15日の当社調べ)

選ばれるポイント

  • WordPressサイトの国内シェアNo.1。実績で選びたいときの安心材料(Dataprovider.com調べ、2025年6月)
  • サイトが止まりにくい。月間稼働率99.99%以上を保証し、下回ると月額費用の一部を返金
  • 攻撃に強い。WordPressを狙った攻撃の99%以上を未然に防ぐ機能(2024年9月15日〜11月15日の当社調べ)
  • ドメイン代を節約できる。独自ドメインが永久無料(対象ドメイン・契約期間などの条件あり)
  • テーマ選びも安心。人気テーマ「Cocoon」の開発・提供元が運営
  • 10日間の無料お試しで、契約前に操作や表示の速さを確かめられる

10日間の無料お試しで、契約前に試せます

公式サイトを見る

10日間無料でお試し

エックスサーバー

広告(アフィリエイト)を含みます。特長は2026年11月8日時点の公式サイトの記載で、数値・順位は各調査・調べの時点のものです。料金・条件は公式サイトでご確認ください。

アイキャッチ画像をコードで設定する方法の関連項目

出典(一次情報)

本記事は情報提供を目的としています。WordPress本体やテーマ・プラグインのバージョンによって動作が異なる場合があるため、本番環境に反映する前に、必ずテスト環境で動作を確認してください。

PR当サイトはアフィリエイト広告を利用しています。掲載内容は広告主から依頼・指示を受けたものではなく、筆者の調査・体験にもとづきます。