wpdb::replace()
Оновлює або створює рядок у таблиці.
Якщо рядок із вказаним ключем PRIMARY KEY вже є всі інші вказані поля будуть оновлені у рядку. Якщо такого рядка в таблиці ще немає, функція вставить (insert) новий рядок.
Після вставки, ID створений для колонки AUTO_INCREMENT можна отримати як $wpdb->insert_id .
Метод включає захист від ін’єкцій SQL. Тобто. можна передавати неочищені дані, наприклад, із параметрів запиту: $_GET['foo'].
Для вставлення нового рядка необов’язково вказувати поле з автоінкрементом. Наприклад, ми маємо таблицю з полем id(AUTO_INCREMENT). Можна вказати значення всіх полів, крім id, і рядок буде додано до таблиці.
PRIMARY KEY може складатися з кількох ключів. У цьому випадку при пошуку для заміни існуючого рядка завжди будуть використовуватися всі колонки, зазначені в PRIMARY KEY. Всі інші поля, крім полів з PRIMARY KEY, не беруть участі в пошуку існуючих рядків.
Наприклад, PRIMARY KEY і двох колонок ID і type : PRIMARY KEY (ID,type). Тоді для заміни існуючого рядка у параметрі $data потрібно вказати значення цих двох колонок. Якщо наприклад вказати ID і не вказати type, то існуючий рядок не буде знайдено і буде створено новий рядок із зазначеним ID та дефолтним значенням type.
Якщо довжина рядка у параметрі $data більша, ніж допускається в комірці таблиці MySQL, вставка провалиться і функція поверне false. При цьому у властивості $wpdb->last_error повідомлення про помилку НЕ буде записано! Втім це стосується й інших методів wpdb .
Тому дуже важливо переконатися, що дані, що вставляють, підходять під розмір осередків (колонок). Інакше просто нічого не станеться і ви не побачите жодних помилок чи попереджень.
Завжди замінюються усі поля таблиці. Наприклад, якщо таблиця має поля primary, one, two, three, а ми вказали в параметрі $data тільки primary, one, то поля twoй threeотримають дефолтні значення, навіть якщо там вже були дані.
Може відбутися заміна відразу кількох наявних рядків – це коли дані, що замінюються, збігаються з існуючими, а унікальний індекс у наявних рядків різний.
{} Це метод класу: wpdb{}
wpdb::_insert_replace_helper()
Хуків немає.
Повертає
int|false. Число (кількість оброблених рядків), 0 чи false.
число– скільки рядків було оброблено (видалено чи вставлено). Якщо була заміна (оновлення), то для кожного оновленого рядка повернеться +2 (видалення та вставка). Якщо була просто вставка, то для кожного вставленого рядка повернеться +1.0– запит було виконано коректно, але жодний рядок не було опрацьовано.false– Запит провалився – помилка запиту. Або коли неможливо замінити або створити новий рядок у таблиці.
Поверне кількість порушених рядків – це сума вставлених та віддалених рядків. Якщо повернулося 1 при заміні одного рядка – це означає, що один рядок була вставлена і жодна не була видалена. Якщо число більше 1 – це означає, що один або більше рядків були видалені перед вставкою нового рядка.
Використання
global $wpdb; $wpdb->replace( $table, $data, $format );
-
$table
(рядок) (обов’язковий) - Назва таблиці, де потрібно замінити дані.
-
$data
(масив) (обов’язковий) Дані, які потрібно замінити/вставити у форматі
[ 'название колонки' => 'новое значение' ].Якщо в значенні вказати NULL , то значення буде встановлено в NULL , відповідний формат при цьому ігнорується.
-
$format
(масив/рядок) Масив форматів даних, які будуть асоційовані із зазначеними значеннями у параметрі $data . Якщо зазначений рядок, то він (формат) буде асоційований з усіма даними. При вказівці формату WordPress переводить передані дані у вказаний формат перед створенням запиту. Можливі формати:
%s– Рядок%d– ціле число%f– дробове число
Якщо не вказати, то для всіх значень $data буде вказано формат
строка, якщо інше не зазначено у властивості wpdb::$field_types .
Типово: null
Приклади
#1 Замінимо рядок із головним ключем ID = 1
(мається на увазі, що таблиця складається з трьох колонок ID, column1, column2).
Рядок буде додано, якщо його немає або повністю оновлено, якщо воно є. Тут важливо вказувати значення для всіх полів, тому що поля без значень отримають дефолтні, навіть якщо в них були дані.
$wpdb->replace( 'table_name', [ 'ID' => 1, 'column1' => 'value1', 'column2' => 123 ]);
#2 Вкажемо формати
$wpdb->replace( 'table', [ 'column' => 'foo', 'field' => 1337 ], [ '%s', '%d' ) );
нотатки
- Дивіться: wpdb::prepare()
- Дивіться: wpdb::$field_types
- Дивіться: wp_set_wpdb_vars()
список змін
| З версії 3.0.0 | Введено. |
wpdb::replace WP 6.0.2
public function replace( $table, $data, $format = null ) {
return $this->_insert_replace_helper( $table, $data, $format, 'REPLACE' );
}