README

TMStack WordPress Framework(TMSWP)の拡張パッケージで、署名付きのURLでサムネイルを生成します。元画像はuploadsの下の画像(添付ファイルのIDかURL)だけで、外部のURLは扱いません。生成した画像はuploads/tmswp-thumb/にキャッシュし、2回目からは静的なファイルとして返します。

動作環境

PHP 8.3〜8.5(ext-gd。composer.jsonのrequire)、WordPress 7.0以上
tmswp/core ^0.10(composer.jsonのrequire)
REST APIが使えること。未生成のサムネイルのURLは、RESTのルート/wp-json/tmswp/v1/thumbを指します。REST以外の経路はありません。ログインしていない訪問者からこのルートが使えないと(REST APIを無効化するプラグイン等)、未生成のサムネイルは表示されません。thumbnailは管理画面の表示のたびにこれを確かめ、使えなければmanage_optionsの権限のユーザーに通知します。Webサーバーの設定による/wp-json/の遮断は検出できません。
uploadsがローカルのファイルシステムにあること。外部ストレージ(オブジェクトストレージへのオフロード等)には対応しません。キャッシュの書き込みに、同じディレクトリの中のrename()とflock()を使います。
thumbnailを登録できるKernelは、サイトに1つです。テーマとプラグインの両方に登録すると、2つ目のKernelの起動がLogicExceptionで止まります。

提供するもの

名前	役割
`TMSWP\Thumbnail\Thumbnail`	`KernelConfig`の`extensions`に渡す拡張。RESTのルート・管理画面の通知・WP-CLIのコマンドを登録する
`TMSWP\Thumbnail\ThumbnailConfig`	寸法の上限・既定の品質・既定の切り抜き・キャッシュのディレクトリ名・302のキャッシュの秒数
`tms_thumb()`	サムネイルのURLを返すグローバル関数(Composerの`autoload.files`で定義)
`wp tmswp thumb clear\|status`	キャッシュの削除と集計

導入

composer require tmswp/thumbnailを実行します。
テーマ・プラグインのどちらか1つのtmswp-kernel.phpで、extensionsにThumbnailを渡します。

use TMSWP\Core\Kernel\KernelConfig;
use TMSWP\Thumbnail\Thumbnail;
use TMSWP\Thumbnail\ThumbnailConfig;

return KernelConfig::theme(
    __DIR__ . '/app',
    'App',
    extensions: [new Thumbnail(new ThumbnailConfig(defaultQuality: 80))],
);

設定

ThumbnailConfigの項目は、maxDimension(幅・高さの上限。既定2560)、defaultQuality(既定82)、defaultCrop(既定true)、cacheDirName(uploadsの直下の1つの名前。英数字で始まり、英数字・.・_・-だけ。既定tmswp-thumb。uploadsの既存のディレクトリ(年のディレクトリ等)と重ならない名前にする)、redirectMaxAge(生成済みのファイルへの302をキャッシュさせる秒数。既定3600)です。範囲・形の外の値は例外になります。

キャッシュのディレクトリには、初回の作成のときに印のファイル.tmswp-thumb-cacheを置きます。印の無い空でない既存のディレクトリは、キャッシュとして使わず、生成・wp tmswp thumb clear・statusが例外になります(cacheDirNameがuploadsの既存のディレクトリと重なったときに、そこにあるファイルを消さないためです)。

使い方

<?php $thumb = tms_thumb((int) get_post_thumbnail_id(), 400, 300); ?>
<?php if ($thumb !== null) : ?>
<img src="<?php echo esc_url($thumb); ?>" alt="">
<?php endif; ?>

tms_thumb($src, $width, $height, $options)の$srcは、添付ファイルのIDか、uploadsの下の画像のURLです。$optionsはcrop(bool)とquality(int 1〜100)だけです。
画像が無いとき(アイキャッチの未設定、添付ファイルやその実体が無い)はnullを返します。
引数とオプションの誤り(uploadsの外のURL、許可されない拡張子、寸法、オプション)は、例外になります。
実行時の失敗は、登録したKernelがdebugなら例外、本番ならそのKernelのロガーに記録してnullを返します。
元画像より大きい寸法は、元画像の寸法で頭打ちになります(拡大しません)。
RESTのルートはログインを求めず、URLの署名(鍵はwp_salt('auth')から導出)で要求を確かめます。saltを変えると、生成前のURLは403になります。

キャッシュの削除(WP-CLI)

wp tmswp thumb clear --days=30   # 最後にREST経由で返してから30日より前のファイルを削除
wp tmswp thumb clear             # すべて削除
wp tmswp thumb status            # 件数・合計サイズ・扱えなかった元画像の数

--daysは正の整数で、redirectMaxAgeより長くなければなりません。ページキャッシュを使うサイトでは、ページキャッシュの寿命より長くしてください(HTMLに残った静的なURLへのアクセスは、削除の判定に使われないため)。削除は自動では実行されません。サーバーのcron等で定期的に実行してください。

レシピ

サムネイルのURLを作る(引数・設定・キャッシュ・WP-CLI・RESTとセキュリティの注意): vendor/tmswp/thumbnail/rules/thumbnail.md
拡張の登録の仕方と制約: vendor/tmswp/core/rules/extensions.md

設計の正本は、TMSWPのmonorepo(tmstack-io/tmswp)のdocs/08-extensions.mdの「tmswp/thumbnail — 署名付きURLサムネイル」の節です。

ライセンス

GPL-2.0-or-later(LICENSE)

tmswp / thumbnail

Package info

Security

Statistics

README

動作環境

提供するもの

導入

設定

使い方

キャッシュの削除(WP-CLI)

レシピ

ライセンス