Перейти до вмісту

База даних

Рівень бази даних дає змогу визначити модель даних блоку у файлі db.php. Blockstudio генерує кінцеві точки CRUD REST, перевіряє вхідні дані за схемою, автоматично керує сховищем і надає клієнт JavaScript (bs.db()) та PHP API (клас Db).

Це основа даних для повностекових блоків. Якщо RPC обробляє власну логіку, рівень бази даних працює зі структурованими даними без шаблонного коду.

Як це працює

  1. Створіть db.php у каталозі блоку
  2. Він повертає схему: поля, типи, правила перевірки даних і контроль доступу
  3. Blockstudio створює сховище (таблицю, файл або метадані запису)
  4. Автоматично генеруються п’ять кінцевих точок REST (список, отримання, створення, оновлення, видалення)
  5. bs.db() і Db::get() надають клієнтський і серверний доступ

Жодних міграцій, контролерів чи реєстрації маршрутів.

Передавайте буквальні значення в API REST і PHP. Бекенди meta і post_type самостійно обробляють екранування метаданих WordPress, зберігаючи зворотні скісні риски та рядки в лапках як у скалярних значеннях, так і у вкладених об’єктах чи масивах. Не екрануйте наперед значення записів бази даних.

Визначення схем

Одна схема

Найпростіший варіант: одна модель даних на блок.

PHP
return [
    'storage'    => 'table',
    'capability' => [
        'create' => true,
        'read'   => true,
        'update' => 'edit_posts',
        'delete' => 'manage_options',
    ],
    'fields' => [
        'email' => ['type' => 'string', 'format' => 'email', 'required' => true],
        'name'  => ['type' => 'string', 'maxLength' => 100],
        'plan'  => ['type' => 'string', 'enum' => ['free', 'pro'], 'default' => 'free'],
    ],
];

Синтаксис конструктора, нативний для PHP

db.php також може використовувати невеликий конструктор API, побудований на іменованих аргументах і незмінних об’єктах визначень. Масиви залишаються форматом за замовчуванням, але це дає зручнішу для розуміння альтернативу, нативну для PHP, коли схема розростається.

PHP
<?php
use Blockstudio\Db\Field;
use Blockstudio\Db\Schema;
use Blockstudio\Db\Storage;

return Schema::make(
    storage: Storage::Table,
    capability: [
        'create' => true,
        'read'   => true,
        'update' => 'edit_posts',
        'delete' => 'manage_options',
    ],
    fields: [
        'email' => Field::string(required: true, format: 'email'),
        'name'  => Field::string(maxLength: 100),
        'plan'  => Field::string(enum: ['free', 'pro'], default: 'free'),
    ],
);

Використовуйте Schema::make() для однієї схеми або повертайте іменований масив викликів Schema::make(...) для блоків із кількома схемами.

Кілька схем

Один блок може містити кілька моделей даних. Поверніть іменований масив:

PHP
return [
    'subscribers' => [
        'storage' => 'table',
        'fields'  => [
            'email' => ['type' => 'string', 'format' => 'email', 'required' => true],
            'plan'  => ['type' => 'string', 'enum' => ['free', 'pro']],
        ],
    ],
    'activity_log' => [
        'storage' => 'jsonc',
        'fields'  => [
            'action'  => ['type' => 'string', 'required' => true],
            'details' => ['type' => 'string'],
        ],
    ],
];

Для кожної схеми створюються окремі кінцеві точки, сховище та правила доступу.

Режими зберігання

Шість варіантів сховища для різних сценаріїв використання.

Власна таблиця (storage: "table")

Кожен запис — це рядок в окремій таблиці MySQL. Blockstudio автоматично створює таблицю та керує нею за допомогою функції dbDelta() від WordPress. Додавання нових полів до схеми створює стовпці під час наступного завантаження сторінки. Наявні стовпці ніколи не видаляються.

Найкраще підходить для: структурованих даних, запитів і робочих застосунків.

SQLite (storage: "sqlite")

