Aki Hamano

WordPress6.2で追加された関数・クラス・アクション/フィルタ―フックまとめ

はじめに

2023年3月29日に、WordPress 6.2がリリースされました。

この記事では、PHPコードに焦点を絞り、新たに追加された関数、アクションフック、フィルタ―フック・クラスをまとめたものです。

あわせて、WordPress6.2でアップデートまたは非推奨となったものも最後にまとめています。

条件として、WordPress本体のソース内で「PHPファイルの中で、コメントに @since 6.2.0 と記載があるもの」を手動で抽出してリストアップしました。

注意点

  • マイナーリリースにより、仕様が若干変わる可能性があります。最新の仕様は、WordPress の開発リポジトリまたは WordPress.org のリリースニュース (Make WordPress Core) などで確認してください。
  • 独断で「これは使えそう」「重要そう」と思った項目については、★マークを付けています。

関数

関数に関しては、以下のものを除外しています。

  • プライベート関数、またはコメントのアクセス修飾子が private のもの（@access private）
  • 関数名がアンダーバー始まり
  • おそらく内部的な利用にとどまるもの
  • 内部にフィルタ―フックが用意されており、直接呼ぶ事はおそらく想定されていないもの

get_classic_theme_supports_block_editor_settings()

クラシックテーマにおいて、ブロックエディター向けにサポートしている設定を一括して取得します。

内部的には、get_theme_support() のそれぞれの結果をまとめているだけなので、個別サポートのチェックはこれまで通り get_theme_support( 'XXX' ) で行う事が出来ます。

// 出力例
array(
    'disableCustomColors'    => false,
    'disableCustomFontSizes' => false,
    'disableCustomGradients' => false,
    'disableLayoutStyles'    => false,
    'enableCustomLineHeight' => true,
    'enableCustomSpacing'    => true,
    'enableCustomUnits'      => true,
    'colors' => array(
        array (
            'name'  => 'Black',
            'slug'  => 'black',
            'color' => '#000000',
        ),
        // ...
    ),
    'fontSizes' => array(
        array(
            'name'      => 'Extra small',
            'shortName' => 'XS',
            'size'      => 16,
            'slug'      => 'extra-small',
        ),
        // ...
    ),
    'gradients' => array(
        array(
            'name'     => 'Purple to yellow',
            'gradient' => 'linear-gradient(160deg, #D1D1E4 0%, #EEEADD 100%)',
            'slug'     => 'purple-to-yellow',
        ),
        // ...
    ),
);

switch_to_user_locale()

ユーザーのロケールに従って翻訳を切り替えます。

似たような関数として switch_to_locale() 関数があり、特定の言語へ切り替えるだけであればこの関数で良いのですが、ユーザーのロケールに合わせて切り替えたい場合は以下のように書く必要がありました。

switch_to_locale( get_user_locale( $user ) )

この新しい関数を使うと、少しシンプルに書く事が出来ます。

switch_to_user_locale( $user_id )

wp_clean_theme_json_cache()

theme_json グループのキャッシュを削除します。

WordPress コアでは、テーマを切り替えた時 (switch_theme)、カスタマイザーでテーマのプレビューが開始された時 (start_preview_theme) の二つのアクションフックでこの関数が実行されます。

明示的に実行する事は無いと思いますが、theme.json の設定やグローバルスタイルが上手く反映されない場合に一度実行してみると良いかもしれません。

wp_get_word_count_type()

ロケールに応じた単語カウントのタイプを取得します。

「カウントのタイプ」とは「どのようなルールで文字数をカウントするか」ということで、3タイプが存在し、それぞれのタイプの時に文字列がどのようにカウントされるかは以下の通りです。

カウントのタイプカウントのルール文字列が「Hello World」だった場合
words (デフォルト)単語単位2 (「Hello」で1文字、「World」で1文字)
characters_excluding_spacesスペースを除く文字単位10（「Hello」で5文字、「World」で5文字）
characters_including_spacesスペースを含む文字単位11（「Hello」で5文字、「World」で5文字、間の半角スペースで1文字）

この戻り値は、WordPress サイトの言語に応じて変わりますが、デフォルト値の「words」という文字列自体が翻訳可能な文字列になっているからです。例えば日本語では、英語のように単語単位 (スペース区切り) でカウントする事は困難であり、1文字単位でカウントするほうが合理的なため、characters_including_spaces と翻訳されています。

★wp_theme_has_theme_json()

現在有効なテーマ、もしくは親テーマが theme.json ファイルを持っているかどうかを判定します。

WordPress6.2からは、WP_Theme_JSON_Resolver::theme_has_support() が非推奨となり、代わりにこの関数を使う事が推奨されるようになりました。

★wp_is_internal_link()

指定された URL が、内部ホストリストに含まれるホストであるかどうか (内部リンクかどうか) を判定します。

例えば、WordPress サイトのURLが「https://example.com」であった場合、判定結果は以下となります。

