WordPressでstyle.cssを更新したらwp_enqueue_styleでキャッシュクリアする

どうも、ヤガーです。

しばらくWEB技術ネタを投稿していませんが、頻繁に使うテクニックについてはちゃんとブログに残していこうと思います。

企業HPなどを制作する時に、長い間Wordpressが使われていると思いますが私ヤガーも基本的にはWPを使って構築します。案件によって最適なテーマを選択したり、プラグインなどを開発したりしますが多かれ少なかれデザインを調整するのにstyle.cssを編集することになります。モダンなブラウザでは表示速度の高速化のために、一度アクセスしたファイルを一時的に保管し二回目以降は保管されたファイル（キャッシュ）から表示するため表示が早くなるという仕組みがあります。しかし、開発中の場合は頻繁にCSSを編集するためこのキャッシュが邪魔になることが多いため、CSSが編集されたら適宜キャッシュがクリアされるようにします。

Contents

1 確認環境
2 完成コード
3 wp_enqueue_style
- 3.1 使い方
- 3.2 パラメータ
4 解説
5 よくある間違い

確認環境

WordPress 5.9

完成コード

まずは最終的なコードを確認していただきましょう。

function theme_enqueue_styles() {
　　　　wp_enqueue_style( 'style', get_stylesheet_directory_uri() . '/style.css', array(), date("ymdHis", filemtime( get_stylesheet_directory().'/style.css')) );
}
add_action( 'wp_enqueue_scripts', 'theme_enqueue_styles' );

このコードをご利用テーマのfunctions.phpに追記します。
続けて解説をしていきます。

wp_enqueue_style

説明
WordPress が生成したページに CSS スタイルファイルを安全に (キューへ) 追加します。wp_register_style() で予め登録されていれば、そのハンドルを使って追加できます。

via: 関数リファレンス/wp enqueue style – WordPress Codex 日本語版

WPの作法としてスタイルシートをheadに記述する時にwp_register_styleを使うことになっており、それを変更・追加する場合はwp_enqueue_styleを利用します。

使い方

<?php wp_enqueue_style( $handle, $src, $deps, $ver, $media ); ?>

パラメータ

$handle: （文字列）（必須）スタイルシートのハンドルとして使われる名称。特別なケースとして、文字列に ‘?’ という記号が含まれている場合、それより前の部分は登録されたハンドルとして参照され、それより後の部分はクエリストリングとして URL に追加される。; 初期値：なし
$src: （文字列|真偽値）（オプション）スタイルシートの URL。例: http://example.com/css/mystyle.css。このパラメータは WordPress がこのスタイルを認識していない場合のみに必要。ローカルのスタイルには URL を直接書き込むべきではない。代わりに plugins_url (プラグイン向け) と get_template_directory_uri (テーマ向け) を使って適切な URL を取得する。リモートのアセットはプロトコルに影響されない URL で指定できる。例: //otherdomain.com/css/theirstyle.css; 初期値：空文字列
$deps: （array）（オプション）このスタイルシートが依存する他のスタイルシートのハンドル配列、つまり、このスタイルシートより前に読み込まれる必要があるスタイルシート。依存関係がない場合は空の配列を指定。; 初期値： array()
$ver: （文字列|真偽値）（オプション）スタイルシートのバージョン番号を指定する文字列 (存在する場合) 。このパラメータはキャッシングに関わらず正しいバージョンがクライアントに送信されるようにするために使う。したがって、バージョン番号があってそれがスタイルシートに意味を持つ場合は含めるべきである。; 初期値： false
$media: （文字列|真偽値）（オプション）スタイルシートが定義されているメディアを指定する文字列。例: ‘all’、’screen’、’handheld’、’print’。有効な CSS-media-types の全容についてはこちらの一覧を参照。; 初期値： ‘all’

解説

まずは、対策前の状態でHTMLソースをみてみましょう。
wp_register_styleで追加されたcssは下記のようなHTMLになっていると思います

<link rel='stylesheet' id='style-css'  href='https://creazy.net/wp/wp-content/themes/creazy/style.css?ver=5.9' type='text/css' media='all' />