Для кожної схеми створюється окремий файл бази даних SQLite у підкаталозі db/. Blockstudio автоматично створює файл і таблицю та додає відсутні стовпці після зміни схеми (як dbDelta для MySQL). Використовується режим журналювання WAL для паралельного читання.

Код
blocks/my-block/
├── db.php
└── db/
    └── subscribers.sqlite   ← single-file database

Найкраще підходить для: структурованих даних, яким потрібні повноцінні запити SQL, але які мають залишатися портативними. Ефективно обробляє тисячі записів, не завантажуючи все в пам’ять. Щоб перенести дані, скопіюйте папку.

Файли JSONC (storage: "jsonc")

Записи зберігаються по одному об’єкту JSON у кожному рядку файлу .jsonc в підкаталозі db/. Файл автоматично створюється під час першого запису. Рядки, що починаються з //, вважаються коментарями та зберігаються.

Код
blocks/my-block/
├── db.php
└── db/
    └── subscribers.jsonc    ← one record per line

Найкраще підходить для: невеликих наборів даних, даних на кшталт конфігурацій, початкових записів і прикладів, які можна зберігати під контролем версій. JSONC навмисно є одним файлом у каталозі блоку. Використовуйте його, коли потрібно зберігати дані разом із кодом, а не для великої кількості паралельних записів.

Файли Storh (storage: "storh")

Storh зберігає кожен запис в окремому файлі в каталозі завантажень WordPress:

Код
wp-content/uploads/blockstudio/db/
└── my-theme-my-block/
    └── subscribers/
        ├── data/
        │   └── 00/
        │       ├── 00000000-0000-7000-8000-000000000001.jsonc
        │       └── 00000000-0000-7000-8000-000000000002.jsonc
        ├── .storh/
        │   └── indexes/
        └── .blockstudio/
            └── sequence.json

Публічні ідентифікатори записів залишаються тими самими цілими числами, що й решта ідентифікаторів bs.db(). Blockstudio зіставляє їх із внутрішніми ідентифікаторами файлів UUIDv7 у Storh та зберігає ціле число id у даних запису, тож клієнтам JavaScript, REST і PHP не потрібно працювати з UUID.

PHP
return [
    'storage' => 'storh',
    'fields'  => [
        'title'  => ['type' => 'string', 'required' => true],
        'status' => ['type' => 'string'],
        'count'  => ['type' => 'integer'],
    ],
];

Blockstudio створює індекси Storh на основі вашої схеми. Оскільки кожне оголошене поле можна використовувати як фільтр списку, для кожного такого поля створюється індекс. Для цілочислових, числових полів і полів із датами використовуються індекси діапазонів; для полів із позначками 'unique' => true або 'index' => 'unique' використовуються унікальні індекси.

Найкраще підходить для: виробничих даних у файлах, яким потрібні безпечніший паралельний запис, індекси на основі схеми та портативне сховище на рівні завантажень без збереження поточних записів у дереві вихідного коду блоку.

Перенесення з JSONC до Storh

Якщо ви почали з файлу .jsonc і хочете перенести ті самі записи до Storh, виконайте:

Командна оболонка
wp bs db migrate my-theme/app subscribers --to=storh

Для блоків з однією схемою:

Командна оболонка
wp bs db migrate my-theme/app --to=storh

Міграція зчитує наявний db/{schema}.jsonc, записує дані в Storh зі збереженням цілочислових ідентифікаторів, повторно індексує дані, перевіряє цільове сховище та залишає файл JSONC без змін. Щоб відкотити зміни, достатньо повернути storage схеми до "jsonc".

Метадані запису (storage: "meta")

Записи зберігаються як масив JSON у метаданих запису WordPress і прив’язуються до конкретного запису через postId.

PHP
return [
    'storage' => 'meta',
    'postId'  => 42,
    'fields'  => [ /* ... */ ],
];

Найкраще підходить для: даних, пов’язаних із конкретним записом або сторінкою.

Власний тип запису (storage: "post_type")

Кожен запис — це запис WordPress у власному типі запису, зареєстрованому автоматично. Кожне поле схеми стає окремим значенням post_meta. Завдяки цьому записи можна запитувати за допомогою WP_Query, вони сумісні з плагінами REST API і відображаються в таких інструментах, як GraphQL.

