insert_data

　 insert_data( string $table_name, array $data[, array $table_schema][, bool $date_init])

テーブルにデータを追加（挿入）します。実体はWordPressコアクラスのメソッドである$wpdb->insert()のラッパーであり、メソッドの仕様もそれに準じます。

パラメータ

$table_name

文字列としてデータを追加したいテーブル名 table_name を指定します。

$data

追加するデータ（カラム名=>値のペア）の配列として指定します。カラム名と値のデータの両方がSQLセーフなエスケープされた値である必要があります。
なお、CDBTプラグインで作成されたテーブルに自動付与されるID（もしくはIDがない場合のプライマリキーのカラム）、created、updatedのカラムに対して値を指定しても無視され、データの挿入時にプライマリキーであるカラムにはオートインクリメントにより自動採番が行われ、createdにはこのメソッドを実行した時点での日時が自動挿入されます。その際、updatedの値は破棄されます。データ挿入後は生成されたプライマリキーを使ってデータにアクセスすることができます。

$table_schema

データを追加するテーブルのテーブルスキーマ情報の配列を指定します。テーブルスキーマ情報は get_table_schema() メソッドにて取得します。このパラメータは必須ではありませんが、指定されると、追加するデータの値についてテーブルのカラム型に応じたマッピングが行われます。省略された場合は、WordPressのwpdb::$field_typesで指定されていない限り、文字列として扱われます。

$date_init

テーブル内にデータ作成日時（created）および更新日時（updated）のカラムがあった場合に、日時の自動挿入をおこなうかを真偽値で設定します。初期値はtrueで、省略時には初期値に沿って日時の自動挿入が行われます。この引数にfalseを指定することで、任意の作成日時・更新日時にてデータを挿入することができます（バージョン 1.1.11 よりCSVインポートによるデータ挿入時はfalse指定で動作します）。なお、falseを指定しても、挿入データの該当カラムに日時データがない場合は自動で日時が挿入されます。

返り値

データが追加できなかった場合、 FALSE を返します。データが正常に追加された場合、追加したデータのプライマリキーであるIDの値を返します。これは、WordPressコアクラスのメソッド$wpdb->insert_idの結果と同一です。

変更履歴

バージョン 内容
1.0.0 –
1.1.0 データが追加できなかった場合の返り値が不正だったのを修正
1.1.5 ID以外のプライマリキーを持つテーブルへのインサートに対応した
1.1.11 $date_init引数によってインサート時の日時自動挿入を制御できるようにした

使用例

<?php
global $cdbt;
$table_name = "prefix_tablename";
list($result, , $table_schema) = $cdbt->get_table_schema($table_name);
if ($result && !empty($table_schema)) {
    $id = $cdbt->insert_data($table_name, array('account_name' => 'john', 'gender' => 'male'), $table_schema);
} else {
    $id = $cdbt->insert_data($table_name, array('account_name' => 'john', 'gender' => 'male'));
}
echo $id;