データベース・キャッシュの記事一覧|WordPressの専門家が作る教科書 https://wordpress.ks-product.com WordPressを活用したウェブサイトの制作方法を教えます Fri, 30 Oct 2026 23:00:00 +0000 ja hourly 1 https://wordpress.org/?v=7.1.5 $wpdb->insert・update の戻り値とエラーの確認方法 https://wordpress.ks-product.com/3079/ Fri, 30 Oct 2026 23:00:00 +0000 https://wordpress.ks-product.com/?p=3079 結論

$wpdb->insert() と $wpdb->update() の戻り値は、成功なら影響を受けた行数(int)、失敗なら false です。ここで重要なのは、update() が返す 0 は失敗ではないことです。「該当行が無い」場合だけでなく、「該当行はあったが、既に同じ値だったので変更が不要だった」場合も 0 になります。

したがって、成否の判定は必ず厳密比較で書きます。

$result = $wpdb->update( $table, $data, $where );
if ( false === $result ) {
    // エラー: $wpdb->last_error を確認
}

if ( ! $result ) と書くと、正常な「0行更新」をエラー扱いしてしまいます。

原因・仕組み

公式リファレンスでは、wpdb::insert( $table, $data, $format ) は挿入した行数か false を返し、直前の挿入 ID は $wpdb->insert_id で得られます。$format を省略すると、値は文字列として扱われます(wpdb が知っている列型があればそれが優先)。また、insert() や update() は値を自動でエスケープするため、prepare() は不要です。

update( $table, $data, $where, $format, $where_format ) は、更新した行数または false を返します。公式リファレンスは、0 が失敗を意味しないこと、そして false === $updated で厳密に比較することを明記しています。

手順(サンプルコード)

global $wpdb;
$table = $wpdb->prefix . 'my_log';

$ok = $wpdb->insert(
    $table,
    array( 'msg' => $message, 'n' => $count ),
    array( '%s', '%d' )          // data と同じ並び・同じ個数で指定
);
if ( false === $ok ) {
    error_log( 'insert failed: ' . $wpdb->last_error );
    return new WP_Error( 'db_insert', 'ログの保存に失敗しました。' );
}
$new_id = (int) $wpdb->insert_id;

$updated = $wpdb->update(
    $table,
    array( 'n' => $count + 1 ),
    array( 'id' => $new_id ),
    array( '%d' ),
    array( '%d' )
);
if ( false === $updated ) {
    error_log( 'update failed: ' . $wpdb->last_error );
} elseif ( 0 === $updated ) {
    // 成功だが、変更なし(同じ値、または該当行なし)
}

「行が存在するか」を厳密に知りたいときは、別途 SELECT で確認します。INSERT ... ON DUPLICATE KEY UPDATE が必要な場合は、prepare() を使った query() で書きます。

動作確認(検証環境と結果)

WordPress 7.1.2(ja)/PHP 8.2.12/MariaDB 10.4.32。検証用の一時テーブル(id, msg varchar(10), n int)を作って実行し、最後に削除しました(tests フォルダの p12.php)。

insert: 1 id=1
bad column insert: false | err: Unknown column 'nope' in 'field list'
update same value: 0
update changed: 1
update no match: 0
update bad column: false | err: Unknown column 'zzz' in 'field list'
too long: false | err: ... 次のフィールドの値の処理に失敗しました: msg。...
delete: 1
  • 存在しない列を指定すると、insert も update も false を返し、last_error に MySQL のエラーが入りました。
  • 同じ値での update と、該当行が無い update は、どちらも 0 でした。区別はできません。
  • varchar(10) の列に30文字を入れようとすると、wpdb が事前に検知して false を返しました。この場合、last_query は直前のクエリのままで、実際の INSERT は送信されていませんでした。
  • $wpdb->show_errors( false ) にしていない場合は、画面にエラー文が出力されます。

$wpdb->insert・update の戻り値とエラーの確認方法の注意点

  • last_error は、直後に読みます。間に別のクエリを実行すると上書きされます。
  • $format の長さは $data の個数と一致させます。wpdb::process_field_formats() のソースを見ると、足りない分には最初の書式が使われるため、エラーにならずに意図しない型(例: 文字列を %d で整数化)で保存されることがあります。
  • 本番では show_errors() を有効にせず、ログに出力します。
  • insert_id は AUTO_INCREMENT 列を持つテーブルで、直前の INSERT に対する値です。複数の処理が並行しても、接続ごとの値なので混ざりません。
  • NULL を入れたい場合は、値に null を渡します。$format に関わらず NULL になると公式にあります。
  • テーブルの作成・変更は、dbDelta() を使うのが基本です。