Найкраще підходить для: даних, які мають нативно інтегруватися з WordPress. Кожне поле можна окремо запитувати й індексувати.

Клієнт JavaScript

Blockstudio додає bs.db() на сторінки з блоками бази даних. Він повертає об’єкт із п’ятьма методами:

JavaScript
const db = bs.db('my-theme/block', 'subscribers');

// Create a record
const record = await db.create({ email: 'a@b.com', plan: 'pro' });

// List all records (with optional filters)
const all = await db.list();
const pros = await db.list({ plan: 'pro', limit: 10, offset: 0 });

// Get a single record
const one = await db.get(record.id);

// Update specific fields
const updated = await db.update(record.id, { plan: 'enterprise' });

// Delete a record
await db.delete(record.id);

Перший аргумент — назва блоку (з /), другий — назва схеми. Для блоків з однією схемою назву схеми можна не вказувати (типове значення — "default").

Кеш

bs.cache — це кеш запитів у пам’яті, спільний для всіх викликів bs.query і bs.mutate. Його також можна використовувати безпосередньо:

JavaScript
// Read a cached value
const data = bs.cache.get('my-key');

// Write to the cache
bs.cache.set('my-key', { items: [...] });

// Invalidate a single key
bs.cache.invalidate('my-key');

// Clear all cached entries
bs.cache.clear();

Записи кешу зберігаються в пам’яті та очищаються під час переходу на іншу сторінку. Переважно їх використовують внутрішньо bs.query і bs.mutate, але прямий доступ стане в пригоді для попереднього заповнення даних або ручного скидання кешу після власних операцій.

Запит

bs.query() додає кешування, усунення дублікатів і контроль застарівання до будь-якої асинхронної функції. Кілька викликів з однаковим ключем під час виконання запиту повертають той самий проміс (без повторних запитів).

JavaScript
// Basic cached fetch
const subscribers = await bs.query('subscribers', () =>
  bs.db('my-theme/app', 'subscribers').list()
);

// With staleTime: skip the fetch if cached data is younger than 30 seconds
const subscribers = await bs.query('subscribers', () =>
  bs.db('my-theme/app', 'subscribers').list(),
  { staleTime: 30000 }
);

Перший аргумент — ключ кешу (будь-який рядок). Другий — функція, що повертає проміс. Третій — необов’язковий об’єкт параметрів:

Параметр Тип Опис
staleTime number Кількість мілісекунд, після якої кешовані дані вважаються застарілими. 0 (типове значення) завжди виконує запит повторно.

Якщо кеш містить дані для цього ключа і вони збережені менше ніж staleTime, кешоване значення повертається негайно без виклику функції.

Зміна даних

bs.mutate() виконує операції запису з оптимістичним оновленням і автоматичним відкатом у разі помилки. Є два режими: автоматичний для поширених шаблонів CRUD і ручний для повного контролю.

Автоматичний режим працює з реактивним об’єктом стану (наприклад, Alpine.js $data). Передайте state, key, action і, за бажанням, optimistic:

JavaScript
// Optimistic create: item appears instantly, gets real ID on success
await bs.mutate({
  state: $data,
  key: 'todos',
  action: 'create',
  optimistic: { text: 'New todo', done: false },
  fn: () =>
    bs.db('my-theme/app', 'todos').create({ text: 'New todo', done: false }),
});

// Optimistic update: field changes instantly, reverts on failure
await bs.mutate({
  state: $data,
  key: 'todos',
  action: 'update',
  id: todoId,
  optimistic: { done: true },
  fn: () => bs.db('my-theme/app', 'todos').update(todoId, { done: true }),
});

// Delete: item removed from the array immediately
await bs.mutate({
  state: $data,
  key: 'todos',
  action: 'delete',
  id: todoId,
  fn: () => bs.db('my-theme/app', 'todos').delete(todoId),
});