これは恐らくテーマの方で、WPのバージョンを自動でCSSのURLにパラメータとして追加し、キャッシュクリアを狙ったものと思います。
こんな感じで定義されているのではないでしょうか。

function theme_enqueue_styles() {
　　　　global $wp_version;
　　　　wp_enqueue_style( 'style', get_stylesheet_directory_uri() . '/style.css', array(), $wp_version );
}
add_action( 'wp_enqueue_scripts', 'theme_enqueue_styles' );

wp_enqueue_styleの第4引数がパラメータになるので、そこにWPバージョンが指定されているのではないかと思います。
しかし、これはWP単位のバージョンなので、テーマのCSSを更新してもバージョンは上がらないため用途にはあいません。

そこで、テーマのバージョンをパラメータに使おうと下記のような例がでてくると思います。

function theme_enqueue_styles() {
　　　　$my_theme = wp_get_theme();
　　　　wp_enqueue_style( 'style', get_stylesheet_directory_uri() . '/style.css', array(), $my_theme->get( 'Version' ) );
}
add_action( 'wp_enqueue_scripts', 'theme_enqueue_styles' );

こうすると、style.cssの冒頭にコメントで定義するテーマバージョンを元にキャッシュクリアしますので、良さそうに思えます。
しかし、堕落したエンジニアの自分からするとテーマバージョンの書き換えを忘れそうだなと思ってしまいます。あとは、テーマのバージョン管理の方針として（特に開発中などは）軽微なCSS修正くらいではバージョン番号を上げたくないことも多いんです。

そこで、style.cssの最終更新日時をみて自動的にキャッシュクリアされるようにします。

function theme_enqueue_styles() {
　　　　wp_enqueue_style( 'style', get_stylesheet_directory_uri() . '/style.css', array(), date("ymdHis", filemtime( get_stylesheet_directory().'/style.css')) );
}
add_action( 'wp_enqueue_scripts', 'theme_enqueue_styles' );

キャッシュクリア用の第4引数が date("ymdHis", filemtime( get_stylesheet_directory().'/style.css')) となっておりstyle.cssの物理パスを引数に filemtime　関数で更新日時を取得しています。これによってバージョン書き換えなどをしなくてもCSSの更新都度キャッシュがクリアされます。

<link rel='stylesheet' id='style-css'  href='https://creazy.net/wp/wp-content/themes/creazy/style.css?ver=220127093026' type='text/css' media='all' />

こういう感じで出力されます。

よくある間違い

function theme_enqueue_styles() {
　　　　wp_enqueue_style( 'style', get_stylesheet_directory_uri() . '/style.css', date("ymdHis", filemtime( get_stylesheet_directory().'/style.css')) );
}
add_action( 'wp_enqueue_scripts', 'theme_enqueue_styles' );

↑第4引数にパラメータを指定したいのに、第3引数に何をいれたら良いかわからず無視してしまっている例。$depsを指定したくない場合は空の array() を入れる必要があります。

function theme_enqueue_styles() {
　　　　wp_enqueue_style( 'style', get_stylesheet_directory_uri() . '/style.css？ver=20220128' );
}
add_action( 'wp_enqueue_scripts', 'theme_enqueue_styles' );

↑第4引数でパラメータを指定できるのに、URLに直接パラメータを追加している例。しかもベタ書き。
これをやってしまうと、CSSを更新するたびにfunctions.phpも更新しなければいけなくなるためよくありません。

function theme_enqueue_styles() {
　　　　wp_enqueue_style( 'style', get_stylesheet_directory_uri() . '/style.css', array(), date("ymdHis") );
}
add_action( 'wp_enqueue_scripts', 'theme_enqueue_styles' );

↑第4引数でアクセスした日時をパラメータに渡し、完全にキャッシュクリアしている例。
この場合、キャッシュが完全にきかなくなってしまうので「開発中のみ指定して本番では変更してください」なんて書いている記事がありましたが、そんなの絶対忘れますからね。

というわけで、関数は正しく理解して使いましょう。