$wpdb->insert・update の戻り値とエラーの確認方法でよくあるミス

  • if ( $wpdb->update(...) ) と書き、変更が無いだけの更新を失敗扱いにする。
  • if ( $wpdb->insert(...) == false ) のように緩い比較を使う(0 == false は真)。
  • $wpdb->prepare() を insert() にも付けて、二重にエスケープする。
  • $wpdb->insert_id を失敗後にも参照し、前回の値を使ってしまう。
  • ユーザーが送信した配列を、そのまま $data に渡して、意図しない列を更新させる。キーを許可リストで絞ります。

$wpdb->insert・update の戻り値とエラーの確認方法のチェックリスト

  • 戻り値を false === で比較している
  • エラー時に last_error をログに残している
  • $format の個数が $data と一致している
  • 更新対象の列名を許可リストで絞っている
  • 本番で show_errors() を有効にしていない

$wpdb->insert・update の戻り値とエラーの確認方法のFAQ(よくある質問)

Q. update の結果で、該当行が無かったことを知るには。
A. 事前に SELECT で確認するか、insert と update を使い分けるロジックを組みます。

Q. $wpdb->replace() との違いは。
A. 主キーが重複した場合、既存行を削除してから挿入します。部分更新には向きません。

Q. 複数行を一括で挿入したい。
A. prepare() で VALUES を組み立てる query() を使います。IN 句と同様、プレースホルダを動的に作ります。

筆者の見解($wpdb->insert・update の戻り値とエラーの確認方法)

0 と false の区別は、小さな違いですが、運用中の障害調査で効いてくると考えています。私見では、$wpdb を呼ぶ箇所を小さなラッパー関数にまとめ、失敗時に WP_Error を返す形に統一しておくと、呼び出し側の分岐も読みやすくなります。

$wpdb->insert・update の戻り値とエラーの確認方法の関連項目

出典(一次情報)

]]>
transient とオブジェクトキャッシュの違い|使い分け https://wordpress.ks-product.com/3078/ Wed, 28 Oct 2026 23:00:00 +0000 https://wordpress.ks-product.com/?p=3078 結論
  • transient(set_transient): 有効期限つきで保存する仕組み。外部オブジェクトキャッシュが無ければ wp_options テーブルに保存され、リクエストをまたいで残ります。外部オブジェクトキャッシュがあれば、そちらに保存されます。
  • オブジェクトキャッシュ(wp_cache_set): 既定ではメモリ上にだけ置かれ、そのリクエストが終われば消えます。Redis や Memcached などの永続バックエンドを入れたときに、はじめてリクエストをまたいで残ります。

「外部 API の結果を数分〜数時間保持したい」なら transient、「同じリクエスト内で同じ重い処理を2回しない」ならオブジェクトキャッシュ、が基本の使い分けです。

原因・仕組み

公式リファレンスによると、set_transient( $transient, $value, $expiration ) の名前は172文字まで、期限は秒数で、0(既定)は期限なしです。外部オブジェクトキャッシュが有効な場合、transient はデータベースを使わずそのキャッシュに保存されます。また、期限なしの transient は autoload(毎ページ読み込み)の対象になり、期限つきのものは対象になりません。

一方 wp_cache_set( $key, $data, $group, $expire ) は WordPress が内部で使っているキャッシュ API で、投稿やオプションの取得結果もここに入っています。永続化は差し込まれたバックエンド次第です。つまり、テーマやプラグインの作者は、サイトにどちらがあるか分からない前提で書く必要があります。

手順(サンプルコード)

外部 API の結果を1時間 transient に保存する典型例です。

function my_get_rates() {
    $rates = get_transient( 'my_rates' );
    if ( false !== $rates ) {
        return $rates;
    }
    $res = wp_remote_get( 'https://example.com/api/rates' );
    if ( is_wp_error( $res ) || 200 !== wp_remote_retrieve_response_code( $res ) ) {
        return array(); // 失敗は保存しない(または短い期限で保存)
    }
    $rates = json_decode( wp_remote_retrieve_body( $res ), true );
    set_transient( 'my_rates', $rates, HOUR_IN_SECONDS );
    return $rates;
}

同じリクエスト内の重複計算を避けるには、オブジェクトキャッシュを使います。$found を受け取ると、false や空配列を保存した場合も区別できます。

function my_expensive_count() {
    $count = wp_cache_get( 'my_count', 'my_plugin', false, $found );
    if ( $found ) {
        return $count;
    }
    $count = my_heavy_query();
    wp_cache_set( 'my_count', $count, 'my_plugin' );
    return $count;
}

データを更新したときは、delete_transient( 'my_rates' ) や wp_cache_delete( 'my_count', 'my_plugin' ) で古い値を消します。

動作確認(検証環境と結果)

WordPress 7.1.2(ja)/PHP 8.2.12/MariaDB 10.4.32、外部オブジェクトキャッシュなしの環境で、run.php から実行しました(tests フォルダの p2.php)。

