当サイト、Codex 日本語版は今後積極的な更新は行わない予定です。後継となる新ユーザーマニュアルは、https://ja.wordpress.org/support/ にあります。
万が一、当サイトで重大な問題を発見した際などは、フォーラムWordSlack #docs チャンネルでお知らせください。</p>

「関数リファレンス/get term by」の版間の差分

提供: WordPress Codex 日本語版
移動先: 案内検索
(Notes)
(初めての和訳。)
1行目: 1行目:
{{NeedTrans}}
+
<div id="Description">
 +
== 説明 ==
 +
</div>
 +
タームのフィールドと検索条件を指定して、タームの全データをデータベースから取得します。
  
== Description ==
+
注意: <tt>$field</tt> が '<tt>name</tt>' であっても、<tt>$value</tt> は HTML タグのエスケープ処理を受けません。必要な場合はご自分で行ってください。
Get all <tt>Term</tt> data from database by <tt>Term</tt> field and data.
+
  
Warning: <tt>$value</tt> is not HTML-escaped for the '<tt>name</tt>' <tt>$field</tt>. You must do it yourself, if required.
+
<tt>$field</tt> のデフォルトは '<tt>id</tt>' ですので、null を指定することもできますが、わざわざそうするのはお勧めしません。
  
The default <tt>$field</tt> is '<tt>id</tt>', therefore it is possible to also use null for field, but not recommended that you do so.
+
<tt>$value</tt> が存在しない場合、false が返されます。
 +
<tt>$taxonomy</tt> が存在し、かつ <tt>$field</tt> と <tt>$value</tt> の組み合わせも存在すると、タームが返されます。
  
If <tt>$value</tt> does not exist, the return value will be false. If <tt>$taxonomy</tt> exists and <tt>$field</tt> and <tt>$value</tt> combinations exist, the Term will be returned.
+
<div id="Usage">
 +
== 使い方 ==
 +
</div>
 +
<?php get_term_by( $field, $value, $taxonomy, $output, $filter ) ?>
  
== Usage ==
+
<div id="Parameters">
<pre>
+
== パラメータ ==
<?php get_term_by( $field, $value, $taxonomy, $output, $filter ) ?>
+
</div>
</pre>
+
{{Parameter|$field|文字列|'<tt>id</tt>', '<tt>slug</tt>', '<tt>name</tt>', または '<tt>term_taxonomy_id</tt>' の何れか。|必須|'id'}}
 
