【WordPress】wp_get_attachment_image・wp_get_attachment_url で添付画像を取得・表示する方法

WordPress のテーマを自作していると、メディアライブラリにアップロードした画像を、テンプレート内でプログラムから表示したい場面が出てきます。カスタムフィールドに保存した画像 ID から <img> を組み立てたり、画像の URL だけを取り出して背景画像に使ったり——こうした処理を担うのが wp_get_attachment_image をはじめとする「添付ファイル」系の関数です。この記事では、画像 ID から <img> タグごと出力する wp_get_attachment_image、URL を取得する wp_get_attachment_url と wp_get_attachment_image_src の使い方を、実例とともに解説します。

WordPress では画像も「投稿（添付ファイル）」として管理される

WordPress では、メディアライブラリにアップロードした画像は「添付ファイル（attachment）」という種類の投稿として保存され、一つひとつに固有の ID（添付ファイル ID）が割り振られます。これらの関数は、この ID を手がかりに画像の情報を取り出す仕組みになっています。そのため、まず「表示したい画像の ID をどう手に入れるか」がスタート地点になります。

ID は、メディアライブラリで画像を開いたときの URL に含まれる item=123 の数字などで確認できます。実際の開発では、カスタムフィールドやテーマオプションに保存した画像 ID を読み出して使うことが多くなります。

wp_get_attachment_image で img タグごと出力する

wp_get_attachment_image は、添付ファイル ID から <img> タグの HTML を丸ごと組み立てて返してくれる関数です。src はもちろん、レスポンシブ表示のための srcset や sizes、alt 属性まで自動で付けてくれるため、自分でタグを書くより安全で確実です。

<?php
$image_id = 123; // 表示したい画像の添付ファイル ID

// img タグの HTML 文字列が返るので echo で出力する
echo wp_get_attachment_image( $image_id, 'medium' );

第1引数に画像の ID、第2引数に表示サイズを渡します。この関数は HTML 文字列を「返す」だけで自動的には表示しないため、echo を付けて出力する点に注意してください。出力される <img> には、その画像にメディアライブラリで設定した代替テキストが alt 属性として自動で入ります。

サイズを指定する

第2引数のサイズには、WordPress が用意する画像サイズの名前を文字列で渡します。代表的なものは次のとおりです。

これらの既定サイズのほか、テーマで add_image_size() を使って追加した独自サイズの名前も指定できます。また array( 300, 200 ) のように幅と高さの配列を渡すこともできますが、その場合は最も近い登録済みサイズの画像が選ばれる点を覚えておきましょう。

class や alt を指定する

第3引数は使わない値（後述の通常は false）で、第4引数に属性を連想配列で渡すと、class や alt などを上書きできます。独自のクラスを付けてスタイルを当てたいときに便利です。

<?php
echo wp_get_attachment_image(
    $image_id,
    'large',
    false, // アイコン用フラグ。画像なので false
    array(
        'class' => 'hero__image',
        'alt'   => 'トップページのメインビジュアル',
        'loading' => 'lazy',
    )
);

第3引数の $icon は、添付ファイルが画像でないとき（PDF など）にメディアアイコンを表示するかどうかのフラグです。通常の画像表示では false のままで問題ありません。

wp_get_attachment_url で URL だけを取得する

背景画像に使いたい、<a> のリンク先にしたい、といった場合は <img> タグではなく画像の URL だけがほしくなります。そのときは wp_get_attachment_url を使います。引数は添付ファイル ID の1つだけで、その画像の原寸（フルサイズ）の URL を返します。

<?php
$url = wp_get_attachment_url( $image_id );

// 取得した URL を背景画像に使う例
// esc_url() で URL を安全にエスケープしてから出力する
?>
<div class="hero" style="background-image: url('<?php echo esc_url( $url ); ?>');">
</div>

取得した URL を HTML に出力するときは、必ず esc_url() を通して安全にエスケープしましょう。なお、その画像が存在しない（ID が間違っているなど）ときは false が返るため、出力前に値があるかを確認しておくと安全です。