same request: 'v'
transient: {"a":1}
options row: true
timeout row: future
autoload: off
miss hit
  • set_transient の値は wp_options に _transient_demo_t として保存され、期限(_transient_timeout_demo_t)は未来の時刻でした。期限つきの autoload は off でした。
  • wp_cache_get の2回呼びは、1回目が miss、2回目が hit でした。
  • レビュー時に、1回目の実行で wp_cache_set( 'rp2k', 'v', 'rp2g' ) し、別プロセスの2回目の実行で wp_cache_get() したところ、値は false、$found も false でした。外部オブジェクトキャッシュが無い環境では、wp_cache の値は次のリクエストに残りません。

transient とオブジェクトキャッシュの違いの注意点

  • transient の期限は「最短でこの時間は残さない」ではなく、期限を過ぎても自動では消えない場合があります(期限切れ行は取得時や掃除処理で削除されます)。期限を過ぎた値は get_transient が false を返すだけだと考えてください。
  • 外部キャッシュの有無で保存先が変わるため、「wp_options に transient がある前提」でデータベースを直接読む実装は避けます。
  • 保存する値が false だと、未保存と区別できません。false を入れたいときは配列に包むか、0 や空文字を使います。
  • 既存の transient を期限指定なし(0)で set_transient() し直すと、値だけが更新され、前回の期限はそのまま残ります(レビュー時の検証: 60秒で保存→期限なしで再保存→_transient_timeout_ は残り約60秒のまま、値は新しいもの)。期限を延ばしたいときは、更新時も期限を渡します。

transient とオブジェクトキャッシュの違いでよくあるミス

  • wp_cache_set を「永続キャッシュ」と思い込み、次のリクエストでも残ると期待する。
  • 利用者ごとに異なる値を共通のキー名で transient に入れる。キーにユーザーIDやパラメータのハッシュを含めます。
  • 失敗した API 応答をそのまま1時間保存してしまい、復旧後も古いエラーが返る。
  • 管理画面で更新した設定が反映されない原因が、削除し忘れた transient だった、というケース。

transient とオブジェクトキャッシュの違いのチェックリスト

  • リクエストをまたいで残したい値は transient(または option)にしている
  • 同一リクエスト内の重複処理は wp_cache_* で省いている
  • キー名に衝突しない接頭辞を付けた(172文字以内)
  • 更新時に古いキャッシュを削除する処理がある
  • false を保存する場合の区別方法を決めた

transient とオブジェクトキャッシュの違いのFAQ(よくある質問)

Q. transient と option はどちらがよいですか。
A. 期限が必要で再取得できる値は transient、設定値のように消えては困るものは option です。

Q. 外部オブジェクトキャッシュを入れると、コードは変えるべきですか。
A. 基本的に不要です。同じ API のまま、保存先だけが切り替わります。

Q. マルチサイトでは。
A. サイト全体で共有したい値には set_site_transient を使います。

筆者の見解(transient とオブジェクトキャッシュの違い)

私見では、迷ったときは「消えても再生成できる値か」で判断するのが分かりやすいと考えます。再生成できて、しかも複数リクエストで使い回したいなら transient、リクエスト内だけなら wp_cache_*、消えると困るなら option です。外部キャッシュの有無は環境次第なので、どちらの環境でも動く書き方にしておくのが無難です。

transient とオブジェクトキャッシュの違いの関連項目

出典(一次情報)

]]>
WordPress プラグイン自作でデータベースに独自テーブルを作る方法|dbDelta とバージョン管理 https://wordpress.ks-product.com/3177/ Sun, 25 Oct 2026 23:00:00 +0000 https://wordpress.ks-product.com/?p=3177 結論

WordPress のプラグイン自作で、データベースに独自のテーブルを作るときは、次の3点を組み合わせるのが公式の Plugin Handbook に沿ったやり方です。

  1. テーブル作成は dbDelta() に CREATE TABLE 文を渡して行う(wp-admin/includes/upgrade.php を読み込んでから呼ぶ)
  2. 実行のタイミングは プラグインの有効化時(register_activation_hook())
  3. テーブル構造の版をオプションに保存し、プラグイン更新時は plugins_loaded で版を比べて再実行する

dbDelta() は「今あるテーブルと、渡した CREATE TABLE 文の差分」を見て、足りない列やインデックスを ALTER TABLE で足してくれます。そのため、同じ関数を新規インストールにも構造の変更にも使えます。

まず、投稿メタやオプションで足りないかを先に検討してください。独自テーブルは、件数が多いログや集計など、wp_postmeta に入れると検索が重くなるデータに向いています。

原因・仕組み

dbDelta(WordPress 1.5.0 から存在)は、$queries(SQL 文字列または配列)と $execute(既定 true)を受け取り、実行した変更内容を文字列の配列で返します。定義されているのは wp-admin/includes/upgrade.php で、フロント側のリクエストでは読み込まれていないため、require_once が必要です。