+
{{Parameter|$value|文字列&#124;整数|この値を検索。}}
== Parameters ==
+
{{Parameter|$taxonomy|文字列|タクソノミー名。<tt>category</tt>, <tt>post_tag</tt>, <tt>link_category</tt> またはカスタム分類の名前。}}
{{Parameter|$field|string|Either '<tt>id</tt>', '<tt>slug</tt>', '<tt>name</tt>', or '<tt>term_taxonomy_id</tt>'|required|'id'}}
+
{{Parameter|$output|文字列|定数 OBJECT, ARRAY_A, ARRAY_N の何れか。|オプション|OBJECT}}
{{Parameter|$value|string&#124;integer|Search for this term value}}
+
{{Parameter|$filter|文字列|デフォルトは raw で、その場合 WordPress の既定のフィルターはどれも適用されない。|オプション|'raw'}}
{{Parameter|$taxonomy|string|Taxonomy Name <tt>category</tt>, <tt>post_tag</tt>, <tt>link_category</tt> or something custom}}
+
{{Parameter|$output|string|Constant OBJECT, ARRAY_A, or ARRAY_N|optional|OBJECT}}
+
{{Parameter|$filter|string|default is raw or no WordPress defined filter will applied.|optional|'raw'}}
+
  
== Return Values ==
+
<div id="Return Values">
; (mixed) : Term Row (object or array) from database. Will return false if <tt>$taxonomy</tt> does not exist or <tt>$term</tt> was not found. Othewise returns object (by default) or array of fields depending on <tt>$output</tt> parameter.
+
== 戻り値 ==
 +
</div>
 +
; (mixed) : データベースから取得したタームの行(オブジェクトまたは配列)。<tt>$taxonomy</tt> が存在しないか <tt>$term</tt> が見つからなければ false を返す。そうでなければ <tt>$output</tt> パラメータに基づいてオブジェクト(デフォルト)またはフィールドの配列を返す。
  
The fields returned are:
+
返されるフィールドは以下のとおり:
* <tt>term_id (See warning below)</tt>
+
* <tt>term_id (下記の「注意」を参照)</tt>
 
* <tt>name</tt>
 
* <tt>name</tt>
 
* <tt>slug</tt>
 
* <tt>slug</tt>
35行目: 40行目:
 
* <tt>parent</tt>
 
* <tt>parent</tt>
 
* <tt>count</tt>
 
* <tt>count</tt>
'''Warning: string vs integer confusion!''' Field values, including <tt>term_id</tt> are returned in string format. Before further use, typecast numeric values to actual integers, otherwise WordPress will mix up term_ids and slugs which happen to have only numeric characters!
+
'''注意:文字列と整数の混同について!''' フィールドの値は <tt>term_id</tt> も含めて文字列形式で返されます。それを使う前に、値が数値なら本物の整数に型変換してください。そうしないと WordPress は、ターム ID と、数字だけから成るスラッグを混同してしまいます!
  
== Examples ==
+
<div id="Examples">
Taxonomy_name is the name of taxonomy, not the term_name and is required; the id (term_id) is the ID of the term, not post_id;...
+
== 例 ==
 +
</div>
 +
タクソノミー名は、タームの名前とは違います。また、必須項目です。
 +
ID (term_id) はタームの ID であり、投稿 ID ではありません。
 +
<!-- Taxonomy_name is the name of taxonomy, not the term_name and is required; the id (term_id) is the ID of the term, not post_id;... -->
  
Remember:<br />
+
これを覚えておいてください:<br />
&darr; Taxonomy type (e.g. post_tag)<br />
+
&darr; タクソノミーの種類(例えば post_tag <br />
Terms in this taxonomy:<br />
+
「タクソノミー」に含まれるターム:<br />
 
&rarr; news<br />
 
&rarr; news<br />
 
&rarr; webdev<br />
 
&rarr; webdev<br />
 
&rarr; ...
 
&rarr; ...
  
Examples to get terms by name and taxonomy ''type'' (taxonomy_name as category, post_tag or custom taxonomy).
+
名前とタクソノミーの''種類''(タクソノミー名が category, post_tag またはカスタム分類)を指定してタームを取得する例です。
 
<pre>
 
<pre>
// Get term by name ''news'' in Categories taxonomy.
+
// カテゴリーのターム名(投稿のカテゴリー名) ''news'' でタームを取得。
 
get_term_by('name', 'news', 'category')
 
get_term_by('name', 'news', 'category')
  
// Get term by name ''news'' in Tags taxonomy.
+
// タグのターム名(投稿のタグ名) ''news'' でタームを取得。
 
get_term_by('name', 'news', 'post_tag')
 
get_term_by('name', 'news', 'post_tag')
  
// Get term by name ''news'' in Custom taxonomy.
+
// カスタム分類のターム名 ''news'' でタームを取得。
 
get_term_by('name', 'news', 'my_custom_taxonomy')
 
get_term_by('name', 'news', 'my_custom_taxonomy')
 
</pre>
 
</pre>
  
By id (term_id, not post_id):
+
ID で取得する場合(投稿 ID ではありません):
 
<pre>
 
<pre>
// Get term by id (''term_id'') in Categories taxonomy.
+
// カテゴリー(投稿のカテゴリー)から ID (''term_id'') でタームを取得。
 
get_term_by('id', 12, 'category')
 
get_term_by('id', 12, 'category')
  
68行目: 77行目:
  
  
=== Wrong example in this page history ===
+
=== 間違った使い方 ===
Warning: the example below '''is wrong''' (see in this page history):
+
<!-- Wrong example in this page history -->
<pre>get_term_by('id', (int)$post->ID, 'taxonomy_name'); // return null</pre>
+
注意:下記の例は'''間違いです'''(参考のため残してあります):
This example try to get a term with ID (term_id) as post_id and in the taxonomy ''taxonomy_name''. This taxonomy not exists and the term_id is wrong.
+
<pre>get_term_by('id', (int)$post->ID, 'taxonomy_name'); // 戻り値は null</pre>
 +
この例はタームを取得するのに、ID (term_id) に投稿 ID を、それからタクソノミー ''taxonomy_name'' を指定しています。
 +
このタクソノミーと ID の組み合わせは間違っています。
  
This is the correct version of this example:
+
正しいバージョンの例は次のとおりです:
  
 
<pre>
 
<pre>
82行目: 93行目:
 
$myCategories[] = get_term_by('id', $postCategory->cat_ID, 'category');
 
$myCategories[] = get_term_by('id', $postCategory->cat_ID, 'category');
 
}
 
}
// OR:
+
// または:
 
$myCategory = get_term_by('id', $postCategories[0]->cat_ID, 'category');
 
$myCategory = get_term_by('id', $postCategories[0]->cat_ID, 'category');
 
</pre>
 
</pre>
  
== Notes ==
+
<div id="Notes">
* Warning: <tt>$value</tt> is not escaped for '<tt>name</tt>' <tt>$field</tt>. You must do it yourself, if required.
+
== 参考 ==
* See [[関数リファレンス/sanitize_term_field|<tt>sanitize_term_field()</tt>]] The <tt>$context</tt> param lists the available values for '<tt>get_term_by</tt>' <tt>$filter</tt> param.
+
</div>
* Uses: [[関数リファレンス/sanitize_term|<tt>sanitize_term()</tt>]] Cleanses the term based on <tt>$filter</tt> context before returning.
+
* 注意: <tt>$field</tt> '<tt>name</tt>' であっても <tt>$value</tt> はエスケープ処理されません。必要な場合は自分で行ってください。
* Uses global: (<tt>object</tt>) [[Class Reference/wpdb|<tt>$wpdb</tt>]]
+
* <tt>$filter</tt> パラメータに指定可能な値は、[[関数リファレンス/sanitize_term_field|<tt>sanitize_term_field()</tt>]] <tt>$context</tt> パラメータのリストを見てください。
 +
* タームを返す前に、[[関数リファレンス/sanitize_term|<tt>sanitize_term()</tt>]] を使用して、<tt>$filter</tt> のコンテキストに基づいてクレンジングします。
 +
* グローバル変数 (<tt>object</tt>) [[クラスリファレンス/wpdb|<tt>$wpdb</tt>]] を使用します。
  
== Change Log ==
+
<div id="Change Log">
Since: 2.3.0
+
== 変更履歴 ==
 +
</div>
 +
バージョン [[Version 2.3|2.3.0]] にて導入されました。
  
== Source File ==
+
<div id="Source File">
<!-- Need links to current source code files -->
+
== ソースファイル ==
<tt>get_term_by()</tt> is located in {{Trac|wp-includes/taxonomy.php}}.
+
</div>
 +
<tt>get_term_by()</tt> {{Trac|wp-includes/taxonomy.php}} にあります。
  
== Related ==
+
<div id="Related">
 +
== 関連項目 ==
 +
</div>
 
{{Term Tags}}
 
{{Term Tags}}
  

2014年7月30日 (水) 20:50時点における版

タームのフィールドと検索条件を指定して、タームの全データをデータベースから取得します。

注意: $field が 'name' であっても、$value は HTML タグのエスケープ処理を受けません。必要な場合はご自分で行ってください。

$field のデフォルトは 'id' ですので、null を指定することもできますが、わざわざそうするのはお勧めしません。

$value が存在しない場合、false が返されます。 $taxonomy が存在し、かつ $field$value の組み合わせも存在すると、タームが返されます。

使い方

<?php get_term_by( $field, $value, $taxonomy, $output, $filter ) ?>

パラメータ

$field
文字列) (必須) 'id', 'slug', 'name', または 'term_taxonomy_id' の何れか。
初期値: 'id'
$value
文字列|整数) (必須) この値を検索。
初期値: なし
$taxonomy
文字列) (必須) タクソノミー名。category, post_tag, link_category またはカスタム分類の名前。
初期値: なし
$output
文字列) (オプション) 定数 OBJECT, ARRAY_A, ARRAY_N の何れか。
初期値: OBJECT
$filter
文字列) (オプション) デフォルトは raw で、その場合 WordPress の既定のフィルターはどれも適用されない。
初期値: 'raw'

