Rapls PDF Image Creator : PDFのサムネイル画像を自動生成するプラグイン

Rapls PDF Image Creator
2026.05.01
  1. PLUGIN : Rapls PDF Image Creator
  2. WHY : 真っ白なサムネイルに気づくということ
  3. DEMO : PDF のサムネイル自動生成
  4. INSTALLATION : 設置方法
    1. 動作要件
    2. サーバー要件の確認
    3. セットアップ手順
  5. FEATURES : 機能一覧
    1. 1. PDF アップロード時の自動サムネイル生成
    2. 2. アイキャッチ画像（Featured Image）として自動登録
    3. 3. 複数サイズの自動生成
    4. 4. メディアライブラリの統合
    5. 5. エディター統合（クラシック・ブロック両対応）
    6. 6. Bulk Generate（既存 PDF の一括処理）
    7. 7. 柔軟な出力フォーマット（JPEG / PNG / WebP）
    8. 8. CMYK / PDF/X 対応とカラーマネジメント
    9. 9. アンインストール時のクリーンアップ
  6. SETTINGS : プラグイン設定画面
    1. Image Settings タブ
    2. Display Settings タブ
    3. Insert Settings タブ
    4. Bulk Generate タブ
    5. Status タブ
    6. サイトヘルス連携（1.3.0 で追加）
    7. 有効化時の警告（1.3.0 で追加）
  7. TEMPLATE : テンプレート内での出力方法
    1. サムネイル付きリンクを表示
    2. 投稿に添付された PDF をすべて表示
    3. アイキャッチが PDF サムネイルの場合の特別処理
  8. SHORTCODES : ショートコード
    1. サムネイル画像のみ
    2. サムネイル付きリンク（PDF へ）
    3. サムネイル URL のみ取得
    4. ダウンロードリンク（サムネイル付き）
  9. FAQ : よくある質問
    1. サーバー要件は何ですか？
    2. サーバーが対応しているか確認するには？
    3. インストール前の PDF のサムネイルも作れますか？
    4. 画像フォーマットは何が選べますか？
    5. アンインストール時にサムネイルは消えますか？
    6. PDF の何ページ目をサムネイルにしますか？
    7. CMYK の PDF がちゃんとサムネイルになりません（真っ黒）
    8. サムネイルの色が元の PDF より鮮やかになります
    9. サムネイルが完全に真っ白になります
    10. PDF をアップロードしてもサムネイルができません
    11. 大量の PDF を一括処理するときの注意点は？
    12. 画像が荒い場合はどうすればいいですか？
    13. 似たプラグインとの違いは？
    14. サポートはどこで受けられますか？
  10. ADVANCED FILTERS : フィルターフック
    1. 何ページ目を使うかを変更
    2. 最大サイズの動的変更
    3. 描画解像度の動的変更（1.2.0 以降）
    4. 品質を動的に変更
    5. 出力フォーマットの動的変更
    6. 背景色の指定
    7. img タグの属性を変更
    8. カラー変換方式の切り替え（1.1.0 以降）
    9. ICC プロファイルの探索パス（1.1.0 以降）
    10. レンダリングインテントの変更（1.1.0 以降）
    11. 透明部分の合成先の背景色（1.1.0 以降）
    12. policy.xml の探索パス（1.3.0 以降）
    13. 挿入 HTML のカスタマイズ
  11. ACTION HOOKS : アクションフック
    1. 生成前の処理
    2. 生成成功時の処理
    3. 生成失敗時の処理
  12. CHANGE LOG : バージョン履歴
  13. RELATED PAGES : 関連ページ

PLUGIN : Rapls PDF Image Creator

Rapls PDF Image Creator wordpress.org から最新版をダウンロード

WordPress.org 公式リポジトリで公開しているプラグインの技術リファレンスページです。WordPress のメディアライブラリに PDF をアップロードすると、1 ページ目のカバー画像を ImageMagick で自動生成し、その PDF のアイキャッチ画像（featured image）として登録します。CMYK 色空間の PDF や PDF/X-1:2001 形式（印刷入稿用）にも対応しているため、印刷会社からの入稿用 PDF をそのまま公開しても、サムネイルが真っ黒になる問題を回避できます。1.1.0 からは ICC プロファイルを通したカラーマネジメント変換に対応し、印刷用 PDF の色が実際より鮮やかに転ぶ問題も解消しました。

ソースコード：GitHub – rapls/rapls-pdf-image-creator

開発の経緯（CMYK PDF 問題の解決、PDF-X ファイル対応の苦労話）は 開発者ガイドをご参照ください。

WHY : 真っ白なサムネイルに気づくということ

古い Ghostscript は、描けなかったページをエラーとして報告しません。正しい寸法の、真っ白なページを返します。受け取ったものをそのまま保存する実装は——WordPress 標準の PDF プレビューを含めて——その白い画像を保存します。ファイルはできます。サイズもあります。サムネイルが完成したように見えます。

実測しました。Ghostscript 9.27 のサーバーで、1 回のアップロードの中で比べています。同じ PDF、同じ瞬間、同じサーバー状態です。

生成したものバイト数標準偏差中身
WordPress 標準の PDF プレビュー16,9100全画素が同じ 1 色（白紙）
Rapls PDF Image Creator274,8000.310絵が出ている

標準偏差 0 は「全画素が同じ値」という意味です。推測ではなく、画素を数えた結果です。