この関数は SQL をそのまま流すのではなく、文字列を解析して既存の構造と比べるため、書式に厳しい決まりがあります。Plugin Handbook が挙げている主な条件は次の通りです。

  • 1行に1フィールドを書く
  • PRIMARY KEY と定義の間は空白2つ
  • INDEX ではなく KEY を使い、少なくとも1つの KEY を含める
  • フィールド名をバッククォートや引用符で囲まない
  • 型は小文字、CREATE TABLE などの SQL キーワードは大文字
  • 長さを取る型はすべて長さを指定する

文字コードと照合順序は、WordPress 3.5 で追加された $wpdb->get_charset_collate() で、サイトの設定に合わせます。これを付けないと、サーバーの既定の文字コードでテーブルが作られ、日本語が化ける原因になります。

手順(サンプルコード)

プラグインのメインファイル(例: my-plugin/my-plugin.php)に書きます。

<?php
/*
 * Plugin Name: My Plugin Logs
 */
if ( ! defined( 'ABSPATH' ) ) {
    exit; // 直接アクセスを防ぐ
}

define( 'MYPL_DB_VERSION', '1.1' );

function mypl_install() {
    global $wpdb;
    $table   = $wpdb->prefix . 'mypl_logs';
    $charset = $wpdb->get_charset_collate();

    $sql = "CREATE TABLE $table (
  id bigint(20) unsigned NOT NULL AUTO_INCREMENT,
  user_id bigint(20) unsigned NOT NULL default 0,
  message text NOT NULL,
  status varchar(20) NOT NULL default 'new',
  created_at datetime NOT NULL default '0000-00-00 00:00:00',
  PRIMARY KEY  (id),
  KEY user_id (user_id)
) $charset;";

    require_once ABSPATH . 'wp-admin/includes/upgrade.php';
    dbDelta( $sql );

    update_option( 'mypl_db_version', MYPL_DB_VERSION );
}
register_activation_hook( __FILE__, 'mypl_install' );

// 更新時(有効化フックは更新では走らない)の構造変更
function mypl_update_db_check() {
    if ( get_option( 'mypl_db_version' ) !== MYPL_DB_VERSION ) {
        mypl_install();
    }
}
add_action( 'plugins_loaded', 'mypl_update_db_check' );

データの追加は $wpdb->insert() に書式(%d %s)を渡し、値を SQL に直接埋め込まないようにします。

global $wpdb;
$wpdb->insert(
    $wpdb->prefix . 'mypl_logs',
    array(
        'user_id'    => get_current_user_id(),
        'message'    => sanitize_text_field( $message ),
        'created_at' => current_time( 'mysql' ),
    ),
    array( '%d', '%s', '%s' )
);

読み出しで条件に外部の値を使うときは $wpdb->prepare() を通します。

$rows = $wpdb->get_results(
    $wpdb->prepare( "SELECT * FROM {$wpdb->prefix}mypl_logs WHERE user_id = %d ORDER BY id DESC LIMIT 20", $user_id )
);

動作確認(検証環境と結果)

WordPress 7.1.2(ja)/PHP 8.2.12/MariaDB 10.4.32 の CLI 検証環境で、上と同じ構造の関数を「列 status なし(版1.0)→同じ内容でもう一度→status を足した版1.1」の順に実行しました(php run.php wl2_dbdelta.php、ログは tests/plugin-custom-table-dbdelta.md)。

1st (v1.0):  [wp_mypl_logs] => Created table wp_mypl_logs
2nd same (v1.0): (空の配列)
3rd (v1.1 add column): [wp_mypl_logs.status] => Added column wp_mypl_logs.status
insert=1 id=1
cols=id,user_id,message,created_at,status
row status=new
charset=DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_520_ci
  • 1回目はテーブルが作られ、同じ文での2回目は何も変更されず(空配列)、列を足した3回目は Added column だけが実行されました。既存データを消さずに構造を足せることが確認できます。
  • その後、定義から status を外した文でもう一度実行すると、戻り値は空配列で、status 列はそのまま残りました(dbDelta は列を消さない)。
  • 足した列 status は、SQL に書いた位置(created_at の前)ではなく末尾に追加されました。
  • PRIMARY KEY (id)(空白1つ)でも、この環境ではエラーは出ず、2回目の実行も空配列でした。ただし公式の Handbook は空白2つを求めているので、記事のコードは公式どおりにしています。
  • 有効化フック自体の発火(管理画面での有効化)はこの CLI 環境では確認していません(関数を直接呼んで確認)。最後にテーブルは削除しました。

WordPress プラグイン自作でデータベースに独自テーブルを作る方法の注意点

  • dbDelta() は列の削除やテーブルの削除はしません。列名を変えると、古い列が残ったまま新しい列が足されます。削除はアンインストール処理(uninstall.php や register_uninstall_hook())で DROP TABLE を自分で書きます。
  • テーブル名には必ず $wpdb->prefix を付けます。マルチサイトや接頭辞を変えたサイトでも衝突しません。
  • register_activation_hook() は、WordPress 3.1 以降、プラグインを更新しただけでは実行されません(Make WordPress Core の告知)。告知でも勧められているとおり、構造を変えたら版番号を保存して比べる、上の plugins_loaded のような版チェックが必要です。
  • $wpdb->prepare() でテーブル名をプレースホルダにしないでください(値用です)。テーブル名は $wpdb->prefix から自分で組み立てた固定の文字列を使います。