戻り値

(mixed) 
データベースから取得したタームの行(オブジェクトまたは配列)。$taxonomy が存在しないか $term が見つからなければ false を返す。そうでなければ $output パラメータに基づいてオブジェクト(デフォルト)またはフィールドの配列を返す。

返されるフィールドは以下のとおり:

  • term_id (下記の「注意」を参照)
  • name
  • slug
  • term_group
  • term_taxonomy_id
  • taxonomy
  • description
  • parent
  • count

注意:文字列と整数の混同について! フィールドの値は term_id も含めて文字列形式で返されます。それを使う前に、値が数値なら本物の整数に型変換してください。そうしないと WordPress は、ターム ID と、数字だけから成るスラッグを混同してしまいます!

タクソノミー名は、タームの名前とは違います。また、必須項目です。 ID (term_id) はタームの ID であり、投稿 ID ではありません。

これを覚えておいてください:
↓ タクソノミーの種類(例えば post_tag )
「タクソノミー」に含まれるターム:
→ news
→ webdev
→ ...

名前とタクソノミーの種類(タクソノミー名が category, post_tag またはカスタム分類)を指定してタームを取得する例です。

// カテゴリーのターム名(投稿のカテゴリー名) ''news'' でタームを取得。
get_term_by('name', 'news', 'category')