このプラグインがしているのは、難しいことではありません。受け取ったものを見る——それだけです。

  • 返ってきたものを検査します。真っ白に描画されたページは、保存せずに拒否します。メディアライブラリには WordPress の PDF アイコンが出て、Status タブに理由が表示されます。白い四角より、そちらのほうが役に立ちます。
  • 原因のほうを回避します。Ghostscript 9.27 以前は、透明グループの中に画像を持つ PDF——PowerPoint や Illustrator の書き出しでよくある構造——で失敗します。透明効果を無効にして描き直すと、同じページが 11,018 バイトの白紙から 624,109 バイトの絵になりました。再試行としてのみ行います。一度で描けたページには触れません。
  • 判定はすべて実測です。PDF が読めるか、CMYK が描けるか、ページ指定が効くか——バージョン番号を読むのではなく、その場で描画して答えます。Status タブには、このサーバーの ImageMagick が使う Ghostscript のデバイス名まで出ます。
  • ホスティング事業者に何を頼めばいいかを表示します。「PDF に対応していない」「ページが大きすぎる」「アップロードフォルダーに書き込めない」「ファイルが見つからない」は、4 つの別々の問題で、依頼する内容も 4 通りです。
  • カラーマネジメントは本物で、しかも軽い。CMYK は ICC プロファイルを通して変換します（緑が蛍光色に転ぶ簡易変換ではなく）。同梱している sRGB プロファイルは 3KB です。登録サイズすべてに 64KB が埋め込まれる類のものではありません。
  • プロセスを一切起動しません。exec() もシェルも使いません。制限の厳しい共有ホスティングでも動きます。

詳しい計測記録は開発者ガイドにあります。

DEMO : PDF のサムネイル自動生成

メディアライブラリのAfter比較

PDF ファイルをアップロードすると、1 ページ目を JPEG / PNG / WebP に変換してサムネイルとして登録します。メディアライブラリでも、デフォルトの汎用 PDF アイコンの代わりに実際のサムネイルが表示されます。

例：catalog-2026.pdf をアップロードすると、catalog-2026-pdf-thumbnail.jpg というファイル名でフルサイズ画像が作られ、さらに WordPress に登録されている各サイズ（large、medium、thumbnail 等）も自動生成されます。

INSTALLATION : 設置方法

動作要件

  • WordPress 5.0 以上
  • PHP 7.4 以上
  • ImageMagick + Imagick PHP 拡張モジュール（PDF サポート付き）

サーバー要件の確認

このプラグインを動作させるには、サーバーに ImageMagick がインストールされていて、かつ Imagick PHP 拡張モジュールが PDF サポート付きで有効化されている必要があります。多くの共有レンタルサーバーでは標準で対応しています。

確認方法は 2 つあります。「ツール > サイトヘルス」の「PDF サムネイルの生成」項目（1.3.0 で追加）か、「設定 > Rapls PDF Image Creator > Status」タブです。どちらも同じ内容で、動かない場合はその理由と、ホスティング事業者に何を依頼すればよいかまで表示します。

セットアップ手順

  1. rapls-pdf-image-creator フォルダを /wp-content/plugins/ にアップロード
  2. WordPress 管理画面の「プラグイン」メニューから有効化
  3. 「設定 > Rapls PDF Image Creator」を開く
  4. Status タブ、または「ツール > サイトヘルス」で ImageMagick が利用可能か確認
  5. メディアライブラリに PDF をアップロードして動作確認

設定画面で生成サイズや品質を調整できますが、デフォルト設定のままでも動作します。

FEATURES : 機能一覧

1. PDF アップロード時の自動サムネイル生成

PDF をメディアライブラリにアップロードすると、その瞬間に 1 ページ目を画像化してサムネイルを生成します。手動操作は不要です。

2. アイキャッチ画像（Featured Image）として自動登録

生成された画像は、PDF 自身のアイキャッチ画像として自動登録されます。

  • get_post_thumbnail_id( $pdf_id ) でサムネイル ID を取得可能
  • wp_get_attachment_image( $pdf_id, 'medium' ) で直接表示可能
  • 投稿のアイキャッチ画像として PDF を選ぶことも可能

3. 複数サイズの自動生成

WordPress に登録されているすべての画像サイズで自動生成されます：

  • my-document-pdf-thumbnail.jpg（フルサイズ）
  • my-document-pdf-thumbnail-1024x768.jpg（large）
  • my-document-pdf-thumbnail-300x225.jpg（medium）
  • my-document-pdf-thumbnail-150x150.jpg（thumbnail）
  • テーマで追加されたカスタムサイズ

レスポンシブ画像（srcset）にも対応します。

4. メディアライブラリの統合

メディアライブラリで各 PDF が個別のサムネイルで表示されます。デフォルトの汎用 PDF アイコンの代わりになります。設定でこの機能をオフにすることもできます。

5. エディター統合（クラシック・ブロック両対応）

クラシックエディターおよびブロックエディターから「PDF を挿入」したときに、自動的にサムネイル付きのリンクとして挿入されます。

挿入オプションは 3 種類：

  • Image only：サムネイル画像のみ（PDF へのリンク付き）
  • Title link：タイトルテキスト＋ PDF へのリンク
  • Custom HTML：プレースホルダー（{thumbnail}、{pdf_url}、{pdf_title}）を使った独自 HTML
表示オプション

6. Bulk Generate（既存 PDF の一括処理）

プラグインを後から導入した場合の既存 PDF を一括処理できます。「設定 > Bulk Generate」タブから実行可能です。

一括生成タブの実行画面

7. 柔軟な出力フォーマット（JPEG / PNG / WebP）

サムネイルの出力フォーマットを 3 種類から選べます：

  • JPEG：互換性が高い（デフォルト推奨）
  • PNG：透過背景が必要な場合
  • WebP：ファイルサイズ重視（モダンブラウザのみ）

8. CMYK / PDF/X 対応とカラーマネジメント

印刷入稿用の PDF（CMYK 色空間、PDF/X-1:2001 など）でも正しくサムネイルが生成されます。透明部分を背景色へ明示的に合成するため、印刷用 PDF が「真っ黒なサムネイル」になる問題を回避できます。

1.1.0 で、CMYK → sRGB の変換に ICC プロファイルを使うようになりました。それ以前は、インクの特性を無視した算術式で変換していたため、緑や青が蛍光色寄りに転ぶ問題がありました（例：#4BA958 が #5EDF54 になる）。サーバー上に ICC プロファイルがあれば、それを通したカラーマネジメント変換を行い、元の PDF に近い色で再現されます。