WordPress プラグイン自作でデータベースに独自テーブルを作る方法でよくあるミス

  • require_once ABSPATH . 'wp-admin/includes/upgrade.php'; を忘れ、Call to undefined function dbDelta() で致命的エラーになる。
  • フィールド名をバッククォートで囲んだり、INDEX と書いたりして、2回目以降に余計な ALTER が走る・差分が正しく取れない。
  • register_activation_hook() をクラスのメソッドやフックの中で呼び、登録が間に合わずテーブルが作られない(メインファイルの直下で呼びます)。
  • 版をオプションに保存せず、更新のたびに何が変わったか追えなくなる。

WordPress プラグイン自作でデータベースに独自テーブルを作る方法のチェックリスト

  • まず投稿メタ・オプションで足りないかを検討した
  • テーブル名に $wpdb->prefix を付けた
  • get_charset_collate() を付けた
  • PRIMARY KEY の後は空白2つ、KEY を1つ以上書いた
  • upgrade.php を読み込んでから dbDelta() を呼んだ
  • 版をオプションに保存し、更新時に比べている
  • 値の挿入・検索は insert() の書式/prepare() を通している
  • アンインストール時の削除処理を用意した

WordPress プラグイン自作でデータベースに独自テーブルを作る方法のFAQ(よくある質問)

Q. テーブルが作られたか確かめるには。
A. dbDelta() の戻り値に Created table ... が入ります。phpMyAdmin や $wpdb->get_var( "SHOW TABLES LIKE '...'" ) でも確認できます。

Q. 列の型を変えたいときは。
A. CREATE TABLE 文の型を書き換えて版を上げれば、dbDelta が差分を見て変更を試みます。データが変わる変更なので、先にバックアップを取ってください。

Q. 停止したらテーブルを消すべきですか。
A. 停止(deactivation)では消さず、削除(uninstall)のときに消すのが一般的です。停止は一時的なことが多いためです。

筆者の見解(WordPress プラグイン自作でデータベースに独自テーブルを作る方法)

独自テーブルは強力ですが、一度作ると移行・バックアップ・削除の責任をプラグイン側がずっと持つことになります。私見では、「件数が多く、絞り込み検索が必要なデータ」以外は、まず投稿メタやカスタム投稿タイプで設計するほうが保守しやすいと考えます。作る場合は、検証で見たとおり dbDelta は列を足すことは得意でも消すことはしないので、版番号と uninstall 処理を最初から書いておくのが、後から困らない近道だと思います。

WordPress プラグイン自作でデータベースに独自テーブルを作る方法の関連項目

出典(一次情報)

]]>
$wpdb->prepare() の使い方|説明・引数・注意点 https://wordpress.ks-product.com/415/ https://wordpress.ks-product.com/415/#respond Fri, 02 Oct 2026 15:54:57 +0000 https://wordpress.ks-product.com/415/ prepare() は、SQL文に値を安全に埋め込むためのメソッドです。SQLインジェクションの対策として必須です。]]> 説明

$wpdb->prepare() は、SQL文に値を安全に埋め込むためのメソッドです。SQLインジェクションの対策として必須です。

基本構文

$wpdb->prepare( string $query, mixed ...$args ): string|void

引数

  • $query:プレースホルダー付きのSQL(%s、%d、%f)
  • ...$args:埋め込む値

戻り値

安全に整形されたSQL文。

使い方(サンプル)

global $wpdb;
$sql = $wpdb->prepare( "SELECT ID FROM {$wpdb->posts} WHERE post_author = %d", 1 );

注意点

  • プレースホルダーに引用符は付けません。%s が自動で引用符付きになります。
  • LIKE句の値は $wpdb->esc_like() を併用します。
  • プレースホルダーがないクエリを渡すと警告が出ます。

実務での使いどころ

  • ユーザー入力や、変数を含むSQLを、安全に組み立てるとき(SQLインジェクション対策)。
  • WHERE 句に、数値や文字列の値を渡すとき。
  • LIKE 検索で、キーワードを渡すとき。

よくあるミスと対策

  • 変数をSQLの文字列に直接埋め込んでいる。SQLインジェクションの原因になります。
  • プレースホルダーを、引用符で囲んでいる('%s')。prepare() が自動で引用符を付けるため、囲みません(%1$s のような番号付きの書式は、引用符が自動では付かないため、自分で付けます)。
  • LIKE 検索で、キーワード中の % や _ をそのまま渡している。$wpdb->esc_like() を通し、前後の % は、値の側に付けます。
  • プレースホルダーが1つもないクエリに、prepare() を使っている。使う意味がなく、警告の原因にもなります。

NG例

$wpdb->get_results( "SELECT * FROM {$wpdb->posts} WHERE post_title = '$title'" );

