Перейти к содержимому

База данных

Слой базы данных позволяет определить модель данных для блока в файле db.php. Blockstudio создает REST CRUD-эндпоинты, проверяет входные данные по схеме, автоматически управляет хранением и предоставляет клиент 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' — уникальные индексы.

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

Перенос 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 автоматически обновляется через хранилище Interactivity API. Менять JavaScript не нужно.

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

При использовании true Blockstudio отправляет запрос каждые 3 секунды, используя имя схемы в качестве ключа состояния хранилища Interactivity API (default для блоков с одной схемой).

Пользовательская конфигурация

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

Как это работает

  1. При загрузке страницы клиент запрашивает короткий хэш текущих данных
  2. Каждые interval миллисекунд хэш запрашивается снова
  3. Если хэш изменился, загружается полный набор данных
  4. Новые данные передаются в хранилище Interactivity 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 без вывода через echo:

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;
});