ICC プロファイルはプラグインに同梱していません。再配布条件の問題を避けるため、実行時にサーバー上のものを探して読み込みます。見つからない場合は従来どおり簡易変換で動作するので、プロファイルの無いサーバーでもサムネイル生成が止まることはありません。動作状況は「設定 > Rapls PDF Image Creator > Status」タブで確認できます。

既存のサムネイルは自動では作り直されません。1.1.0 へ更新したあと、色を反映するには「Bulk Generate」タブから再生成してください。従来の色のままにしたい場合は rapls_pdf_image_creator_color_conversion フィルターに 'naive' を指定します。

9. アンインストール時のクリーンアップ

プラグインアンインストール時に、生成したサムネイル画像を削除するかどうか選択できます。

  • デフォルト：アンインストール時に削除
  • オプション：「Keep Images on Uninstall」を ON にすれば保持

SETTINGS : プラグイン設定画面

WordPress の管理画面「設定 > Rapls PDF Image Creator」から設定します。
プラグイン設定画面（設定タブ）

Image Settings タブ

  • Max Width / Max Height：サムネイルの最大サイズ（100〜4096、デフォルト 1024 × 1024）。この 2 つは縮小しかしません。描画済みのページより大きな値を入れても、拡大はされません
  • Rendering Resolution（1.2.0 で追加）：PDF のページを描画する解像度（72〜600 DPI、デフォルト 150）。サムネイルを大きくしたいときに触るのはここです。1.2.0 より前は 150 DPI 固定で、A4 なら約 1240 × 1754 ピクセル。それを超える最大サイズを指定しても何も起きませんでした。値を上げると描画されるページ自体が大きくなり、そのうえで Max Width / Max Height が上限として効きます。生成時のメモリ使用量は解像度の 2 乗で増えるので、小さなサーバーでは段階的に上げてください
  • Quality：JPEG / WebP 品質（10〜100、デフォルト 90）
  • Format：JPEG / PNG / WebP
  • Background Color：透明部分の背景色（白 / 黒 / 透明）。JPEG は透明を保持できないため、JPEG と「透明」を組み合わせた場合は白が使われます
  • PDF Page：何ページ目を使うか（デフォルト：1 ページ目）

Display Settings タブ

  • Hide Thumbnails in Media Library：生成されたサムネイル画像をメディアライブラリで非表示にする（デフォルト：オン）
  • Replace Default PDF Icon：メディアライブラリのデフォルト PDF アイコンをサムネイルで置き換える（デフォルト：オン）
  • Allow PDF as Featured Image：PDF を投稿のアイキャッチ画像として選択可能にする（デフォルト：オン）
  • Keep Images on Uninstall：アンインストール時にサムネイル画像を保持する（デフォルト：オフ）

Insert Settings タブ

エディターからの挿入時の動作を設定します。

  • Insert Output Type：Image only / Title link / Custom HTML
  • Custom HTML Template（Custom 選択時）：{thumbnail}、{pdf_url}、{pdf_title} を使ってカスタマイズ

Bulk Generate タブ

既存 PDF のサムネイルを一括生成します。実行前に状態（処理対象数）を確認できます。

Status タブ

サーバー要件のチェック結果を表示します：

  • ImageMagick（Imagick PHP 拡張）の有無
  • PDF サポートの状態と、動かない理由（1.3.0 で拡充）：単に「利用不可」ではなく、拡張が入っていないのか、入っているが ImageMagick のセキュリティポリシーで PDF が禁止されているのかを区別して表示します。後者の場合は原因となっている policy.xml のパスも出します。依頼すべき内容が変わるためです
  • ImageMagick のバージョン
  • ICC カラーマネジメントの動作状況（1.1.0 で追加）：有効な場合は使用中のプロファイル名、無効な場合はその理由と対処方法
  • ImageMagick 6 の警告（1.1.0 で追加）：サーバーが ImageMagick 6 の場合のみ表示。CMYK の PDF が真っ白になる既知の問題と、ホスティング事業者へ依頼すべき内容を案内します
  • サポートリンク（Buy Me a Coffee、レビュー）

サイトヘルス連携（1.3.0 で追加）

「ツール > サイトヘルス」に 「PDF サムネイルの生成」 のテストを追加します。描画できない環境では「重大な問題」として表示され、理由と依頼内容がその場に出ます。プラグインの設定画面を開かなくても、困った人が最初に見る場所で分かるようにするためです。

「サイトヘルス > 情報」にも Rapls PDF Image Creator の節を追加します。プラグインのバージョン、PDF 描画の可否とその詳細、ImageMagick のバージョン、ICC カラーマネジメントの状態、描画解像度、最大サイズ、出力形式、アップロード時生成の可否が並びます。サポートに問い合わせるときは、この節をそのまま貼り付けてください。

有効化時の警告（1.3.0 で追加）

ImageMagick が使えないサーバーでも、有効化そのものは止めません。止めてしまうと Status 画面すら開けなくなるためです。代わりに、有効化した直後の管理画面に理由つきの警告を表示します。1.2.1 以前は何も言わずに有効化され、PDF をアップロードしてもサムネイルが出ず、理由もどこにも残りませんでした。

実際に PDF のアップロードでサムネイル生成に失敗した場合も記録され、同じ警告に「PDF がアップロードされましたが、この理由でサムネイルを生成できませんでした」の一文が加わります。警告は理由ごとに閉じられるので、いったん閉じたあとサーバー側の事情が変わって別の理由になれば、また表示されます。

TEMPLATE : テンプレート内での出力方法

サムネイル付きリンクを表示

$pdf_id = 123;
if ( rapls_pic_has_thumbnail( $pdf_id ) ) {
    echo '<a href="' . esc_url( wp_get_attachment_url( $pdf_id ) ) . '" target="_blank" class="pdf-link">';
    echo rapls_pic_get_thumbnail_image( $pdf_id, 'medium' );
    echo '</a>';
}

投稿に添付された PDF をすべて表示

$pdfs = get_posts( array(
    'post_type'      => 'attachment',
    'post_mime_type' => 'application/pdf',
    'post_parent'    => get_the_ID(),
    'posts_per_page' => -1,
) );

