
# База даних

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

Це основа даних для повностекових блоків. Якщо [RPC](https://blockstudio.dev/uk/docs/blocks/block-api/rpc/) обробляє власну логіку, рівень бази даних
працює зі структурованими даними без шаблонного коду.

## Як це працює

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

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

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

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

### Одна схема

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

```php title="db.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 title="db.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 title="db.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 title="db.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, виконайте:

```bash
wp bs db migrate my-theme/app subscribers --to=storh
```

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

```bash
wp bs db migrate my-theme/app --to=storh
```

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

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

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

```php title="db.php"
return [
    'storage' => 'meta',
    'postId'  => 42,
    'fields'  => [ /* ... */ ],
];
```

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

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

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

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

## Клієнт JavaScript

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

```js
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`. Його також можна використовувати безпосередньо:

```js
// 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()` додає кешування, усунення дублікатів і контроль застарівання до будь-якої асинхронної функції. Кілька викликів з однаковим ключем під час виконання запиту повертають той самий проміс (без повторних запитів).

```js
// 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`:

```js
// 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`:

```js
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`:

```js
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 title="db.php"
return [
    'storage'  => 'table',
    'realtime' => true,
    'fields'   => [ /* ... */ ],
];
```

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

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

```php title="db.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 title="db.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 title="db.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 title="db.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` і масиви помилок для кожного поля. Цей формат натхненний [Zod`fieldErrors`](https://zod.dev/error-formatting) і спрощує прив’язування помилок до полів форми:

```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."]
    }
  }
}
```

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

```js
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 title="db.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 title="index.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`. Повний список наведено в довіднику [Хуки](https://blockstudio.dev/uk/docs/blocks/hooks/php/#database) PHP.

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

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

```php title="db.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 title="functions.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 title="rpc.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;
});
```
