$wpdb->insert() の使い方｜説明・引数・注意点

説明

基本構文

$wpdb->insert( string $table, array $data, array|string $format = null ): int|false

引数

• $table：テーブル名
• $data：列名と値の連想配列
• $format：各値の書式（%s / %d / %f）

戻り値

追加した行数。失敗時は false。

使い方（サンプル）

global $wpdb;
$wpdb->insert( $wpdb->prefix . 'my_table', array( 'name' => 'taro' ), array( '%s' ) );
$new_id = $wpdb->insert_id;

注意点

• 値は自動でエスケープされます。
• 追加した行のIDは $wpdb->insert_id で取得します。

実務での使いどころ

• 独自のテーブルに、1行を追加するとき。
• 値は、自動でエスケープされるため、prepare() を使わずに、安全に追加するとき。

よくあるミスと対処

• データを、あらかじめ prepare() や esc_sql() で処理してから渡している。二重にエスケープされる。そのまま渡す。
• $format を指定せず、型が、意図と違う。数値は %d、文字列は %s を指定する。
• 追加した行のIDは、$wpdb->insert_id で取得する。戻り値は、追加した行数（1）。
• テーブル名に、接頭辞（$wpdb->prefix）を、付けていない。

NG例

$wpdb->insert( 'logs', array( 'user_id' => $user_id ) ); // 接頭辞がない

OK例

$wpdb->insert(
	$wpdb->prefix . 'logs',
	array( 'user_id' => $user_id, 'message' => $message ),
	array( '%d', '%s' )
);
$new_id = $wpdb->insert_id;

使い分け早見表

関連項目

$wpdb->update()、$wpdb->delete()、$wpdb->prepare()

公式リファレンス：wpdb::insert() | Class method | WordPress Developer Resources