よく使う関数一覧

WordPressにはたくさんの関数が用意されてますが、私がよく使う関数をまとめました。

WordPressテーマに必須な関数

次の関数は、テーマ作成時に必ず記述するべき関数です。これらの関数を記述することで、管理バーの表示、メタタグの出力、JavaScriptライブラリの読み込みなどを行ってくれます。また、これらの関数を記述しないとプラグインが動作しないなどの不具合も生じますので必ず記述しましょう。

テーマテンプレートファイル内の タグ直前に

<?php wp_head(); ?>

と記述します。

テーマテンプレートファイル内の タグ直前に

<?php wp_footer(); ?>

と記述します。

サイト情報を取得したい

bloginfo

サイトの情報を表示させる関数です。

例) 管理画面の「設定」⇒「一般」で設定したサイトのタイトルを表示。

bloginfo('name');

URL、パス情報を取得したい

下記設定で動作を確認

パス情報を取得(header.phpで実行)

echo __FILE__ . "</br>";
echo trailingslashit(__FILE__) . "</br>";
 
echo ABSPATH . "</br>";
echo TEMPLATEPATH . "</br>";
echo STYLESHEETPATH . "</br>";
■子テーマの場合
C:\xampp\htdocs\wakuwakuweb-local\wordpress\wp-content\themes\child\header.php
C:\xampp\htdocs\wakuwakuweb-local\wordpress\wp-content\themes\child\header.php/

C:\xampp\htdocs\wakuwakuweb-local\wordpress/
C:\xampp\htdocs\wakuwakuweb-local\wordpress/wp-content/themes/parent
C:\xampp\htdocs\wakuwakuweb-local\wordpress/wp-content/themes/child

■親テーマの場合
C:\xampp\htdocs\wakuwakuweb-local\wordpress\wp-content\themes\parent\header.php
C:\xampp\htdocs\wakuwakuweb-local\wordpress\wp-content\themes\parent\header.php/

C:\xampp\htdocs\wakuwakuweb-local\wordpress/
C:\xampp\htdocs\wakuwakuweb-local\wordpress/wp-content/themes/parent
C:\xampp\htdocs\wakuwakuweb-local\wordpress/wp-content/themes/parent

URLを取得

echo home_url() . "</br>";
echo home_url("/", "https") . "</br>";
echo site_url() . "</br>";
 
echo get_template_directory_uri() . "</br>";
echo get_stylesheet_directory_uri() . "</br>";
echo get_stylesheet_uri() . "</br>";
 
echo admin_url() . "</br>";
echo includes_url() . "</br>";
■子テーマの場合
http://localhost/wakuwakuweb-local
https://localhost/wakuwakuweb-local/
http://localhost/wakuwakuweb-local/wordpress

http://localhost/wakuwakuweb-local/wordpress/wp-content/themes/parent
http://localhost/wakuwakuweb-local/wordpress/wp-content/themes/child
http://localhost/wakuwakuweb-local/wordpress/wp-content/themes/child/style.css

http://localhost/wakuwakuweb-local/wordpress/wp-admin/
http://localhost/wakuwakuweb-local/wordpress/wp-includes/

■親テーマの場合
http://localhost/wakuwakuweb-local
https://localhost/wakuwakuweb-local/
http://localhost/wakuwakuweb-local/wordpress

http://localhost/wakuwakuweb-local/wordpress/wp-content/themes/parent
http://localhost/wakuwakuweb-local/wordpress/wp-content/themes/parent
http://localhost/wakuwakuweb-local/wordpress/wp-content/themes/parent/style.css

http://localhost/wakuwakuweb-local/wordpress/wp-admin/
http://localhost/wakuwakuweb-local/wordpress/wp-includes/

※ちなみに下記は非推奨

bloginfo( 'template_directory' );
bloginfo( 'url' );
bloginfo( 'stylesheet_url' );

テンプレートファイルを読み込みたい

  • get_header
    • header.phpを読み込む
  • get_footer
    • footer.phpを読み込む
  • get_sidebar
    • sidebar.phpを読み込む
  • get_search_form
    • searchform.phpを読み込む
  • get_template_part
    • 引数に指定したテンプレートを読み込む。

例) content.phpを読み込む。

get_template_part('content');

投稿に紐づく情報を扱いたい

  • the_permalink
    • 投稿のパーマリンクを表示する。
    • ※パーマリンクとは?
      • 個々の記事に与えられたURLのこと。
  • the_title
    • 投稿のタイトルを表示する。
  • the_excerpt
    • 投稿の抜粋文を表示する。
  • the_content
    • 投稿の本文を表示する。
  • the_post_thumbnail
    • 投稿のアイキャッチを表示する。
  • the_time
    • 投稿の投稿時間を表示する。