OK例

$wpdb->get_results(
	$wpdb->prepare( "SELECT * FROM {$wpdb->posts} WHERE post_title = %s", $title )
);

// LIKE検索の場合
$like = '%' . $wpdb->esc_like( $keyword ) . '%';
$wpdb->get_results(
	$wpdb->prepare( "SELECT ID FROM {$wpdb->posts} WHERE post_title LIKE %s", $like )
);

使い分け早見表

メソッド 取得するもの
$wpdb->get_var() 1つの値
$wpdb->get_row() 1行
$wpdb->get_col() 1列(値の配列)
$wpdb->get_results() 複数行

関連項目

$wpdb->get_results()、$wpdb->esc_like()、esc_sql()、$wpdb->get_row()、$wpdb->get_var()、$wpdb->get_col()

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

]]>
https://wordpress.ks-product.com/415/feed/ 0
$wpdb->get_var() の使い方|説明・引数・注意点 https://wordpress.ks-product.com/414/ https://wordpress.ks-product.com/414/#respond Fri, 02 Oct 2026 15:54:56 +0000 https://wordpress.ks-product.com/414/ get_var() は、SELECT文を実行し、1つの値だけを取得するメソッドです。]]> 説明

$wpdb->get_var() は、SELECT文を実行し、1つの値だけを取得するメソッドです。

基本構文

$wpdb->get_var( string $query = null, int $x = 0, int $y = 0 ): string|null

引数

  • $query:SQL文
  • $x:何列目か
  • $y:何行目か

戻り値

値の文字列。該当なしなら null。

使い方(サンプル)

global $wpdb;
$title = $wpdb->get_var(
	$wpdb->prepare( "SELECT post_title FROM {$wpdb->posts} WHERE ID = %d", 123 )
);

注意点

  • COUNT(*) など、1つの値を取得するクエリに向いています。
  • 戻り値は文字列なので、数値として使うなら型変換が必要です。

実務での使いどころ

  • 1つの値(件数、最大値、1つの列の値)だけを、取得するとき。
  • COUNT(*) の結果を、取得するとき。

よくあるミスと対策

  • 変数を、直接SQLに入れている。$wpdb->prepare() を使う。
  • 値が、文字列で返る。数値として比べるときは、(int) などで、変換する。
  • 見つからないときは null。0 や空文字と、区別して扱わない。

NG例

$count = $wpdb->get_var( "SELECT COUNT(*) FROM {$wpdb->posts} WHERE post_author = $author_id" );
if ( 5 === $count ) { // 文字列 '5' が返り、一致しない
	// ...
}

OK例

$count = (int) $wpdb->get_var(
	$wpdb->prepare( "SELECT COUNT(*) FROM {$wpdb->posts} WHERE post_author = %d", $author_id )
);

使い分け早見表

メソッド 取得するもの
$wpdb->get_var() 1つの値
$wpdb->get_row() 1行
$wpdb->get_col() 1列(値の配列)

関連項目

$wpdb->get_row()、$wpdb->get_results()、$wpdb->prepare()

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

]]>
https://wordpress.ks-product.com/414/feed/ 0
dbDelta() の使い方|説明・引数・注意点 https://wordpress.ks-product.com/413/ https://wordpress.ks-product.com/413/#respond Fri, 02 Oct 2026 15:54:47 +0000 https://wordpress.ks-product.com/413/ 説明

dbDelta() は、テーブルを作成・更新する関数です。プラグイン有効化時のテーブル作成に使います。

基本構文

dbDelta( string|string[] $queries = '', bool $execute = true ): array

引数

  • $queries:テーブル作成のSQL文
  • $execute:実行するか

戻り値

実行した処理の結果の配列。

使い方(サンプル)

require_once ABSPATH . 'wp-admin/includes/upgrade.php';
$sql = "CREATE TABLE {$wpdb->prefix}my_table (
  id bigint(20) NOT NULL AUTO_INCREMENT,
  name varchar(255) NOT NULL,
  PRIMARY KEY  (id)
) {$charset_collate};";
dbDelta( $sql );

注意点

  • wp-admin/includes/upgrade.php の読み込みが必要です。
  • SQLの書式に厳しい制約があります(PRIMARY KEY の後に半角スペース2つなど)。
  • 有効化フックの中で1度だけ呼びます。

実務での使いどころ

  • プラグインの有効化時に、独自のテーブルを、作る・更新するとき。
  • バージョンアップで、テーブルの構造を、変更するとき。

よくあるミスと対策

  • wp-admin/includes/upgrade.php を、読み込んでいない。関数が未定義になる。
  • SQLの書式を守らないと、2回目以降の更新(カラムやインデックスの差分の適用)が、正しく動かないことがある。公式の書式(1行1項目、PRIMARY KEY の後ろはスペース2つ、KEY を使うなど)に従う。
  • 毎回のリクエストで、実行している。有効化時や、バージョンが変わったときだけにする。
  • 文字コードを、指定していない。$wpdb->get_charset_collate() を使う。