foreach ( $pdfs as $pdf ) {
    if ( rapls_pic_has_thumbnail( $pdf->ID ) ) {
        printf(
            '<a href="%s">%s</a>',
            esc_url( wp_get_attachment_url( $pdf->ID ) ),
            rapls_pic_get_thumbnail_image( $pdf->ID, 'thumbnail' )
        );
    }
}

アイキャッチが PDF サムネイルの場合の特別処理

$thumb_id = get_post_thumbnail_id( get_the_ID() );
$pdf_id = get_post( $thumb_id )->post_parent;
if ( $pdf_id && get_post_mime_type( $pdf_id ) === 'application/pdf' ) {
    echo '<a href="' . esc_url( wp_get_attachment_url( $pdf_id ) ) . '" target="_blank">';
    the_post_thumbnail();
    echo '</a>';
} else {
    the_post_thumbnail();
}

SHORTCODES : ショートコード

サムネイル画像のみ

[rapls_pdf_thumbnail id="123"]
[rapls_pdf_thumbnail id="123" size="medium"]

サムネイル付きリンク（PDF へ）

[rapls_pdf_clickable_thumbnail id="123"]

サムネイル URL のみ取得

[rapls_pdf_thumbnail_url id="123" size="medium"]

ダウンロードリンク（サムネイル付き）

[rapls_pdf_download_link id="123"]

FAQ : よくある質問

サーバー要件は何ですか？

ImageMagick + Imagick PHP 拡張モジュール（PDF サポート付き）が必要です。多くの共有レンタルサーバーで対応しています。

サーバーが対応しているか確認するには？

「ツール > サイトヘルス」の「PDF サムネイルの生成」項目（1.3.0 で追加）か、「設定 > Rapls PDF Image Creator > Status」タブを確認してください。どちらも、利用可能かどうかに加えて、利用できない場合はその理由を表示します。

インストール前の PDF のサムネイルも作れますか？

はい。Bulk Generate タブで一括処理できます。

画像フォーマットは何が選べますか？

JPEG、PNG、WebP の 3 種類から選べます。デフォルトは JPEG です。

アンインストール時にサムネイルは消えますか？

デフォルトでは消えます。「Keep Images on Uninstall」を ON にすると残ります。

PDF の何ページ目をサムネイルにしますか？

デフォルトは 1 ページ目（0-indexed の 0）です。フィルターで変更可能：

add_filter( 'rapls_pdf_image_creator_thumbnail_page', function( $page, $pdf_id ) {
    return 1; // 2 ページ目を使う
}, 10, 2 );

CMYK の PDF がちゃんとサムネイルになりません（真っ黒）

透明部分を背景色へ明示的に合成する処理が入っているため、印刷用 PDF（PDF/X-1:2001 等）でも真っ黒にはなりません。もし出力フォーマットに JPEG を選び、背景色に「透明」を指定していた場合、JPEG は透明を保持できないため以前は黒く塗り潰されていました。1.1.0 からはこの組み合わせで自動的に白へ切り替わります。

サムネイルの色が元の PDF より鮮やかになります

PDF が CMYK で作られていて、サーバーに ICC プロファイルが無い場合、簡易的な算術変換にフォールバックするため緑や青が強く出ます。「設定 > Rapls PDF Image Creator > Status」タブでカラーマネジメントの動作状況を確認してください。

サーバーに CMYK の ICC プロファイルを設置するか、rapls_pdf_image_creator_icc_paths フィルターでパスを指定すると、正確な色で再現されます。なお、この修正は 1.1.0 以降です。それ以前のバージョンで生成したサムネイルは、更新後に「Bulk Generate」タブから再生成してください。

サムネイルが完全に真っ白になります

原因は 2 つあり、対処が違います。どちらなのかは「設定 > Rapls PDF Image Creator > Status」タブが実測して表示します。1.3.2 以降、バージョン番号からの推測ではなく、テストページを実際に描画した結果を出しています。

1. ImageMagick が自分の書いた画像を読み戻せない

ImageMagick 6 は、CMYK と判定した PDF を Ghostscript の bmpsep8 デバイスで描画することがあります。ところがこのデバイスが出力する分版 BMP を、ImageMagick 自身の BMP リーダーが解釈できません。バージョンの組み合わせによって、読み込みがエラーになるか、中身が空の画像が返るかに分かれ、後者が真っ白なサムネイルになります。ImageMagick 7 は別のデバイスを使うため起きません。

ImageMagick 6 なら必ず起きる、というわけではありません。実測では 6.9.13-25 の環境で CMYK のページが正しく描画されました。使われるデバイスはビルドごとに違います。Status タブの「CMYK PDF の描画」に、このサーバーが使うデバイス名を表示するので、pamcmyk32 と出ていれば問題ありません。

デバイスの選択は PDF の中身から ImageMagick が自動で決めており、Imagick の API から上書きする手段がないため、この原因はプラグイン側では回避できません。ホスティング事業者に、次のいずれかを依頼してください。

  • ImageMagick をバージョン 7 に更新する
  • delegates.xml の ps:cmyk デリゲートを bmpsep8 から pamcmyk32 に変更する

RGB の PDF には影響しません。同じサイトで一部の PDF だけ真っ白になるのは、このためです。

2. Ghostscript が透明効果でつまずく

Ghostscript 9.27 以前は、透明グループの中に画像を持つ PDF——PowerPoint や Illustrator の書き出しでよくある構造——の描画に失敗し、エラーをひとつも出さないまま白紙を返します。Ghostscript 10 は同じファイルを警告ひとつ出さずに描画します。ファイルが壊れているわけではなく、PDF の解釈系が 10 系で全面的に書き直されたことによる差です。

1.4.1 以降、この原因は自動で回避します。ページが真っ白で返ってきたときに限り、透明効果を無効にして描き直します。実測では 11,018 バイトの白紙が 624,109 バイトの画像になりました。回避策が使われたサーバーでは、Status タブに「Ghostscript」の行が出ます。透明部分の見え方は本来と変わることがあるため、根本的な解決はホスティング事業者による Ghostscript の更新です。