次のように表示する際のフォーマット指定ができます。

the_time('Y-m-d');
  • the_category
    • 投稿のカテゴリーを表示する。
  • the_tags
    • 投稿のタグを表示する。
  • the_terms
    • 投稿のタームを表示する。
  • get_post_type
    • 投稿の投稿タイプを取得する。

次のように、投稿タイプで条件分けをしたいときなどに利用

if( get_post_type() === 'post' ) {
    /* 投稿タイプが「post」だった時の処理 */
} elseif( get_post_type() === 'shop' ) {
    /* 投稿タイプがカスタム投稿「shop」だった時の処理 */
}
  • get_post_ancestors
    • 投稿IDを基に親投稿のIDの配列を取得します。

例) 現在の投稿の親投稿を取得し、親投稿のIDに300が含まれているか判定

if ( in_array(300, get_post_ancestors( $post->ID ) ) ) {
    echo 'この投稿は、固定ページ ID 300 の子孫ページです';
}
  • get_post_meta
    • カスタムフィールドの値を取得。第3引数の$singleには、単一の値を取得する場合はtrue、複数の値を取得する場合(配列をシリアライズしてDBに保存している場合)はfalseを指定します。
get_post_meta($post_id, $key, $single);
補足
「the_permalink()」などの関数は出力まで実行してしまいます。 変数として取得したいのであれば、「get_permalink()」と記述します。 WordPressの関数名は、get_にするとその文字列が得られるように命名されている場合が多いです。

投稿情報を取得したい

  • get_post
    • 投稿IDで指定した投稿情報を取得します。この関数はWP_Postオブジェクトを返します。

表示されるページによって条件分岐したい

  • is_front_page
    • サイトのフロントページが表示されている場合
  • is_home
    • メインブログページが表示されている場合
  • is_404
    • “HTTP 404: Not Found”エラーページが表示されている場合
  • is_page
    • 固定ページが表示されている場合
  • is_single
    • 個別投稿のページが表示されている場合
  • is_search
    • 検索結果のページが表示されている場合
  • is_category
    • カテゴリーのアーカイブページが表示されている場合
  • is_tag
    • タグのアーカイブページが表示されている場合
  • is_tax
    • タクソノミーのアーカイブページが表示されている場合

より詳しい情報は、「条件分岐タグ – WordPress Codex 日本語版」にて確認できます。

サイト内リンクを手軽に作りたい

記事のIDを指定してパーマリンクを取得します。

次のようにget_page_by_pathを一緒に利用することで、固定ページのパーマリンクを取得できます。

例) 固定ページ「siteinfo」のパーマリンクを出力

echo get_permalink(get_page_by_path('siteinfo'));

wp_list_pages

引数で指定した条件の固定ページリストを出力します。

例1) IDが2,4,12のページだけをリスト出力。見出し用のliは出力しない。

wp_list_pages('include=2,4,12&title_li=');

例2) $post->IDの下の階層ページを出力。階層の最大数は2とする。見出し用のliは出力しない。

wp_list_pages(array('child_of' => $post->ID, 
                    'title_li' => false, 
                    'depth' => 2));

wp_list_categories

引数で指定した条件のカテゴリーのリストを出力します。

例1) 公開記事のあるカテゴリーを出力。見出し用のliは出力しない。current_categoryで指定したIDに自動でclass属性を付与する。

wp_list_categories(array('title_li' => false, 
                         'hide_empty' => true, 
                         'current_category' => $id));

例2) shopタクソノミーの公開記事のあるタームを出力。見出し用のliは出力しない。

wp_list_categories(array('taxonomy' => 'shop', 
                         'title_li' => false, 
                         'hide_empty' => true));

ナビメニュー

register_nav_menus

カスタムメニューの機能を有効にします。

functions.phpに記述します。

register_nav_menus(
    array(
        'place_global' => 'グローバル',
    )
);

上記のように記述すると、管理画面の「外観」⇒「メニュー」で「テーマの位置」に “グローバル” が追加されます。

メニューを出力します。

wp_nav_menu(array(
    'container' => 'div',                  // メニューをdivタグでラップする。
    'container_id' => 'global_nav',        // ラップするタグのID属性を指定
    'theme_location' => 'place_global',    // functions.phpで定義したテーマの位置を指定
    'depth' => 3,                          // 階層数を指定
));

参考:テンプレートタグ/wp nav menu