NG例

dbDelta( "CREATE TABLE {$wpdb->prefix}logs (id INT PRIMARY KEY, message TEXT)" ); // 書式が違い、ファイルも読み込んでいない

OK例

require_once ABSPATH . 'wp-admin/includes/upgrade.php';
$charset = $wpdb->get_charset_collate();
$sql = "CREATE TABLE {$wpdb->prefix}logs (
  id bigint(20) unsigned NOT NULL AUTO_INCREMENT,
  message text NOT NULL,
  PRIMARY KEY  (id)
) $charset;";
dbDelta( $sql );

使い分け早見表

やりたいこと 使うもの
テーブルを作成・更新 dbDelta()
データを追加・更新 $wpdb->insert()、$wpdb->update()
任意のSQLを実行 $wpdb->query()

関連項目

register_activation_hook()、$wpdb->query()、$wpdb->prepare()

公式リファレンス:dbDelta() | Function | WordPress Developer Resources

]]>
https://wordpress.ks-product.com/413/feed/ 0
$wpdb->esc_like() の使い方|説明・引数・注意点 https://wordpress.ks-product.com/412/ https://wordpress.ks-product.com/412/#respond Fri, 02 Oct 2026 15:54:45 +0000 https://wordpress.ks-product.com/412/ esc_like() は、LIKE検索の値に含まれる % や _ などのワイルドカードをエスケープするメソッドです。]]> 説明

$wpdb->esc_like() は、LIKE検索の値に含まれる % や _ などのワイルドカードをエスケープするメソッドです。

基本構文

$wpdb->esc_like( string $text ): string

引数

  • $text:エスケープする文字列

戻り値

エスケープした文字列。

使い方(サンプル)

global $wpdb;
$like = '%' . $wpdb->esc_like( $keyword ) . '%';
$sql = $wpdb->prepare( "SELECT ID FROM {$wpdb->posts} WHERE post_title LIKE %s", $like );

注意点

  • prepare() に渡す前に使います。

実務での使いどころ

  • LIKE 検索で、キーワードに含まれる、% や _ を、ただの文字として、扱うとき。

よくあるミスと対策

  • キーワードを、esc_like() に通さず、% を、ワイルドカードとして、解釈させている。
  • % を付けてから、esc_like() に通している。% も、エスケープされる。esc_like() のあとに、% を付ける。
  • esc_like() だけで、SQLの安全が確保できると考えている。$wpdb->prepare() も、併用する。

NG例

$like = $wpdb->esc_like( '%' . $keyword . '%' ); // % もエスケープされる

OK例

$like = '%' . $wpdb->esc_like( $keyword ) . '%';
$rows = $wpdb->get_results(
	$wpdb->prepare( "SELECT ID FROM {$wpdb->posts} WHERE post_title LIKE %s", $like )
);

使い分け早見表

関数 役割
$wpdb->esc_like() LIKE 用に、特殊文字をエスケープする
$wpdb->prepare() 値を含むSQLを、安全に組み立てる
esc_sql() SQL用に、文字列をエスケープする

関連項目

$wpdb->prepare()

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

]]>
https://wordpress.ks-product.com/412/feed/ 0
$wpdb->get_col() の使い方|説明・引数・注意点 https://wordpress.ks-product.com/411/ https://wordpress.ks-product.com/411/#respond Fri, 02 Oct 2026 15:54:42 +0000 https://wordpress.ks-product.com/411/ get_col() は、SELECT文を実行し、1列分の値を配列で取得するメソッドです。]]> 説明

$wpdb->get_col() は、SELECT文を実行し、1列分の値を配列で取得するメソッドです。

基本構文

$wpdb->get_col( string $query = null, int $x = 0 ): array

引数

  • $query:SQL文
  • $x:何列目か

戻り値

値の配列。

使い方(サンプル)

global $wpdb;
$ids = $wpdb->get_col( "SELECT ID FROM {$wpdb->posts} LIMIT 10" );

注意点

  • IDの一覧を取得するときに便利です。

実務での使いどころ

  • 1列の値を、配列として、取得するとき(IDの一覧など)。

よくあるミスと対策

  • 変数を、直接SQLに入れている。$wpdb->prepare() を使う。
  • 結果が、1件もないときは、空の配列。
  • 複数の列が欲しいのに、使っている。1列だけが、取得される。

NG例

$ids = $wpdb->get_col( "SELECT ID FROM {$wpdb->posts} WHERE post_author = $author_id" ); // 変数を直接入れている

OK例

$ids = $wpdb->get_col(
	$wpdb->prepare( "SELECT ID FROM {$wpdb->posts} WHERE post_author = %d AND post_status = 'publish'", $author_id )
);

使い分け早見表

メソッド 取得するもの
$wpdb->get_col() 1列(値の配列)
$wpdb->get_results() 複数行
$wpdb->get_var() 1つの値