wp_is_internal_link( 'http://example.com/test/' );
// → true
​
wp_is_internal_link( 'https://example.com/test/' );
// → true
​
wp_is_internal_link( 'http://www.example.com/test/' );
// → false
​
wp_is_internal_link( 'https://www.example.com/test/' );
// → false

どのような URL を内部ホストとしてみなすかどうかは、同じくWordPress6.2で導入される wp_internal_hosts フィルターフックで変更出来ます。

フィルターフック

comment_author_link_rel

コメント投稿者のURL (ユーザ―プロフィールページの「サイト」で設定された URL) の rel 属性をフィルタリングします。

つまり、get_comment_author_link() 関数で生成されるリンクの rel 属性となります。例えば、プロトコルが https である外部リンクの rel 属性には ugc / external / nofollow 属性が付与されますが、例えば以下のように条件に応じてフィルタリング出来ます。

function custom_comment_author_link_rel( $rel_parts, $comment ) {
    // 特定のURLの場合のみsponsored属性を追加
    if ( $comment->comment_author_url === 'https://example.com' ) {
        $rel_parts[] = 'sponsored';
    }
    return $rel_parts;
}
add_filter( 'comment_author_link_rel', 'custom_comment_author_link_rel', 10, 2 );

★post_search_columns

検索クエリで検索されるフィールドをフィルタリングします。

デフォルトで検索対象となるのは、投稿タイトル (post_title)、投稿の抜粋 (post_excerpt)、投稿コンテンツ (post_content) ですが、条件に応じて投稿タイトルのみを検索対象とする場合の例は以下です。

function custom_post_search_columns( $search_columns, $q, $query ) {
    // 常に投稿タイトルのみを検索対象とする場合
    return array( 'post_title' );
​
    // 特定のキーワードの場合
    if ( 'XXXXX' === $q ) {
        return array( 'post_title' );
    }
​
    // 特定の投稿タイプの場合
    if ( 'XXXXX' === $query->query_vars['post_type'] ) {
        return array( 'post_title' );
    }
​
    return $search_columns;
}
add_filter( 'post_search_columns', 'custom_post_search_columns', 10, 3 );

pre_wp_load_alloptions

全てのオプション情報を返却する wp_load_alloptions() 関数にあるフィルターです。

このフィルターを使ってあらかじめ配列を返しておくと、以降の処理 (データベースへのアクセス) をショートカット出来るので、上手く使えばパフォーマンスの改善につながるかもしれません。

wp_get_attachment_link_attributes

添付ファイルのリンク属性をフィルタリングします。

例えば投稿テンプレートにおいて、以下のようなコードでそのメディアへのリンクがついたアイキャッチ画像を出力しているとします。

if ( has_post_thumbnail() ) {
    $thumbnail_id = get_post_thumbnail_id( $post->ID );
    echo wp_get_attachment_link( $thumbnail_id, 'medium', true );
}

このリンクを新しいタブで開くようにしたい場合は、以下のようにフィルタリングします。

function custom_wp_get_attachment_link_attributes( $attributes, $id ) {
    $attributes['target'] = '_blank';
    return $attributes;
}
add_filter( 'wp_get_attachment_link_attributes', 'custom_wp_get_attachment_link_attributes', 10, 2 );

wp_internal_hosts

内部ホストとみなされる URL の配列をフィルタリングします。

このフックは、同じくWordPress6.2で導入される wp_is_internal_link() 関数の内部でしか使われていないので、実質この関数の判定ロジックをフィルタリングすることとなります。

// wwwの有無に関わらず内部リンクと見なす
function custom_wp_internal_hosts( $internal_hosts ) {
	$additional_hosts = array();
	foreach ( $internal_hosts as $key => $host ) {
		$has_www = preg_match( '/^www\./', $host );
		if ( ! $has_www ) {
			$additional_hosts[] = 'www.' . $host;
		} else {
			$additional_hosts[] = preg_replace( '/^www\./', '', $host );
		}
	}
	return array_merge( $internal_hosts, $additional_hosts );
}
add_filter( 'wp_internal_hosts', 'custom_wp_internal_hosts' );

wp_save_post_revision_revisions_before_deletion

削除の対象となるリビジョンをフィルタリングします。

いくつまでリビジョンを残すかどうかは WP_POST_REVISIONS 定数を元に判断されますが、この定数が定義されていない場合、WordPress コアは true をデフォルト値として定義するので、すべてのリビジョンが保存されます。残すリビジョンの数を制限したい場合は、WP_POST_REVISIONS 定数の定義または wp_revisions_to_keep フィルターフックで1以上の整数を指定します。

この数を超えたリビジョンは自動的に削除されていく事になりますが、その削除対象となるリビジョンをフィルタリングします。例えば、最も古いリビジョンは削除させたくない場合の例は以下です。