フォーマット用関数

変数や関数を使って文字を出力する際にフォーマット関数を利用します。
esc_html関数などは、2重にエスケープされるのを防いでくれる機能を持っています。

esc_html

文字列をHTML内のテキスト出力用にエスケープする。

<h1><?php echo esc_html( $title ); ?></h1>

esc_attr

文字列を属性値用にエスケープする。

<input type="hidden" name="taxonomy" value="<?php echo esc_attr($taxonomy); ?>" />

esc_url

文字列をURL用にフォーマットする。文字列を調べ、余分な文字の削除などをします。

<img src="<?php echo esc_url( $screenshot ); ?>" alt="" />
<form action="<?php echo esc_url( $form_post ) ?>" method="post">
<a href="<?php echo esc_url( $home_url ); ?>"><?php echo $home_url; ?></a>

フィルターフック、アクションフック

次の関数は、WordPressが行う処理の特定タイミングで自分の作った関数を呼び出したいときに利用します。この特定のタイミングというのは、WordPressのコアファイルのソース上に設定されており フックポイント と呼びます。フィルターフックとアクションフックは、便宜的に分かれてますが、機能は同じということが、wordpress/wp-includes/plugin.php の記述をみると確認できます。

// wordpress/wp-includes/plugin.php
function add_action($tag, $function_to_add, $priority = 10, $accepted_args = 1) {
    return add_filter($tag, $function_to_add, $priority, $accepted_args);
}
 
function remove_action( $tag, $function_to_remove, $priority = 10 ) {
    return remove_filter( $tag, $function_to_remove, $priority );
}

add_filter

フィルターフックを登録する。

// $tag                フックするフィルター名
// $function_to_add    フィルター時に呼び出される関数名
// $priority           実行する関数の順序
// $accepted_args      関数が受け取る引数の数
add_filter( $tag, $function_to_add, $priority, $accepted_args );

remove_filter

フィルターフックの登録を解除する。

// $tag                 除去する関数がフックしているフィルター名
// $function_to_remove  除去する関数名
remove_filter($tag, $function_to_remove);

add_action

アクションフックを登録する。

remove_action

アクションフックを解除する。

javascript、cssファイルを読み込みたい

利用方法はjavascriptのときとほぼ同じ。

wp_register_script, wp_enqueue_script, wp_localize_script

javascriptの読み込み

add_action( 'wp_enqueue_scripts', 'my_scripts' );
 
function  my_scripts() {
    wp_enqueue_script( 'jquery' );
 
    wp_register_script( 'xxx-js', plugins_url( 'js/xxx.js', __FILE__ ), array('jquery'), '1.0', TRUE );
    wp_enqueue_script( 'xxx-js' );
 
    $config_array = array(
            'ver1' => 'aaaa',
            'ver2' => 'bbbb'
    );
    wp_localize_script( 'xxx-js', 'xxxconf', $config_array );
}
  • 1行目
    • javascript読み込み処理が記述された関数をwp_enqueue_scriptsアクションフックで実行させる。
  • 6行目
    • wp_register_script関数でjavascriptファイルを登録。
      • 第1引数
          - 任意のユニークな識別子
      • 第2引数
          - javascriptファイルまでのURLを指定
      • 第3引数
          - このスクリプトより前に読み込まれる必要があるスクリプトの識別子を指定
      • 第4引数
          - バージョン
      • 第5引数
          - TRUEの場合、javascriptファイルを内ではなく、の直前に配置。
    • plugins_url関数でプラグインディレクトリ(wp-content/plugins/)の相対パスを取得。第2引数で起点となるファイル(この例では、FILE)を指定。
  • 4,7行目
    • wp_enqueue_script関数でjavascriptファイルを読み込ませることができる。wp_register_script関数で指定した識別子を指定。jqueryは、wordpressのコアファイル内で指定済み。
  • 13行目
    • wp_localize_script関数を利用するとスクリプトにPHP変数を渡すことができる。この例の場合、スクリプト上で「xxxconf.ver1」と指定した箇所に「aaaa」がバインドされる。

wp_register_style, wp_enqueue_style

CSSの読み込み

add_action( 'wp_enqueue_scripts', 'my_scripts' );
 
function  my_scripts() {
    wp_register_style( 'xxx-css', plugins_url( 'css/xxx.css', __FILE__ ) );
    wp_enqueue_style( 'xxx-css' );
}

管理画面にメニューを追加したい

add_menu_page

トップレベルメニューを追加