У разі успіху оптимістичні дані замінюються відповіддю сервера. У разі помилки стан повертається до знімка, зробленого до зміни. Після кожної успішної зміни ключ кешу автоматично стає недійсним.

Помилкою вважається відхилення промісу, повернутого fn. bs.db() і bs.fn() повертають тіло помилки без відхилення промісу у разі помилки перевірки даних, відсутності запису або невдалої перевірки дозволів. Тому, якщо в таких випадках також потрібно виконати відкат, викиньте помилку, коли результат містить code:

JavaScript
const ok = (request) =>
  request.then((result) => {
    if (result?.code) {
      throw result;
    }
    return result;
  });

await bs.mutate({
  state: $data,
  key: 'todos',
  action: 'delete',
  id: todoId,
  fn: () => ok(bs.db('my-theme/app', 'todos').delete(todoId)),
});

Для операцій створення оптимістичному елементу призначається тимчасовий id (наприклад, __temp_1). Коли сервер надсилає відповідь, тимчасовий елемент оновлюється реальними даними, зокрема призначеним сервером id.

Ручний режим надає повний контроль за допомогою зворотних викликів before, onSuccess і onError:

JavaScript
await bs.mutate({
  fn: () => bs.db('my-theme/app', 'todos').create({ text: 'New' }),
  invalidate: 'todos',
  before: () => {
    // Take a snapshot, return it for use in onError
    const snapshot = [...$data.todos];
    $data.todos.push({ id: '__temp', text: 'New' });
    return snapshot;
  },
  onSuccess: (result, snapshot) => {
    // Replace temp item with server response
  },
  onError: (error, snapshot) => {
    // Restore from snapshot
    $data.todos = snapshot;
  },
});
Параметр Тип Режим Опис
fn function Обидва Асинхронна функція, що виконує зміну. Обов’язково.
state object Автоматичний Реактивний об’єкт стану (e.g., Alpine $data).
key string Автоматичний Назва властивості стану, що містить масив. Також використовується як ключ кешу.
action string Автоматичний Одне зі значень: create, update або delete.
id any Автоматичний Ідентифікатор запису для дій update і delete.
optimistic object Автоматичний Дані для оптимістичного застосування до відповіді сервера.
before function Ручний Викликається перед fn. Повернене значення передається в onSuccess/onError як snapshot.
onSuccess function Ручний Викликається з (result, snapshot) у разі успіху.
onError function Ручний Викликається з (error, snapshot) у разі помилки.
invalidate string Ручний Ключ кешу, який потрібно скинути після успіху.

PHP API

Клас Db надає ті самі операції на сервері. Використовуйте його в rpc.php, cron.php, шаблонах або будь-якому коді PHP.

PHP
use Blockstudio\Db;

$db = Db::get('my-theme/block', 'subscribers');

// Create
$record = $db->create(['email' => 'a@b.com', 'plan' => 'pro']);

// List with filters
$all  = $db->list();
$pros = $db->list(['plan' => 'pro'], limit: 10, offset: 0);

// Count and paginate
$count = $db->count(['plan' => 'pro']);
$page  = $db->paginate(['plan' => 'pro'], limit: 10, offset: 20);

// Get by ID
$one = $db->get_record(1);

// Update
$db->update(1, ['plan' => 'enterprise']);

// Delete
$db->delete(1);

Для блоків з однією схемою:

PHP
$db = Db::get('my-theme/block');

Опитування в реальному часі

Додайте realtime до схеми, щоб увімкнути автоматичне опитування. Коли дані на сервері змінюються, UI автоматично оновлюється через сховище API взаємодії. Змінювати JavaScript не потрібно.

PHP
return [
    'storage'  => 'table',
    'realtime' => true,
    'fields'   => [ /* ... */ ],
];

З true, Blockstudio опитує сервер кожні 3 секунди, використовуючи назву схеми як ключ стану в API взаємодії (default для блоків з однією схемою).

Власні параметри

PHP
return [
    'storage'  => 'table',
    'realtime' => [
        'key'      => 'todos',
        'interval' => 5000,
    ],
    'fields' => [ /* ... */ ],
];
Параметр Тип Типове значення Опис
key string назва схеми Назва властивості в state, що містить масив даних
interval number 3000 Інтервал опитування в мілісекундах