wp_get_attachment_image_src で特定サイズの URL とサイズを得る

wp_get_attachment_url は常にフルサイズの URL を返しますが、「中サイズの URL がほしい」「画像の幅と高さも一緒に知りたい」というときは wp_get_attachment_image_src を使います。この関数は、URL・幅・高さなどをまとめた配列を返します。

<?php
// 第2引数にサイズを指定。戻り値は [URL, 幅, 高さ, リサイズ済みか] の配列
$image = wp_get_attachment_image_src( $image_id, 'medium' );

if ( $image ) {
    $url    = $image[0];
    $width  = $image[1];
    $height = $image[2];
    ?>
    <img src="<?php echo esc_url( $url ); ?>"
         width="<?php echo esc_attr( $width ); ?>"
         height="<?php echo esc_attr( $height ); ?>"
         alt="">
    <?php
}

戻り値の配列は、添字 0 が URL、1 が幅、2 が高さ、3 がリサイズされた画像かどうかの真偽値です。幅と高さを <img> に指定しておくと、画像読み込み時のレイアウトのガタつき（CLS）を防ぐ効果があります。

カスタムフィールドに保存した画像 ID を表示する

実際の開発でもっとも多いのが、投稿のカスタムフィールドに保存しておいた画像 ID を読み出して表示するパターンです。get_post_meta で ID を取得し、それを wp_get_attachment_image に渡すだけで、その投稿専用の画像を表示できます。

<?php
// カスタムフィールド 'sub_image' に保存した画像 ID を取り出す
$image_id = get_post_meta( get_the_ID(), 'sub_image', true );

// ID が保存されているときだけ画像を表示する
if ( $image_id ) {
    echo wp_get_attachment_image( $image_id, 'large', false, array(
        'class' => 'post__sub-image',
    ) );
}

if ( $image_id ) でチェックしているのは、カスタムフィールドが未設定の投稿で空の <img> が出力されるのを防ぐためです。値が無いときは何も表示しない、という分岐を入れておくと安全です。

画像が表示されないときに確認すること

関数を呼んでいるのに画像が出ない場合、原因はいくつかのパターンに絞られます。順番に確認していきましょう。

渡している ID が添付ファイルの ID になっているか

もっとも多いのが ID の取り違えです。これらの関数が必要とするのは「画像（添付ファイル）の ID」であって、その画像を貼り付けた記事の投稿 ID ではありません。カスタムフィールドに画像の URL を保存している場合も、ID を期待するこれらの関数には渡せないため、attachment_url_to_postid() で URL から ID に変換するなどの対応が必要です。

echo を付け忘れていないか

wp_get_attachment_image は HTML を画面に出力するのではなく、文字列として返す関数です。echo を付けずに呼ぶと、画像は組み立てられているのに画面には何も出ません。「the_ で始まる関数は表示、get_ を含む関数は取得（要 echo）」という WordPress の命名の傾向を意識すると、付け忘れを減らせます。

まとめ

添付ファイル系の関数を使い分けると、画像をプログラムから柔軟に扱えるようになります。要点を振り返ります。

• WordPress の画像は「添付ファイル」という投稿として ID で管理されている
• wp_get_attachment_image は ID から <img> タグごと生成する（srcset・alt も自動）
• 第2引数でサイズ、第4引数の連想配列で class や alt を指定できる
• URL だけほしいときは wp_get_attachment_url（常にフルサイズ）
• 特定サイズの URL と幅・高さは wp_get_attachment_image_src が配列で返す
• カスタムフィールドの画像 ID は get_post_meta で取り出して渡す
• これらは文字列を返す関数なので echo を忘れない

まずは wp_get_attachment_image で <img> を出力するところから始め、URL だけが必要になったら wp_get_attachment_url や wp_get_attachment_image_src に切り替える、と覚えておくと迷いません。

参考ページ

• wp_get_attachment_image() – WordPress Developer Resources
• wp_get_attachment_url() – WordPress Developer Resources
• wp_get_attachment_image_src() – WordPress Developer Resources