function custom_wp_save_post_revision_revisions_before_deletion( $revisions, $post_id ) {
	array_shift( $revisions );
	return $revisions;
}
add_filter( 'wp_save_post_revision_revisions_before_deletion', 'custom_wp_save_post_revision_revisions_before_deletion', 10, 2 );

アクションフック

comment_reply_to_unapproved_comment

未承認のコメントに対して返信しようとしたときに発火します。

未承認のコメントはフロントエンドのコメントリストには表示されませんが、例えば、次のようなケースで発生します。

  • フロントエンド側で、承認されて表示されているコメントについて「返信」ボタンを押す
  • 管理画面側で、返信しようとしているコメントを「承認を解除」リンクから未承認の状態に戻す
  • フロントエンド側で、コメントを入力し「コメントを送信」ボタンを押下する

そうすると、フロントエンド側ではそのコメントは承認済として表示されますが、サーバーサイドにリクエストを送る段階ではそのコメントは未承認なので、このフックが発火する事になります。

function custom_comment_reply_to_unapproved_comment( $comment_post_id, $comment_parent ) {
	// Do something...
}
add_action( 'comment_reply_to_unapproved_comment', 'custom_comment_reply_to_unapproved_comment', 10, 2 );

wp_ajax_save_attachment

Ajax ハンドラによって添付ファイルが更新された後、JSON レスポンスが送信される前に発火します。

「Ajax によって添付ファイルを更新される」とは、メディアライブラリにおける alt テキストやキャプションの変更などが一例です。添付ファイルの追加フィールドを更新するために追加されたフックのようです。

function custom_wp_ajax_save_attachment( $post, $changes ) {
	// Do something...
}
add_action( 'wp_ajax_save_attachment', 'custom_wp_ajax_save_attachment', 10, 2 );

wp_set_password()

ユーザーのパスワードが設定された後に発火します。

プラガブル関数である wp_set_password() 関数内にあるフックです。

function custom_comment_reply_to_unapproved_comment( $password, $user_id ) {
	// Do something...
}
add_action( 'wp_set_password', 'custom_wp_set_password', 10, 2 );

クラス

クラスに関しては4つ追加されましたが、メインとなるのは WP_HTML_Tag_Processor クラスです。他の三つのクラス (WP_HTML_Attribute_Token / WP_HTML_Span / WP_HTML_Text_Replacement) は、このクラス内のみで使われています。

WP_HTML_Tag_Processor 以外のクラスについては、各クラスの冒頭のコメント欄を翻訳した文章のみ記載しておきます。

★ WP_HTML_Tag_Processor

HTML文字列をパースし、属性の追加・削除・変更が行えるとても便利なクラスです。

例えば、ある HTML 要素に特定のクラス名を付与するために str_replace 等の関数を使うとした場合、以下のようなケースを考慮する必要があります。

  • 既に何らかのクラス名が付与されているか (クラス名の間に半角スペースを入れる必要がある)
  • 既にそのクラス名は付与されているか (二重で付与する事を防ぎたい)
  • そもそも class 属性は付与されているのか

このクラスを使うと、上記のような様々なケースに対応した処理をシンプルに書く事が出来ます。

function add_some_class( $contents ) {
	$tags = new WP_HTML_Tag_Processor( $contents );
	$tags->next_tag();
	$tags->add_class( 'additional-class' );
	return $tags->get_updated_html();
}

$contents1 = '<p>Some text</p>';
add_some_class( $contents1 );
// → <p class="additional-class">Some text</p>

$contents2 = '<p class>Some text</p>';
add_some_class( $contents2 );
// → <p class="additional-class">Some text</p>

$contents3 = '<p class="additional-class">Some text</p>';
add_some_class( $contents3 );
// → <p class="additional-class">Some text</p>

$contents4 = '<p class="default-class">Some text</p>';
add_some_class( $contents4 );
// → <p class="default-class additional-class">Some text</p>

より詳しい内容は、クラスファイルに膨大なコメントとして残されており、とても参考になると思います。

WP_HTML_Attribute_Token

属性トークン構造のクラス。

WP_HTML_Span

HTML文書内のテキストスパンを表すクラス。

WP_HTML_Text_Replacement

テキスト置換クラス。

アップデートされた関数

影響が大きそうなものは特に無し

アップデートされたフィルタ―フック

影響が大きそうなものは特に無し

アップデートされたアクションフック

影響が大きそうなものは特に無し

非推奨となった関数

get_page_by_title()

ページタイトルからページの情報を取得する関数です。

代わりに、以下のように WP_Query クラス を使う事が推奨されています。

$query = new WP_Query(
	array(
		'post_type' => 'page',
		'title'     => 'Sample Page',
	)
);

非推奨となったクラスメソッド

WP_Theme_JSON_Resolver::theme_has_support()

アクティブなテーマが theme.json ファイルを持っているかどうかを判定します。

代わりに、WordPress6.2で導入された wp_theme_has_theme_json() 関数を使用します。

Categories

Events