どちらでもなく白いままの場合、1.4.0 以降は真っ白なページをサムネイルとして保存しません。かわりに WordPress の PDF アイコンが表示され、Status タブに理由が出ます。白い画像が保存されてしまうと「サムネイルはできている」ように見えてしまうためです。

なお、作り直したのに画面が白いままのときは、ブラウザーのキャッシュを疑ってください。1.4.0 以前は再生成したサムネイルが古いファイル名をそのまま引き継いでいたため、正しく作り直しても古い画像が表示され続けることがありました。1.4.1 で修正しています。

PDF をアップロードしてもサムネイルができません

「ツール > サイトヘルス」を開いてください。「PDF サムネイルの生成」の項目に、このサーバーで描画できるかどうかと、できない場合の理由が出ます。同じ内容は「設定 > Rapls PDF Image Creator > Status」タブにもあります。

サーバー側の原因は 2 つあり、ホスティング事業者に依頼する内容が違います。プラグインがどちらなのかを判定するので、当てずっぽうで問い合わせる必要はありません。

  • Imagick PHP 拡張が入っていない → 拡張のインストールと有効化を依頼してください。ImageMagick 本体の PHP バインディングです
  • ImageMagick は入っているが、セキュリティポリシーで PDF の読み込みが禁止されている → policy.xml で PDF コーダーに読み取り権限を与えるよう依頼してください。2018 年の Ghostscript の脆弱性への対処として PDF を一律禁止する policy.xml を配布している事業者は今も多く、共有サーバーではこちらが原因のことがよくあります。1.3.0 以降は原因になっている policy.xml の絶対パスまで表示します

プラグインはプロセスを起動できない（WordPress.org の規約で exec() 系が使えない）ため、identify -list policy のようなコマンドは実行できません。代わりに policy.xml を自前で読んで判定しています。

大量の PDF を一括処理するときの注意点は？

Bulk Generate で 100 件以上を処理するとき、PHP の max_execution_time に引っかかる可能性があります。プラグインは Ajax で小分けに処理するので通常は問題ありませんが、サーバーの設定によってはタイムアウトすることがあります。その場合は、Bulk Generate タブで小分けに（10〜20 件ずつ）処理してください。

画像が荒い場合はどうすればいいですか？

「Image Settings」タブで、この順番に調整してください。

  1. Rendering Resolution（1.2.0 で追加）：150 から 300 へ上げる。ここが本体です。PDF のページを何 DPI で描画するかの設定で、サムネイルの元になる画像の大きさを決めています
  2. Max Width / Max Height：必要なら大きめに（例：2000 × 1500）
  3. Quality：90〜95 に上げる

Max Width / Max Height だけを上げても、たいていは何も変わりません。この 2 つは描画済みのページを縮小するだけで、拡大はしないからです。A4 を 150 DPI で描画すると約 1240 × 1754 ピクセルになるので、それより大きい最大値を指定しても意味がありません。1.2.0 より前は解像度が 150 DPI 固定だったため、ここで手詰まりになっていました。

ただし、生成時のメモリ使用量は解像度の 2 乗で増えます。600 DPI では A4 が約 4960 × 7016 ピクセル（約 3,500 万画素）になるので、共有サーバーでは 300 DPI あたりから試して、段階的に上げてください。

似たプラグインとの違いは？

  • CMYK / PDF-X 対応：印刷用 PDF がちゃんとサムネイルになる。1.1.0 からは ICC プロファイルを通したカラーマネジメント変換に対応し、色が転ばない
  • WebP 出力対応：JPEG / PNG / WebP の 3 形式
  • WordPress.org のセキュリティ要件：本プラグインは外部プロセスを一切起動しません（exec() 系の関数を使わない、1.0.5 以降）。PDF の描画は Imagick 経由で ImageMagick に任せており、ImageMagick が内部で Ghostscript をデリゲートとして呼ぶかどうかはサーバー側の構成です
  • ブロックエディター統合：クラシック・ブロック両エディタから挿入可能

サポートはどこで受けられますか？

ADVANCED FILTERS : フィルターフック

functions.php にフィルターを設定して挙動をカスタマイズできます。

何ページ目を使うかを変更

add_filter( 'rapls_pdf_image_creator_thumbnail_page', function( $page, $pdf_id ) {
    return 2; // 3 ページ目（0-indexed）
}, 10, 2 );

最大サイズの動的変更

add_filter( 'rapls_pdf_image_creator_thumbnail_max_width', function( $width, $pdf_id ) {
    return 2400;
}, 10, 2 );

add_filter( 'rapls_pdf_image_creator_thumbnail_max_height', function( $height, $pdf_id ) {
    return 1800;
}, 10, 2 );

描画解像度の動的変更（1.2.0 以降）

PDF のページを何 DPI で描画するかを、添付ファイルごとに変えられます。設定画面の値より優先されます。0 や負数を返した場合はデフォルトの 150 に戻ります（Imagick がそのまま受け取ると空のページを描画してしまうため）。

add_filter( 'rapls_pdf_image_creator_thumbnail_resolution', function( $dpi, $pdf_id ) {
    // 特定のカテゴリーの PDF だけ高解像度で描画する
    if ( has_term( 'catalog', 'media_category', $pdf_id ) ) {
        return 300;
    }
    return $dpi;
}, 10, 2 );

品質を動的に変更

add_filter( 'rapls_pdf_image_creator_thumbnail_quality', function( $quality, $pdf_id ) {
    return 95;
}, 10, 2 );

出力フォーマットの動的変更

add_filter( 'rapls_pdf_image_creator_thumbnail_format', function( $format, $pdf_id ) {
    $file_size = filesize( get_attached_file( $pdf_id ) );
    if ( $file_size > 5 * 1024 * 1024 ) {
        return 'webp';
    }
    return $format;
}, 10, 2 );