Як це працює

  1. Під час завантаження сторінки клієнт отримує короткий хеш поточних даних
  2. Кожні interval мілісекунд він отримує хеш знову
  3. Якщо хеш змінився, клієнт отримує повний набір даних
  4. Нові дані передаються до сховища API взаємодії через store()
  5. Усі директиви, прив’язані до цієї властивості стану, автоматично відображають зміни

Опитування виконується лише на сторінках, де є відповідний елемент data-wp-interactive. Воно призупиняється, коли вкладка браузера прихована, і поновлюється, коли її знову видно.

Кінцева точка хешу (?_hash=1) повертає лише контрольну суму md5 і кількість записів, щоб запити опитування передавали мало даних.

Дані користувача

Установіть userScoped: true, щоб автоматично обмежити всі записи даними поточного користувача. Blockstudio додає стовпець user_id, заповнює його під час створення та обмежує всі операції записами поточного користувача:

PHP
return [
    'storage'    => 'sqlite',
    'userScoped' => true,
    'fields'     => [
        'text' => ['type' => 'string', 'required' => true],
        'done' => ['type' => 'boolean', 'default' => false],
    ],
];

Не потрібно вручну додавати поле user_id, використовувати хук before_create чи фільтрувати дані в RPC. Користувачі можуть переглядати, редагувати й видаляти лише власні записи. Стовпець user_id повністю контролюється Blockstudio.

Якщо використовується сховище post_type, замість окремого стовпця user_id для userScoped використовується post_author.

Контроль доступу

Для кожної операції CRUD задається окремий рівень дозволів:

Значення Поведінка
true Публічний доступ із захистом CSRF (дозволено для користувачів без входу; потрібен X-BS-Token)
'open' Повністю публічний доступ без CSRF і автентифікації (для вебхуків і зовнішніх API)
'edit_posts' Перевірка дозволу WordPress
['cap_a', 'cap_b'] Користувачеві потрібен будь-який один із перелічених дозволів
не вказано / null Потрібна автентифікація (користувач має увійти в систему)
PHP
'capability' => [
    'create' => true,                               // public + CSRF protected
    'read'   => 'open',                             // truly open, no protection
    'update' => 'edit_posts',                       // editors and above
    'delete' => ['delete_posts', 'manage_options'], // either capability works
],

Захист CSRF

Публічні кінцеві точки (true) захищено заголовком X-BS-Token. bs.db() і bs.fn() отримують свіжі облікові дані з некешованої кінцевої точки того самого джерела, замість того щоб вбудовувати токени зі строком дії у HTML сторінки. Сторінки, які обслуговуються з довготривалих зовнішніх кешів, продовжують працювати. Анонімні виклики без дійсного токена отримують відповідь 403.

Облікові дані запитуються під час першого виклику API, а не під час кожного перегляду сторінки. Обидва клієнти, зокрема клієнт періодичного опитування бази даних у реальному часі, спільно використовують один запит на оновлення облікових даних. Облікові дані оновлюються після п’яти хвилин використання. Відхилений nonce WordPress або токен CSRF Blockstudio запускає одне оновлення та повторну спробу; звичайні помилки прав доступу не спричиняють повторних спроб. Запити авторизованих користувачів і далі використовують сеанс поточного відвідувача, а також перевірки можливостей і права власності на записи, визначені схемою.

Розмістіть POST /wp-json/blockstudio/v1/client/credentials поза кешем проксі або CDN. Він надсилає Cache-Control: private, no-store і вимагає запиту з того самого джерела та нестандартного заголовка. Вбудовані клієнти обробляють це автоматично.

Використовуйте 'open', коли потрібен повністю неавтентифікований доступ без CSRF, наприклад для вхідних вебхуків від зовнішніх служб.

Типи полів

