Media PDF Thumbnail
ImageMagickを使用してPDFファイルからサムネイル画像を生成し、Media Entityのフィールドフォーマッターとして表示します。
media_pdf_thumbnail
インストール
composer require 'drupal/media_pdf_thumbnail:^6.1'
概要
Media PDF Thumbnailモジュールは、PDFファイルからサムネイル画像を生成し、Media Entityのサムネイルとして使用できるようにします。Media EntityにPDFファイルが含まれている場合、このモジュールはPDFの特定のページから自動的に画像を生成し、デフォルトのサムネイルの代わりに表示できます。
このモジュールは、ImageMagick（PHPのImagick拡張機能経由）とspatie/pdf-to-imageライブラリを使用してPDFから画像への変換を行います。生成された画像は、ソースPDFと生成画像の関係を追跡するカスタムEntityタイプ（pdf_image_entity）に保存されます。
主な機能には、複数ページPDFのサポート（使用するページの選択）、出力形式の選択（JPGまたはPNG）、生成画像の保存先パスの設定、同期および非同期（Cronベース）の画像生成が含まれます。このモジュールはDrupalのTokenシステムと統合されており、プログラムからのアクセスが可能で、カスタマイズ用のhookも提供しています。
Features
- ImageMagickとspatie/pdf-to-imageライブラリを使用してPDFファイルからサムネイル画像を生成
- 複数ページPDFのサポート - サムネイルを抽出するページを指定可能（デフォルトは1ページ目）
- JPGおよびPNG画像出力形式をサポート
- Media Entityのサムネイルフィールド用フィールドフォーマッター（Media PDF Thumbnail Image）
- 同期（オンザフライ）または非同期（Cron Queue）の画像生成モード
- PDF画像マッピングを保存するカスタムEntityタイプ（pdf_image_entity）、リビジョンと多言語をサポート
- パブリックおよびプライベートファイルストレージ用の保存先パス設定
- PDF画像Entityを管理するためのViews統合（フィルターと一括操作付き）
- 生成画像およびレンダリングへのプログラムアクセス用Tokenシステム統合
- プライベートサムネイル閲覧専用のパーミッションによるプライベートファイルアクセス制御
- 画像レンダリングと保存先パスをカスタマイズするためのalter hook
- 画像リンクオプション：コンテンツへのリンク、生成画像ファイルへのリンク、またはオリジナルPDFファイルへのリンク
- リンク用HTML属性設定（download、target、rel）
- Queue処理とEntity削除のバッチ操作
- サムネイル生成時の自動Cache無効化
- リモートファイルストレージ（S3など）のサポート、自動一時ファイル処理付き
Use Cases
PDFプレビュー付きドキュメントライブラリ
PDFドキュメントを保存するためのドキュメントライブラリMediaタイプを作成します。サムネイルフィールドにMedia PDF Thumbnailフォーマッターを設定し、アップロードされた各PDFの最初のページからプレビュー画像を自動生成します。ユーザーはドキュメントをダウンロードせずに視覚的なプレビューを確認でき、ブラウジング体験が向上します。
雑誌・出版物アーカイブ
デジタル雑誌アーカイブでは、特定のページ（例：表紙ページ）からサムネイルを抽出するようフォーマッターを設定します。サムネイル画像を直接PDFファイルにリンクして、簡単にダウンロードできるようにします。「download」属性を使用すると、クリック時にページ遷移せずにダウンロードダイアログが開きます。
複数ページドキュメントのサムネイル
最初のページが表紙シートである複数ページドキュメントの場合、フォーマッターを2ページ目または別の重要なページを使用するよう設定します。これにより、汎用的なタイトルページではなく、意味のあるコンテンツがプレビューに表示されます。
プライベートドキュメントリポジトリ
プライベートファイルシステムに保存される機密ドキュメントの場合、サムネイル用のプライベート保存先URIを設定します。「プライベートPDFサムネイルを表示」パーミッションは、ドキュメントにアクセスすべき認証済みユーザーにのみ付与します。サムネイルはソースPDFと共に保護されたままになります。
大量PDF処理
多くのPDFをアップロードするサイトでは、フォーマッターで「Cronを使用」オプションを有効にします。これによりサムネイル生成がバックグラウンド処理用にQueueに追加され、メディアのアップロードや初回表示時のページ読み込みの遅延を防ぎます。Queue管理ページを監視して、処理がアップロードに追いついていることを確認してください。
Tokenによるプログラムからのサムネイルアクセス
Tokenシステムを使用して、カスタムコード、Views、またはRulesで生成されたサムネイルにアクセスします。例：[media_pdf_thumbnail:field_media_file:1:jpg:image_uri]はファイルURIを返し、[media_pdf_thumbnail:field_media_file:1:jpg:render:medium]は画像スタイルを適用したレンダリング済みHTMLを返します。
Tips
- 高トラフィックサイトでのパフォーマンス向上のため、Cronベースの生成を使用してください。サムネイルはバックグラウンドで生成されます
- フォーマッター設定を変更した後は、既存コンテンツに変更を反映させるためにCacheをクリアしてください
- /admin/media-pdf-thumbnail/settings/purge の「クリーンアップ」機能は、Entityを削除することですべてのサムネイルを再生成できます。サムネイルは次回表示時に再作成されます
- 多言語サイトでは、サムネイルは言語およびリビジョンごとに生成されます
- プログラムからのアクセスにはTokenシステムを使用してください：[media_pdf_thumbnail:field_name:page:format:image_uri]
- フォーマッターで画像スタイルを設定し、一貫したサイズと帯域幅削減を実現してください
- 「画像をPDFファイルにリンク」オプションはドキュメントダウンロード機能に便利です
Technical Details
Admin Pages 4
/admin/media-pdf-thumbnail/settings/list
モジュールによって作成されたすべてのPDF画像EntityのViewsベースの一覧を表示します。このテーブルは、ソースEntityと生成されたサムネイルの関係を示し、Entityタイプ、バンドル、Entity ID、リビジョンID、言語、PDFフィールド名、PDFファイルIDとURI、ページ番号、生成画像ファイルIDとURI、画像形式、タイムスタンプが含まれます。このViewには、Entityタイプ、バンドル、言語、Entity ID、日付の公開フィルターがあります。各行には、個々のEntity管理用の削除操作リンクがあります。
/admin/media-pdf-thumbnail/settings/global
生成画像のカスタム保存先パスなど、PDFサムネイル生成のグローバル設定を構成します。
/admin/media-pdf-thumbnail/settings/queue
PDF画像生成Queueを管理します。Cronベースの生成を使用する場合、サムネイルはQueueに追加され、Cron実行時に処理されます。このページでは、Queueの状態を確認し、手動で処理をトリガーできます。
/admin/media-pdf-thumbnail/settings/purge
すべてのPDF画像Entityと関連する画像ファイルを削除します。これはシステムから生成されたすべてのサムネイルを削除する破壊的な操作です。
権限 8
Hooks 2
hook_media_pdf_thumbnail_image_render_alter
モジュールが表示前にレンダリングされたPDFサムネイル画像要素を変更できるようにします。alt テキスト、タイトル、その他の画像属性を変更するのに便利です。
hook_media_pdf_thumbnail_image_destination_alter
モジュールがPDF画像生成のソースパスと保存先パスを変更できるようにします。サムネイルの保存場所をカスタマイズするのに便利です。
Troubleshooting 6
Imagick PHP拡張機能がインストールされ有効になっているか確認してください。サーバーにImageMagickがインストールされているか確認してください（バージョン6.3.7以上）。「Media PDF Thumbnail」ロガーチャンネルからのエラーメッセージをDrupalログで確認してください。保存先ディレクトリが書き込み可能であることを確認してください。
Cronが定期的に実行されていることを確認してください。/admin/media-pdf-thumbnail/settings/queue のQueue管理ページを確認してください。「実行」ボタンを使用して手動でQueueを処理してください。ログを確認して処理中にエラーが発生していないか確認してください。
適切なユーザーロールに「プライベートPDFサムネイルを表示」パーミッションを付与してください。Drupal設定でプライベートファイルシステムが正しく構成されていることを確認してください。
PDFファイルが無効、破損している、またはImagick拡張機能が処理できない可能性があります。ファイルフィールドに実際にPDFが含まれているか確認してください（MIMEタイプがapplication/pdf）。特定のImageMagickエラーについてはエラーログを確認してください。
ImageMagickのバージョンは6.3.7以上である必要があります。spatie/pdf-to-imageライブラリのバージョンは2.1.0以上である必要があります。必要に応じて「composer require spatie/pdf-to-image:^2.1.0」を実行して更新してください。
モジュールは処理のためにPDFをローカルの一時ストレージにコピーすることでリモートストレージをサポートしています。問題が発生した場合は、temporary://ストリームラッパーが正しく設定され、十分な空き容量があるか確認してください。
Security Notes 4
- 「administer_media_pdf_thumbnail」パーミッションは、すべてのサムネイルデータを削除できるため、信頼できる管理者にのみ付与してください
- 「プライベートPDFサムネイルを表示」パーミッションは、プライベートファイルから生成されたサムネイルへのアクセスを制御します。付与前に慎重に検討してください
- 生成されたサムネイルは、カスタム保存先URIが設定されていない限り、ソースPDFのファイルシステムの場所（パブリック/プライベート）を継承します
- モジュールはhook_file_download()を実装して、プライベートサムネイルに対するパーミッションチェックを実施します