add_menu_page( 
    $page_title,  //クリックされたときにHTMLページタイトルになる
    $menu_title,  //トップレベルメニューの管理画面上での名前
    $capability,  //このメニューページを利用できる権限
    $menu_slug,   //トップレベルメニューページの識別子
    $function,    //トップレベルメニューページのコンテンツを出力する関数
    $icon_url,    //トップレベルメニューのアイコン
    $position );  //トップレベルメニューの出す順

add_submenu_page

サブメニューを追加

add_submenu_page( 
    $parent_slug, //親メニューの識別子
    $page_title,  //クリックされたときにHTMLページタイトルになる
    $menu_title,  //サブメニューの管理画面上での名前
    $capability,  //このメニューページを利用できる権限
    $menu_slug,   //サブメニューページの識別子
    $function );  //サブメニューページのコンテンツを出力する関数

ユーザー管理したい

  • wp_get_current_user
    • ログインしているユーザー情報を取得
  • is_user_logged_in
    • 現在の訪問者がログインしているかチェック
  • add_role
    • ユーザーロールの追加
  • get_role
    • ユーザーロールの取得
  • remove_role
    • ユーザーロールの削除
  • add_cap
    • (WP_Roleオブジェクトのメソッド)
    • 権限の追加

メタデータを操作したい

操作 投稿
(wp_postmeta)
ユーザ
(wp_usermeta)
コメント
(wp_commentmeta)
追加 add_post_meta add_user_meta add_comment_meta
取得 get_post_meta get_user_meta get_comment_meta
更新 update_post_meta update_user_meta update_comment_meta
削除 delete_post_meta delete_user_meta delete_comment_meta

関数の引数は次のようになります。

add_post_meta( $post_id, $meta_key, $meta_value, $unique );
get_post_meta($post_id, $key, $single);
update_post_meta( $post_id, $meta_key, $meta_value, $prev_value );
delete_post_meta( $post_id, $meta_key, $meta_value );

WP_Errorを利用してエラー処理をしたい

WP_Errorの利用例です。

$email = "abc";
$name = "";
$result = err_chk($email, $name);
if (is_wp_error($result)) {
    var_dump($result->get_error_messages());
}
 
function err_chk($email, $name) {
    $errors = new WP_Error();
 
    if (!is_email($email)) {
        $errors->add('error_email', 'メールアドレス形式が正しくありません。');
    }
 
     if (!is_email($name)) {
        $errors->add('error_name', '名前が未入力です。');
    }   
     
    if ($errors->get_error_code()) {
        return $errors;
    } else {
        return true;
    }
}

4行目のis_wp_error関数は、引数がWP_Errorオブジェクトの場合はtrueを、それ以外はfalseを返します。

結果は次のようになります。

array (size=2)
  0 => string 'メールアドレス形式が正しくありません。' (length=57)
  1 => string '名前が未入力です。' (length=27)

ショートコードを使いたい

ショートコードの利用例です。

function shortcode_test($atts) {
    extract(shortcode_atts(array(
        'id' => 0,
        'name' => 'XXXX',
        'old' => 0), $atts)
    );
 
    return $id . ':' . $name . 'さんは' . $old . '歳です。<br>';   
}
add_shortcode('wakuwakuweb', 'shortcode_test');
 
echo do_shortcode('[wakuwakuweb]');
echo do_shortcode('[wakuwakuweb id=10 name=wakuwakuweb old=30]');

12,13行目のdo_shortcode関数を利用するとPHP内でショートコードを呼ぶことができます。

結果は次のようになります。

0:XXXXさんは0歳です。
10:wakuwakuwebさんは30歳です。

国際化対応したい

例として、『testplugin』というプラグイン内で国際化対応を行うとする。
翻訳ファイルは、プラグインフォルダ内のlanguagesフォルダ配下に設置するとする。

翻訳ファイルの読み込み

load_plugin_textdomain( 
    'testplugin', 
    false, 
    dirname( plugin_basename( __FILE__ ) ) . '/languages/'
);

第1引数では、テキストドメインを指定。(プラグイン名が推奨されている)
第2引数は、false
第3引数は、翻訳ファイルが設置されいてるディレクトリ

国際化用の関数

_e( 'Hello', 'testplugin' );
$str = __( 'Hello', 'testplugin' );
esc_html_e( 'Hello', 'testplugin' );
$str = esc_html__( 'Hello', 'testplugin' );

翻訳作業の流れ

  1. WordPress i18n ToolsでPOTを作成
  2. POTファイルからPOファイルを作成
  3. POファイルをMOファイルに変換
わくわくBank.
ソフトウェア開発で必要とされる技術、用語、概念を整理しています。