関連項目

$wpdb->get_results()、$wpdb->get_var()

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

]]>
https://wordpress.ks-product.com/411/feed/ 0
$wpdb->get_row() の使い方|説明・引数・注意点 https://wordpress.ks-product.com/410/ https://wordpress.ks-product.com/410/#respond Fri, 02 Oct 2026 15:54:40 +0000 https://wordpress.ks-product.com/410/ get_row() は、SELECT文を実行し、1行分の結果を取得するメソッドです。]]> 説明

$wpdb->get_row() は、SELECT文を実行し、1行分の結果を取得するメソッドです。

基本構文

$wpdb->get_row( string $query = null, string $output = OBJECT, int $y = 0 ): array|object|null|void

引数

  • $query:SQL文
  • $output:返却形式
  • $y:何行目を返すか(0始まり)

戻り値

1行分のデータ。該当なしなら null。

使い方(サンプル)

global $wpdb;
$row = $wpdb->get_row(
	$wpdb->prepare( "SELECT * FROM {$wpdb->posts} WHERE ID = %d", 123 )
);

注意点

  • 値は prepare() でプレースホルダーに渡します。
  • 該当なしの場合に備え、null の判定をします。

実務での使いどころ

  • 1行だけの結果を、取得するとき(IDを指定した、1件の取得など)。

よくあるミスと対策

  • 変数を、直接SQLに入れている。$wpdb->prepare() を使う。
  • 見つからないときは null。確認せずに、プロパティへアクセスする。
  • 複数行を取得したいのに、使っている。2行目以降は、取得されない。

NG例

$row = $wpdb->get_row( "SELECT * FROM {$wpdb->prefix}logs WHERE id = $id" );
echo $row->message; // 変数を直接入れ、見つからない場合も確認していない

OK例

$row = $wpdb->get_row(
	$wpdb->prepare( "SELECT * FROM {$wpdb->prefix}logs WHERE id = %d", $id )
);
if ( $row ) {
	echo esc_html( $row->message );
}

使い分け早見表

メソッド 取得するもの
$wpdb->get_row() 1行
$wpdb->get_results() 複数行
$wpdb->get_var() 1つの値

関連項目

$wpdb->get_results()、$wpdb->get_var()

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

]]>
https://wordpress.ks-product.com/410/feed/ 0
$wpdb->get_results() の使い方|説明・引数・注意点 https://wordpress.ks-product.com/409/ https://wordpress.ks-product.com/409/#respond Fri, 02 Oct 2026 15:54:38 +0000 https://wordpress.ks-product.com/409/ get_results() は、SELECT文を実行し、結果の複数行を配列で取得するメソッドです。]]> 説明

$wpdb->get_results() は、SELECT文を実行し、結果の複数行を配列で取得するメソッドです。

基本構文

$wpdb->get_results( string $query = null, string $output = OBJECT ): array|object|null

引数

  • $query:SQL文
  • $output:OBJECT / ARRAY_A / ARRAY_N / OBJECT_K

戻り値

結果の配列。該当なしなら空配列。

使い方(サンプル)

global $wpdb;
$rows = $wpdb->get_results(
	$wpdb->prepare( "SELECT ID, post_title FROM {$wpdb->posts} WHERE post_status = %s LIMIT %d", 'publish', 5 )
);

注意点

  • 値を埋め込むSQLは、必ず $wpdb->prepare() を通します。
  • テーブル名は $wpdb->posts のようなプロパティで指定し、接頭辞を直書きしません。
  • 大量の行を取得するとメモリを圧迫します。

実務での使いどころ

  • 複数行の結果を、取得するとき。
  • カスタムテーブルや、投稿の独自の検索結果を、取得するとき。

よくあるミスと対策

  • 変数を、直接SQLに入れている。SQLインジェクションの原因になる。$wpdb->prepare() を使う。
  • 結果が、1件もないときは、空の配列。失敗と、区別して扱わない。
  • 大量のデータを、一度に取得している。LIMIT で、件数を絞る。
  • $output の既定は、オブジェクト。配列で受け取りたいときは、ARRAY_A を指定する。

NG例

$rows = $wpdb->get_results( "SELECT * FROM {$wpdb->prefix}logs WHERE user_id = $user_id" ); // 変数を直接入れている

OK例

$rows = $wpdb->get_results(
	$wpdb->prepare( "SELECT * FROM {$wpdb->prefix}logs WHERE user_id = %d LIMIT 100", $user_id )
);
foreach ( $rows as $row ) {
	echo esc_html( $row->message );
}

使い分け早見表

メソッド 取得するもの
$wpdb->get_results() 複数行
$wpdb->get_row() 1行
$wpdb->get_var() 1つの値
$wpdb->get_col() 1列(値の配列)

関連項目

$wpdb->prepare()、$wpdb->get_row()、$wpdb->get_var()

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

]]>
https://wordpress.ks-product.com/409/feed/ 0