背景色の指定

add_filter( 'rapls_pdf_image_creator_thumbnail_bgcolor', function( $color, $pdf_id ) {
    return '#f5f5f5';
}, 10, 2 );

img タグの属性を変更

add_filter( 'rapls_pdf_image_creator_thumbnail_image_attributes', function( $attrs, $pdf_id, $size ) {
    $attrs['class'] = 'pdf-thumbnail-custom rounded shadow';
    $attrs['loading'] = 'lazy';
    return $attrs;
}, 10, 3 );

カラー変換方式の切り替え（1.1.0 以降）

'auto'（既定）は ICC プロファイルがあれば使い、無ければ簡易変換にフォールバックします。'icc' は意図を明示するための指定で挙動は auto と同じ、'naive' は 1.1.0 より前の色に固定します。すでに公開中のサイトで色が変わること自体を避けたい場合に使ってください。

add_filter( 'rapls_pdf_image_creator_color_conversion', function() {
    return 'naive'; // 'auto' | 'icc' | 'naive'
} );

ICC プロファイルの探索パス（1.1.0 以降）

絶対パスの配列を先頭から順に評価し、最初に読めた有効なプロファイルを使います。$type には 'srgb' または 'cmyk' が渡されます。

add_filter( 'rapls_pdf_image_creator_icc_paths', function( $paths, $type ) {
    if ( 'cmyk' === $type ) {
        return array( '/srv/icc/JapanColor2011Coated.icc' );
    }
    return $paths;
}, 10, 2 );

レンダリングインテントの変更（1.1.0 以降）

既定は相対比色（RENDERINGINTENT_RELATIVE）です。印刷物の再現としてはこれが最も素直で、知覚的（PERCEPTUAL）は全体が眠くなりやすいためこちらを既定にしています。

add_filter( 'rapls_pdf_image_creator_rendering_intent', function( $intent ) {
    return Imagick::RENDERINGINTENT_PERCEPTUAL;
} );

透明部分の合成先の背景色（1.1.0 以降）

設定画面の背景色より優先されます。$format には 'JPEG' / 'PNG' / 'WEBP' が渡されるので、フォーマットごとに変えることもできます。

add_filter( 'rapls_pdf_image_creator_flatten_background', function( $color, $format ) {
    return '#f5f5f5';
}, 10, 2 );

policy.xml の探索パス（1.3.0 以降）

PDF が描画できない原因が「ポリシーによる禁止」なのか「デリゲートの欠落」なのかを判定するために、policy.xml を探索します。既定では実行時の MAGICK_CONFIGURE_PATH、MAGICK_HOME、Imagick::getConfigureOptions() の値、および /etc/ImageMagick-7 などの一般的な配置場所を順に見ます。独自の場所に置いているビルドではこのフィルターで足してください。

add_filter( 'rapls_pdf_image_creator_policy_paths', function( $paths ) {
    array_unshift( $paths, '/opt/imagemagick/etc/policy.xml' );
    return $paths;
} );

診断にしか使いません。ここに何を指定しても、サムネイルの生成そのものには影響しません。

挿入 HTML のカスタマイズ

add_filter( 'rapls_pdf_image_creator_custom_insert_html', function( $html, $pdf_id, $thumbnail ) {
    $pdf_url = wp_get_attachment_url( $pdf_id );
    $pdf_title = get_the_title( $pdf_id );
    return sprintf(
        '<div class="pdf-card">
            <a href="%s" target="_blank">%s</a>
            <h4>%s</h4>
            <a href="%s" download class="btn btn-download">ダウンロード</a>
        </div>',
        esc_url( $pdf_url ),
        $thumbnail,
        esc_html( $pdf_title ),
        esc_url( $pdf_url )
    );
}, 10, 3 );

ACTION HOOKS : アクションフック

生成前の処理

add_action( 'rapls_pdf_image_creator_before_generate', function( $pdf_id ) {
    error_log( "PDF thumbnail generation starting for ID: {$pdf_id}" );
} );

生成成功時の処理

add_action( 'rapls_pdf_image_creator_after_generate', function( $pdf_id, $thumbnail_id ) {
    update_post_meta( $pdf_id, '_thumbnail_generated_at', current_time( 'mysql' ) );
    update_post_meta( $pdf_id, '_thumbnail_id', $thumbnail_id );
}, 10, 2 );

生成失敗時の処理

add_action( 'rapls_pdf_image_creator_generation_failed', function( $pdf_id, $error ) {
    wp_mail(
        get_option( 'admin_email' ),
        'PDF サムネイル生成失敗',
        sprintf( "PDF ID: %d\nError: %s", $pdf_id, $error )
    );
}, 10, 2 );