// タグのターム名(投稿のタグ名) ''news'' でタームを取得。
get_term_by('name', 'news', 'post_tag')

// カスタム分類のターム名 ''news'' でタームを取得。
get_term_by('name', 'news', 'my_custom_taxonomy')

ID で取得する場合(投稿 ID ではありません):

// カテゴリー(投稿のカテゴリー)から ID (''term_id'') でタームを取得。
get_term_by('id', 12, 'category')

...


間違った使い方

注意:下記の例は間違いです(参考のため残してあります):

get_term_by('id', (int)$post->ID, 'taxonomy_name'); // 戻り値は null

この例はタームを取得するのに、ID (term_id) に投稿 ID を、それからタクソノミー taxonomy_name を指定しています。 このタクソノミーと ID の組み合わせは間違っています。

正しいバージョンの例は次のとおりです:

// get_term_by('id', category_id, 'category')

$postCategories = get_the_category($post->ID);
foreach ( $postCategories as $postCategory ) {
$myCategories[] = get_term_by('id', $postCategory->cat_ID, 'category');
}
// または:
$myCategory = get_term_by('id', $postCategories[0]->cat_ID, 'category');

参考

  • 注意: $field が 'name' であっても $value はエスケープ処理されません。必要な場合は自分で行ってください。
  • $filter パラメータに指定可能な値は、sanitize_term_field()$context パラメータのリストを見てください。
  • タームを返す前に、sanitize_term() を使用して、$filter のコンテキストに基づいてクレンジングします。
  • グローバル変数 (object) $wpdb を使用します。

変更履歴

バージョン 2.3.0 にて導入されました。

ソースファイル

get_term_by()wp-includes/taxonomy.php にあります。

タームタグ: is_term(), term_exists(), get_objects_in_term(), get_term(), get_term_by(), get_term_children(), get_term_link(), get_terms(), get_the_terms(), get_the_term_list(), has_term(), sanitize_term(), the_terms(), get_object_taxonomies() is_object_in_taxonomy() the_taxonomies() wp_get_object_terms(), wp_set_object_terms(), wp_get_post_terms(), wp_set_post_terms(), wp_delete_object_term_relationships()



関数リファレンステンプレートタグ目次もご覧ください。


最新英語版: WordPress Codex » Function Reference/get term by最新版との差分