Тип Стовпець MySQL Тип PHP Опис
string varchar(maxLength) string Текст, типове значення maxLength 255
integer bigint(20) int Цілі числа
number decimal(20,6) float Десяткові числа
boolean tinyint(1) bool Так/ні
text longtext string Текстовий вміст великого обсягу

Перевірка даних

Перед збереженням усі дані під час створення та оновлення перевіряються за схемою. Перевірка виконується на сервері незалежно від того, чи надходить запит із bs.db(), клієнта REST API чи з Db::get().

Вбудовані правила

Правило Приклад Опис
required 'required' => true Під час створення поле має бути заповнене
type 'type' => 'integer' Значення має відповідати оголошеному типу
enum 'enum' => ['a', 'b'] Значення має бути одним із перелічених варіантів
maxLength 'maxLength' => 100 Рядок не може перевищувати цю довжину
minLength 'minLength' => 3 Рядок має бути не коротшим за цю довжину
format: "email" 'format' => 'email' Має бути дійсною адресою електронної пошти
format: "url" 'format' => 'url' Має бути дійсним URL

Власна перевірка даних

Додайте зворотний виклик validate до будь-якого поля, щоб виконувати на сервері додаткові перевірки. Поверніть true для успішної перевірки або рядок із повідомленням про помилку:

PHP
'email' => [
    'type'     => 'string',
    'format'   => 'email',
    'required' => true,
    'validate' => function ($value, $data) {
        if (str_ends_with($value, '@disposable.com')) {
            return 'Disposable email addresses are not allowed.';
        }
        return true;
    },
],

Зворотний виклик отримує значення поля й увесь масив даних, тож ви можете перевіряти залежності між полями.

Формат відповіді з помилками

Помилки перевірки повертають статус 400 і масиви помилок для кожного поля. Цей формат натхненний ZodfieldErrors і спрощує прив’язування помилок до полів форми:

JSON
{
  "code": "blockstudio_db_validation",
  "message": "Validation failed.",
  "data": {
    "status": 400,
    "errors": {
      "email": [
        "Must be a valid email address.",
        "Disposable email addresses are not allowed."
      ],
      "plan": ["Must be one of: free, pro."]
    }
  }
}

Для кожного поля повертається масив рядків із помилками. Для одного поля можуть не пройти кілька правил. На фронтенді:

JavaScript
const result = await db.create({ email: 'bad', plan: 'invalid' });

if (result.data?.errors) {
  // { email: ["Must be a valid email address."], plan: ["Must be one of: free, pro."] }
  Object.entries(result.data.errors).forEach(([field, messages]) => {
    showFieldError(field, messages[0]);
  });
}

Кінцеві точки REST

Усі кінцеві точки розміщені в просторі назв blockstudio/v1/db/:

Код
/db/{block-name}/{schema-name}

У назві блоку / замінюється на -. Для блоків з однією схемою назва схеми — default.

Метод Кінцева точка Опис
GET /db/{block}/{schema} Список записів
POST /db/{block}/{schema} Створення запису
GET /db/{block}/{schema}/{id} Отримання одного запису
PUT /db/{block}/{schema}/{id} Оновлення запису
DELETE /db/{block}/{schema}/{id} Видалення запису

Параметри запиту (список)

Параметр Опис
limit Максимальна кількість записів у відповіді (типово 50, максимум 100)
offset Кількість записів, які потрібно пропустити
Будь-яка назва поля Фільтр за точним збігом значення

Приклад: GET /db/my-theme-app/subscribers?plan=pro&limit=10

Відображення форми

Для полів можна визначити ключ component, що посилається на блок Blockstudio. Викличте bs_db_form() у шаблоні, щоб відобразити всі поля як форму з використанням компонентних блоків.