CHANGE LOG : バージョン履歴

  • 1.4.1真っ白なサムネイルを、プラグイン側で回避できるようにしました。Ghostscript 9.27 以前は、透明グループの中に画像を持つ PDF——PowerPoint や Illustrator の書き出しでよくある構造——の描画に失敗し、エラーをひとつも出さないまま白紙を返します。ページが真っ白で返ってきたときに限り、透明効果を無効にして自動で描き直すようにしました。実測では 11,018 バイトの白紙が 624,109 バイトの画像になります。常時ではなく再試行としてのみ行うのは、透明効果を正しく使っている PDF では描画結果が変わるためです。ImageMagick に Ghostscript のオプションを渡す API は無く、この環境の ImageMagick は Ghostscript をライブラリとしてリンクしているため delegates.xml も読みません。実際に届いたのは GS_OPTIONS 環境変数でした（プロセスは起動していません）。回避策が使われたサーバーでは Status タブに表示します。透明部分の見え方は変わることがあるため、根本的な解決はホスティング事業者による Ghostscript の更新です。あわせて、サムネイルを再生成しても画面が変わらない不具合を修正。古いサムネイルを削除するとそのファイル名が空き、新しい画像が同じ名前を受け取っていたため、ブラウザーが古い画像を表示し続けていました。再生成した画像には別のファイル名を付けます。1.4.0 で追加した画面表示の日本語訳も追加しました。
  • 1.4.0サムネイルが作れなかったときに、理由を表示するようにしました。これまでは失敗しても何も残らず、PDF にサムネイルが付かないという結果だけが見えていました。原因を「サーバーに PDF サポートが無い」「ページが大きすぎて開けない」「アップロードフォルダーに書き込めない」「ファイルが見つからない」などに分類し、Status タブに表示します。真っ白に描画されたページは、サムネイルとして保存しなくなりました。Ghostscript が失敗を報告しないまま白紙を返すことがあり、そのまま保存すると「答えが出た」ように見えてしまうためです。かわりに WordPress の PDF アイコンが表示され、Status タブに理由が出ます。ページ番号の設定が実際に効くかどうかを、メモリ上で作ったテストファイルを描画して判定する「Page Selection」の項目を追加。測定結果は 12 時間記憶されるので、ホスティング事業者が設定を変えた直後に押す「このサーバーを再検査」ボタンも追加しました。カラーマネジメントでは、ほぼすべてのサーバーにある Ghostscript の default_cmyk.icc を探索対象に加え、出力側の sRGB プロファイル（sRGB2014.icc）を同梱。プロファイルが 1 つも無かったサーバーでも実際のカラーマネジメント変換が働きます。Status タブは CMYK に使われる Ghostscript のデバイス名も表示します。一括生成が「見つかった PDF: 0」とだけ表示していた問題も修正し、空のメディアライブラリ・全件生成済み・実際の異常を区別して表示します。policy.xml のコメント内の記述を有効な設定として数えていた不具合も修正。開発者向けに rapls_pdf_image_creator_before_resize フィルターを追加し、rapls_pdf_image_creator_generation_failed アクションに失敗コードと変換結果を渡すようにしました（引数 2 個で受けている既存のコードはそのまま動きます）。
  • 1.3.2ImageMagick 6 環境で出していた「CMYK の PDF が真っ白になる」警告を、バージョン番号による推測から実測に変更しました。これまでは ImageMagick 6 というだけで全サーバーに警告を出していましたが、実際に測ると 6.9.13-25 では CMYK のページが正しく描画されました。どのデバイスが使われるかはビルドごとに違います。CMYK のテストページを実際に描画し、このサーバーがどうだったかを表示します。
  • 1.3.1PDF が読めるかどうかの判定を、実際に PDF を読んで行うようにしました。queryFormats('PDF') はビルド時に組み込まれたコーダーを返すだけで、セキュリティポリシーが読み取りを許しているかどうかは分かりません。ポリシーで PDF を禁止したサーバーでも queryFormats には PDF が並び、実際に読むと NotAuthorized で失敗します。メモリ上で作った最小の PDF を読ませて判定するようにしました。
  • 1.3.0動かないときに、動かない理由が分かるようにしました。「ツール > サイトヘルス」に「PDF サムネイルの生成」テストと、Rapls PDF Image Creator の情報セクションを追加。困った人が最初に見る場所であり、サポートに貼り付ける先でもあるためです。ImageMagick が使えないサーバーで有効化した場合、これまでは何も言わずに有効化され、PDF をアップロードしてもサムネイルが出ず、理由もどこにも残りませんでした。有効化直後の管理画面に理由つきの警告を出し、アップロードでの失敗も記録して同じ警告に反映するようにしました。あわせて「ImageMagick が利用できません」の一言で済ませていた表示を分割し、拡張が入っていないのか、入っているが ImageMagick のセキュリティポリシーで PDF が禁止されているのかを区別して、原因の policy.xml のパスまで表示します。ホスティング事業者に依頼する内容が変わるためです。判定は policy.xml を読んで行っています（規約上プロセスを起動できないため identify -list policy は使えません）。開発者向けに rapls_pdf_image_creator_policy_paths フィルターを追加。有効化処理が設定のデフォルト値を自前で複製しており、1.2.0 で追加した描画解像度が含まれていなかった不具合も修正。
  • 1.2.1翻訳が英語のまま表示されていた 12 個の文字列を修正。同梱の日本語翻訳がコードとずれており、すでに存在しない Status タブの項目を 14 件抱えたまま、その置き換え先や Bulk Generate のエラーメッセージ、レビューリンクの訳を持っていませんでした。翻訳ファイルのみの変更で、動作は変わりません。
  • 1.2.0Rendering Resolution（描画解像度）設定を追加。PDF のページを描画する DPI がこれまで 150 固定で、Max Width / Max Height は描画済みのページを縮小するだけだったため、最大サイズをいくら上げてもサムネイルは大きくなりませんでした（A4 を 150 DPI で描画すると約 1240 × 1754 ピクセルで頭打ち）。72〜600 DPI の範囲で設定できるようにしました。開発者向けに rapls_pdf_image_creator_thumbnail_resolution フィルターを追加。既定値は従来と同じ 150 のため、値を上げるまで出力は変わりません。既存のサムネイルは自動では作り直されないので、Bulk Generate タブから再生成してください。
  • 1.1.1プラグインの表示名を「Rapls PDF Image Creator – PDF Thumbnails & Featured Images」に変更し、ブランド名だけでなく何をするプラグインなのかで検索に引っかかるようにしました。プラグインヘッダーの説明文が readme と食い違っていた点も解消。動作の変更はありません。
  • 1.1.0CMYK の PDF から生成したサムネイルの色が、実際より鮮やかに（緑や青が蛍光色寄りに）なる不具合を修正。従来はインクの特性を無視した算術式で sRGB へ変換していたため色が転んでいました。サーバー上に ICC プロファイルがある場合はカラーマネジメント変換を行うようになり、元の PDF に近い色で再現されます（プロファイルが無い環境では従来どおり動作します）。あわせて、透明部分を背景色へ明示的に合成する処理に改め（「サムネイルが真っ黒になる」問題への正しい対処）、JPEG 出力で背景に「透明」を選んだ場合は白へ切り替わるようにしました。非推奨の flattenImages() を mergeImageLayers() に置き換え、ImageMagick 7 での動作を安定化。Status タブに ICC カラーマネジメントの動作状況を追加し、ImageMagick 6 の環境では CMYK の PDF が真っ白になる既知の問題を警告表示します。開発者向けに rapls_pdf_image_creator_icc_paths / rapls_pdf_image_creator_rendering_intent / rapls_pdf_image_creator_color_conversion / rapls_pdf_image_creator_flatten_background の 4 フィルターを追加。既存のサムネイルは自動では作り直されません。色を反映するには「Bulk Generate」タブから再生成してください。従来の色のままにしたい場合は rapls_pdf_image_creator_color_conversion フィルターに 'naive' を指定します。
  • 1.0.9.10PDF を画像として表示する際、PHP 8

    環境で発生する致命的エラー（TypeError: Argument #5 ($attr) must be of type array, string

    given    ）を修正。wp_get_attachment_image

    フィルターコールバックが文字列・配列の双方を受け取れるようにし、WordPress

    コアのフィルタ仕様に揃えました。
  • 1.0.9.9PDF（または PDF

    から生成した画像）を一覧ページのアイキャッチとして表示した際に発生する PHP 警告（Undefined

    array key "width"     / "height"）を修正。PDF の添付メタデータにトップレベルの

    width / height を補完し、コアの srcset

    処理での未定義キー参照を防止しました（1.0.9.8 で導入された影響への追加対応）。
  • 1.0.9.8PDF を画像として埋め込んで表示した際、WordPress 6.9.x 以前で発生する PHP 警告（Undefined array key "file"）を修正。PDF の添付メタデータにトップレベルの file キーを補完し、コアの srcset 処理による未定義キー参照を防止しました（WordPress 7.0 ではコア側で修正済み）。
  • 1.0.9.7WordPress 7.0 に対応（動作確認済み）。ブロックエディター・サイトヘルス・REST API での互換性を確認。
  • 1.0.9.6「Auto Generate（自動生成）」をオフにした際、WordPress コア標準の PDF プレビュー生成も抑制し、アップロード時にサムネイルが一切生成されないように修正。自動生成オフ時にコアが生成する -pdf.jpg を削除する wp_generate_attachment_metadata フィルターを追加。
  • 1.0.9.5Plugin URI を新しいプラグインページ (https://raplsworks.com/plugins/rapls-pdf-image-creator/) に更新しました。
  • 1.0.9.4WordPress 6.5+ で .l10n.php 翻訳ファイル不在時の PHP 警告を解消。PHP 最適化された翻訳ファイル（ja.l10n.php）を追加して翻訳ロードを高速化。グローバルパス警告を回避するためプラグインディレクトリから翻訳を直接ロード。無効化・アンインストール時に翻訳ファイルキャッシュをクリアして古いファイル参照を防止。
  • 1.0.9.3WordPress 6.5+ で .l10n.php 翻訳ファイル不在時の PHP 警告を解消。PHP 最適化された翻訳ファイル（ja.l10n.php）を追加して翻訳ロードを高速化。プラグインディレクトリから翻訳を確実にロードするため load_plugin_textdomain() を復活。
  • 1.0.9.2Status タブのサポートセクションにレビューリンクを追加。Plugin URI を新ガイドページ（/plugins/rapls-pdf-image-creator/）に更新。
  • 1.0.9PDF/X-1:2001 形式の PDF が真っ黒なサムネイルになる問題を修正。印刷入稿用 PDF 向けに CMYK → sRGB の色空間変換を追加。
  • 1.0.8PDF 添付詳細でサムネイル URL ではなく PDF URL を表示するように修正。生成サムネイルの添付詳細でもソース PDF URL を表示。「URL をクリップボードにコピー」が PDF・サムネイルともに PDF URL をコピーするように修正。生成サムネイルが AJAX メディアライブラリクエリで適切に非表示に。非推奨の load_plugin_textdomain() 呼び出しを削除（WordPress 4.6 以降は自動）。日本語翻訳を WordPress 翻訳スタイルガイドに準拠するように更新。
  • 1.0.6Status タブにサポートリンク（Buy Me a Coffee）を追加。PHP 7.4 互換性修正（readonly properties / match expressions を削除）。セキュリティ向上：error_log() は WP_DEBUG 有効時のみ実行。有効化/無効化フックから flush_rewrite_rules() を削除。admin_url() を使って AJAX URL を単純化。カスタム HTML 出力に wp_kses_post() サニタイゼーションを追加。
  • 1.0.5GhostScript エンジンサポートを削除（WordPress.org セキュリティ要件）。ImageMagick（Imagick PHP 拡張）専用に。Status タブにサーバー要件チェックを追加。ImageMagick 未対応時の管理画面通知を改善。設定からエンジン選択を削除して単純化。
  • 1.0.4名前空間を Rapls\PDFImageCreator に変更（一意性確保）。全プレフィックスを rapls_pic_ に統一（WordPress.org 準拠）。ショートコード名を pdf_* から rapls_pdf_* に変更。AJAX エラーレスポンスからファイルパス情報を削除（セキュリティ）。メタキーを _rapls_pic_ プレフィックスに更新。
  • 1.0.3プラグイン名を「Rapls PDF Image Creator」に変更。プラグインスラッグを「rapls-pdf-image-creator」に。非推奨の imagedestroy() を削除（PHP 8.0+ 互換性）。
  • 1.0.2WordPress.org 準拠のため translators コメントの位置を修正。
  • 1.0.1WordPress Plugin Check 互換性問題を修正。適切な入力サニタイゼーションでセキュリティ向上。非標準ポートでの AJAX CORS 問題を修正。WordPress コーディング標準に準拠。
  • 1.0.0初回リリース。PDF アップロード時の自動サムネイル生成、ImageMagick エンジン対応、Bulk thumbnail generation、Featured image 対応、Block editor 統合、ショートコード・テンプレート関数、設定可能な画像オプション、日本語翻訳付属。

RELATED PAGES : 関連ページ

タイトルとURLをコピーしました