PHP
'fields' => [
    'email' => [
        'type'     => 'string',
        'format'   => 'email',
        'required' => true,
        'component' => [
            'name' => 'my-theme/field',
            'attributes' => ['label' => 'Email', 'type' => 'email'],
            'innerBlocks' => [
                [
                    'name' => 'my-theme/input',
                    'attributes' => ['placeholder' => 'Enter your email'],
                ],
            ],
        ],
    ],
    'plan' => [
        'type' => 'string',
        'enum' => ['free', 'pro'],
        'component' => [
            'name' => 'my-theme/field',
            'attributes' => ['label' => 'Plan'],
            'innerBlocks' => [
                [
                    'name' => 'my-theme/select',
                    'attributes' => ['options' => ['free', 'pro']],
                ],
            ],
        ],
    ],
],
PHP
<form>
  <?php bs_db_form('my-theme/app', 'subscribers'); ?>
  <button type="submit">Subscribe</button>
</form>

Кожен компонент отримує повне визначення поля як field у своїх атрибутах, тому компоненти можуть адаптувати відображення відповідно до схеми. Наприклад, $a['field']['name'] задає назву поля, $a['field']['type'] — тип, $a['field']['required'] — чи є воно обов’язковим тощо.

Структура компонента відповідає тому самому формату name, attributes, innerBlocks, що й блоки WordPress. Внутрішні блоки рендеряться першими й передаються батьківському блоку як $content.

Для використання PHP без виведення:

PHP
use Blockstudio\Db;

$db   = Db::get('my-theme/app', 'subscribers');
$html = $db->form();

Хуки

Дії виконуються до й після кожної операції запису. Усі хуки отримують один масив $params. Повний список наведено в довіднику Хуки PHP.

Вбудовані хуки

Визначайте хуки безпосередньо в db.php. Вони автоматично прив’язані до цієї схеми, тому перевіряти назву блоку чи схеми не потрібно:

PHP
return [
    'storage' => 'table',
    'fields'  => [ /* ... */ ],
    'hooks' => [
        'after_create' => function ($params) {
            // $params['record'] is the created record
            wp_mail($params['record']['email'], 'Welcome!', 'Thanks for subscribing.');
        },
        'before_delete' => function ($params) {
            // $params['id'] is the record being deleted
            error_log('Deleting subscriber ' . $params['id']);
        },
    ],
];

Глобальні хуки

Слухайте події в усіх схемах із будь-якого місця:

PHP
add_action('blockstudio/db/after_create', function ($params) {
    // $params['block'] and $params['schema'] identify the source
    if ('my-theme/app' === $params['block'] && 'subscribers' === $params['schema']) {
        // sync to external CRM
    }
});

Поєднання з RPC

db.php і rpc.php — незалежні системи. db.php створює кінцеві точки CRUD за визначенням схеми. rpc.php визначає власні серверні функції. Кожна з них працює окремо.

Використовуйте їх разом, коли потрібні стандартні операції з даними та власна бізнес-логіка:

PHP
use Blockstudio\Db;

return [
    'export' => [
        'callback'   => function (array $params): array {
            $db   = Db::get('my-theme/app', 'subscribers');
            $rows = $db->list(['plan' => 'pro']);
            // custom CSV generation, email sending, etc.
            return ['exported' => count($rows)];
        },
        'capability' => 'manage_options',
    ],
];

Переносність

За використання сховища JSONC дані зберігаються поруч із кодом. Скопіюйте папку блоку на інший сайт — і все переміститься разом: UI, логіка, контроль доступу й самі дані.

Код
my-app/
├── block.json
├── index.twig
├── style.css
├── rpc.php        ← custom endpoints
├── db.php         ← data schema
├── cron.php       ← scheduled tasks
└── db/
    └── entries.jsonc  ← the actual data

Без міграцій бази даних і кроків експорту чи імпорту. Просто скопіюйте папку.

Сховище Storh також переносне, але розташоване в uploads/blockstudio/db/, а не в папці блоку. Так робочі дані, які можна змінювати, залишаються поза деревом вихідного коду, а кожна схема все одно має сховище у вигляді звичайних файлів, яке можна резервувати, копіювати або мігрувати окремо.

Фільтр

Програмно змінюйте схеми ззовні блоку:

PHP
add_filter('blockstudio/database', function (array $schemas): array {
    // Add a field to an existing schema
    $schemas['my-theme/app:subscribers']['fields']['source'] = [
        'type'    => 'string',
        'default' => 'website',
    ];
    return $schemas;
});