Baza danych
Warstwa bazy danych pozwala zdefiniować model danych dla bloku w pliku db.php.
Blockstudio generuje REST endpointy CRUD, weryfikuje dane wejściowe względem schematu, automatycznie zarządza przechowywaniem danych i udostępnia zarówno klienta JavaScript (bs.db()), jak i PHP API (klasę Db).
To podstawa danych dla bloków full-stack. Podczas gdy RPC obsługuje niestandardową logikę, warstwa bazy danych zarządza ustrukturyzowanymi danymi bez zbędnego kodu.
Jak to działa
- Tworzysz
db.phpw katalogu bloku - Zwraca on schemat: pola, typy, reguły walidacji i kontrolę dostępu
- Blockstudio tworzy miejsce przechowywania danych (tabelę, plik lub metadane wpisu)
- Pięć endpointów REST jest generowanych automatycznie (lista, pobranie, utworzenie, aktualizacja, usunięcie)
bs.db()iDb::get()zapewniają dostęp po stronie klienta i serwera
Bez migracji, kontrolerów ani rejestracji tras.
Przekazuj wartości literalne do interfejsów API REST i PHP. Backendy meta i post_type obsługują wewnętrznie escapowanie ukośników w metadanych WordPress, zachowując ukośniki odwrotne i ujęte w cudzysłowy ciągi znaków zarówno w wartościach skalarnych, jak i zagnieżdżonych obiektach lub tablicach. Nie dodawaj wcześniej ukośników do wartości rekordów bazy danych.
Definiowanie schematów
Pojedynczy schemat
Najprostsza forma: jeden model danych na blok.
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'],
],
];
Składnia buildera PHP
db.php może również korzystać z niewielkiego buildera API opartego na nazwanych argumentach i obiektach definicji tylko do odczytu. Tablice pozostają domyślnym formatem, ale przy większych schematach ta opcja natywna dla PHP ułatwia odkrywanie dostępnych możliwości.
<?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'),
],
);
Użyj Schema::make() dla pojedynczego schematu lub zwróć tablicę nazwanych wywołań Schema::make(...) dla bloków z wieloma schematami.
Wiele schematów
Jeden blok może zawierać wiele modeli danych. Zwróć nazwaną tablicę:
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'],
],
],
];
Każdy schemat ma własne endpointy, miejsce przechowywania danych i kontrolę dostępu.
Tryby przechowywania danych
Sześć backendów przechowywania danych, z których każdy sprawdza się w innych zastosowaniach.
Tabela niestandardowa (storage: "table")
Każdy rekord jest wierszem w osobnej tabeli MySQL. Blockstudio automatycznie tworzy tabelę i zarządza nią za pomocą funkcji dbDelta() z WordPress. Dodanie nowych pól do schematu dodaje kolumny przy następnym wczytaniu strony. Istniejące kolumny nigdy nie są usuwane.
Najlepsze do: ustrukturyzowanych danych, zapytań i aplikacji produkcyjnych.
SQLite (storage: "sqlite")
Każdy schemat otrzymuje własny plik bazy danych SQLite w podkatalogu db/. Blockstudio automatycznie tworzy plik i tabelę oraz dodaje brakujące kolumny po zmianie schematu (podobnie jak dbDelta w MySQL). Używa trybu dziennika WAL, aby zapewnić wydajne równoczesne odczyty.
blocks/my-block/
├── db.php
└── db/
└── subscribers.sqlite ← single-file database
Najlepsze do: ustrukturyzowanych danych wymagających prawdziwych zapytań SQL, które powinny pozostać przenośne. Wydajnie obsługuje tysiące rekordów bez wczytywania wszystkiego do pamięci. Skopiuj katalog, aby przenieść dane.
Pliki JSONC (storage: "jsonc")
Rekordy są przechowywane jako pojedynczy obiekt JSON w każdym wierszu pliku .jsonc w podkatalogu db/. Plik jest tworzony automatycznie przy pierwszym zapisie. Wiersze zaczynające się od // są traktowane jako komentarze i zachowywane.
blocks/my-block/
├── db.php
└── db/
└── subscribers.jsonc ← one record per line
Najlepsze do: małych zbiorów danych, danych konfiguracyjnych, rekordów początkowych i przykładów, których wersje można kontrolować. JSONC to celowo pojedynczy plik w katalogu bloku. Używaj go, gdy dane mają być przenoszone razem z kodem, a nie gdy spodziewasz się wielu równoczesnych zapisów.
Pliki Storh (storage: "storh")
Storh przechowuje każdy rekord jako osobny plik w katalogu przesłanych plików 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
Publiczne identyfikatory rekordów pozostają tymi samymi identyfikatorami całkowitymi, których używa reszta bs.db().
Blockstudio mapuje te identyfikatory na wewnętrzne identyfikatory plików UUIDv7 w Storh i zapisuje liczbę całkowitą id w danych rekordu, dzięki czemu wywołujący JavaScript, REST i PHP nie muszą obsługiwać UUID.
return [
'storage' => 'storh',
'fields' => [
'title' => ['type' => 'string', 'required' => true],
'status' => ['type' => 'string'],
'count' => ['type' => 'integer'],
],
];
Blockstudio tworzy indeksy Storh na podstawie schematu. Ponieważ każde zadeklarowane pole może służyć jako filtr listy, każde pole jest indeksowane. Pola typu liczba całkowita, liczba i data używają indeksów zakresowych; pola oznaczone jako 'unique' => true lub 'index' => 'unique' używają indeksów unikatowych.
Najlepsze do: produkcyjnych danych opartych na plikach, wymagających bezpieczniejszych równoczesnych zapisów, indeksów wynikających ze schematu i przenośnego przechowywania na poziomie przesłanych plików, bez umieszczania bieżących rekordów w drzewie źródłowym bloku.
Migracja JSONC do Storh
Jeśli zaczynasz od pliku .jsonc i chcesz przenieść te same rekordy do Storh, uruchom:
wp bs db migrate my-theme/app subscribers --to=storh
W przypadku bloków z jednym schematem:
wp bs db migrate my-theme/app --to=storh
Migracja odczytuje istniejące db/{schema}.jsonc, zapisuje rekordy w Storh, zachowując identyfikatory całkowite, ponownie indeksuje dane, weryfikuje docelowe miejsce przechowywania i pozostawia plik JSONC bez zmian. Aby cofnąć migrację, wystarczy zmienić storage schematu z powrotem na "jsonc".
Metadane wpisu (storage: "meta")
Rekordy są przechowywane jako tablica JSON w metadanych wpisu WordPress i powiązane z konkretnym wpisem za pomocą postId.
return [
'storage' => 'meta',
'postId' => 42,
'fields' => [ /* ... */ ],
];
Najlepsze do: danych należących do konkretnego wpisu lub strony.
Niestandardowy typ wpisu (storage: "post_type")
Każdy rekord jest wpisem WordPress w automatycznie rejestrowanym niestandardowym typie wpisu. Każde pole w schemacie staje się osobnym wpisem post_meta. Dzięki temu rekordy można wyszukiwać za pomocą WP_Query, są zgodne z wtyczkami REST API i widoczne dla narzędzi takich jak GraphQL.
Najlepsze do: danych, które powinny natywnie integrować się z WordPress. Każde pole można niezależnie wyszukiwać i indeksować.
Klient JavaScript
Blockstudio wstrzykuje bs.db() na stronach z blokami bazy danych. Zwraca obiekt z pięcioma metodami:
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);
Pierwszym argumentem jest nazwa bloku (z /), a drugim nazwa schematu.
W przypadku bloków z jednym schematem pomiń nazwę schematu (domyślnie jest to "default").
Pamięć podręczna
bs.cache to współdzielona pamięć podręczna zapytań w pamięci operacyjnej dla wszystkich wywołań bs.query i bs.mutate. Możesz też użyć jej bezpośrednio:
// 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();
Wpisy pamięci podręcznej są przechowywane w pamięci operacyjnej i usuwane przy przejściu na inną stronę. Są używane głównie wewnętrznie przez bs.query i bs.mutate, ale bezpośredni dostęp przydaje się do wstępnego wczytywania danych lub ręcznego unieważniania wpisów po niestandardowych operacjach.
Zapytanie
bs.query() opakowuje dowolną funkcję asynchroniczną, zapewniając buforowanie, usuwanie duplikatów i kontrolę nieaktualności danych. Wiele wywołań z tym samym kluczem podczas trwającego żądania zwraca tę samą obietnicę (bez powielania pobrań).
// 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 }
);
Pierwszym argumentem jest klucz pamięci podręcznej (dowolny ciąg znaków). Drugim jest funkcja zwracająca obietnicę. Trzecim jest opcjonalny obiekt opcji:
| Opcja | Typ | Opis |
|---|---|---|
staleTime |
number |
Czas w milisekundach, po którym dane w pamięci podręcznej uznaje się za nieaktualne. 0 (domyślnie) zawsze pobiera dane ponownie. |
Jeśli pamięć podręczna zawiera dane dla danego klucza, a ich wiek nie przekracza staleTime, buforowana wartość jest zwracana natychmiast bez wywoływania funkcji.
Mutacja
bs.mutate() obsługuje operacje zapisu z optymistycznymi aktualizacjami i automatycznym przywracaniem poprzedniego stanu w razie błędu. Ma dwa tryby: automatyczny dla typowych wzorców CRUD oraz ręczny, dający pełną kontrolę.
Tryb automatyczny działa z reaktywnym obiektem stanu (takim jak Alpine.js $data). Przekaż state, key, action i opcjonalnie optimistic:
// 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),
});
Po powodzeniu dane optymistyczne zostają zastąpione odpowiedzią serwera. W razie błędu stan zostaje przywrócony do migawki sprzed mutacji. Klucz pamięci podręcznej jest automatycznie unieważniany po każdej udanej mutacji.
Błąd oznacza odrzucenie obietnicy zwróconej przez fn. bs.db() i bs.fn() zwracają rozstrzygnięte obietnice z treścią błędu w razie błędu walidacji, braku rekordu lub nieudanego sprawdzenia uprawnień. Jeśli te przypadki również mają powodować przywrócenie stanu, zgłoś wyjątek, gdy wynik zawiera code:
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)),
});
W przypadku operacji tworzenia optymistycznemu elementowi przypisywany jest tymczasowy id (np. __temp_1). Po odpowiedzi serwera tymczasowy element jest uzupełniany rzeczywistymi danymi, w tym przypisanym przez serwer id.
Tryb ręczny daje pełną kontrolę za pomocą funkcji zwrotnych before, onSuccess i onError:
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;
},
});
| Opcja | Typ | Tryb | Opis |
|---|---|---|---|
fn |
function |
Oba | Funkcja asynchroniczna wykonująca mutację. Wymagana. |
state |
object |
Auto | Obiekt stanu reaktywnego (e.g., Alpine $data). |
key |
string |
Auto | Nazwa właściwości obiektu stanu zawierającej tablicę. Używana także jako klucz pamięci podręcznej. |
action |
string |
Auto | Jedna z wartości: create, update lub delete. |
id |
any |
Auto | Identyfikator rekordu dla działań update i delete. |
optimistic |
object |
Auto | Dane stosowane optymistycznie przed odpowiedzią serwera. |
before |
function |
Ręczny | Wywoływane przed fn. Zwrócona wartość jest przekazywana do onSuccess/onError jako snapshot. |
onSuccess |
function |
Ręczny | Wywoływane z (result, snapshot) po powodzeniu. |
onError |
function |
Ręczny | Wywoływane z (error, snapshot) w razie błędu. |
invalidate |
string |
Ręczny | Klucz pamięci podręcznej do unieważnienia po powodzeniu. |
PHP API
Klasa Db udostępnia te same operacje po stronie serwera. Używaj jej w rpc.php, cron.php, szablonach lub dowolnym kodzie 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);
W przypadku bloków z jednym schematem:
$db = Db::get('my-theme/block');
Odpytywanie w czasie rzeczywistym
Dodaj realtime do schematu, aby włączyć automatyczne odpytywanie. Gdy dane na serwerze ulegną zmianie, UI aktualizuje się automatycznie za pośrednictwem sklepu API Interactivity. Nie trzeba zmieniać JavaScript.
return [
'storage' => 'table',
'realtime' => true,
'fields' => [ /* ... */ ],
];
Po ustawieniu true komponent Blockstudio odpytuje serwer co 3 sekundy, używając nazwy schematu jako klucza stanu w sklepie API Interactivity (default dla bloków z jednym schematem).
Konfiguracja niestandardowa
return [
'storage' => 'table',
'realtime' => [
'key' => 'todos',
'interval' => 5000,
],
'fields' => [ /* ... */ ],
];
| Opcja | Typ | Domyślnie | Opis |
|---|---|---|---|
key |
string |
nazwa schematu | Nazwa właściwości w state przechowującej tablicę danych |
interval |
number |
3000 |
Interwał odpytywania w milisekundach |
Jak to działa
- Po wczytaniu strony klient pobiera skrót bieżących danych
- Co
intervalmilisekund ponownie pobiera skrót - Jeśli skrót się zmienił, pobiera cały zbiór danych
- Nowe dane są przekazywane do sklepu API Interactivity za pomocą
store() - Wszelkie dyrektywy powiązane z tą właściwością stanu są automatycznie renderowane ponownie
Odpytywanie działa tylko na stronach zawierających pasujący element data-wp-interactive. Zatrzymuje się, gdy karta przeglądarki jest ukryta, i wznawia działanie po jej wyświetleniu.
Endpoint skrótu (?_hash=1) zwraca tylko sumę kontrolną md5 i liczbę rekordów, dzięki czemu żądania odpytywania są lekkie.
Dane przypisane do użytkownika
Ustaw userScoped: true, aby automatycznie przypisywać wszystkie rekordy do bieżącego użytkownika.
Blockstudio dodaje kolumnę user_id, ustawia jej wartość przy tworzeniu i ogranicza wszystkie operacje do rekordów bieżącego użytkownika:
return [
'storage' => 'sqlite',
'userScoped' => true,
'fields' => [
'text' => ['type' => 'string', 'required' => true],
'done' => ['type' => 'boolean', 'default' => false],
],
];
Bez ręcznego pola user_id, haka before_create ani filtrowania w RPC. Użytkownicy mogą wyświetlać, edytować i usuwać wyłącznie własne rekordy. Kolumna user_id jest zarządzana w całości przez Blockstudio.
W przypadku korzystania z magazynu post_type, userScoped mapuje się na post_author zamiast osobnej kolumny user_id.
Kontrola dostępu
Każda operacja CRUD ma własny poziom uprawnień:
| Wartość | Działanie |
|---|---|
true |
Publiczny dostęp z ochroną CSRF (dozwoleni niezalogowani użytkownicy, wymagane X-BS-Token) |
'open' |
Całkowicie publiczny dostęp, bez CSRF i uwierzytelniania (dla webhooków i zewnętrznych API) |
'edit_posts' |
Sprawdzenie uprawnień WordPress |
['cap_a', 'cap_b'] |
Użytkownik musi mieć dowolne z wymienionych uprawnień |
pominięto / null |
Wymaga uwierzytelnienia (zalogowanego użytkownika) |
'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
],
Ochrona CSRF
Publiczne punkty końcowe (true) są chronione nagłówkiem X-BS-Token. bs.db() i bs.fn() pobierają aktualne dane uwierzytelniające z niebuforowanego punktu końcowego w tym samym źródle, zamiast osadzać wygasające tokeny w kodzie strony HTML. Strony dostarczane z długo działających zewnętrznych pamięci podręcznych nadal działają. Anonimowe wywołania bez prawidłowego tokenu otrzymują odpowiedź 403.
Dane uwierzytelniające są pobierane przy pierwszym wywołaniu API, a nie przy każdym wyświetleniu strony. Oba klienty, w tym klient odpytujący bazę danych w czasie rzeczywistym, współdzielą jedno trwające odświeżanie danych uwierzytelniających. Dane uwierzytelniające są odświeżane po pięciu minutach użycia. Odrzucony nonce WordPress lub token CSRF Blockstudio powoduje jedno odświeżenie i ponowną próbę; zwykłe błędy uprawnień nie są ponawiane. Żądania zalogowanych użytkowników nadal korzystają z sesji odwiedzającego oraz kontroli uprawnień i własności rekordów określonych w schemacie.
Umieść POST /wp-json/blockstudio/v1/client/credentials poza pamięcią podręczną dowolnego serwera proxy lub CDN. Wysyła Cache-Control: private, no-store i wymaga żądania z tego samego źródła, zawierającego nagłówek niestandardowy. Wbudowane klienty obsługują to automatycznie.
Użyj 'open', gdy potrzebujesz dostępu bez uwierzytelniania i ochrony CSRF, na przykład dla przychodzących webhooków z usług zewnętrznych.
Typy pól
| Typ | Kolumna MySQL | Typ PHP | Opis |
|---|---|---|---|
string |
varchar(maxLength) |
string |
Tekst, domyślna wartość maxLength 255 |
integer |
bigint(20) |
int |
Liczby całkowite |
number |
decimal(20,6) |
float |
Liczby dziesiętne |
boolean |
tinyint(1) |
bool |
Wartości logiczne |
text |
longtext |
string |
Tekst o dowolnej długości |
Walidacja
Wszystkie zapisy (tworzenie i aktualizacja) są weryfikowane względem schematu przed zapisaniem danych. Walidacja odbywa się po stronie serwera niezależnie od tego, czy żądanie pochodzi z bs.db(), klienta REST API czy Db::get().
Wbudowane reguły
| Reguła | Przykład | Opis |
|---|---|---|
required |
'required' => true |
Pole musi być podane podczas tworzenia |
type |
'type' => 'integer' |
Wartość musi być zgodna z zadeklarowanym typem |
enum |
'enum' => ['a', 'b'] |
Wartość musi być jedną z wymienionych opcji |
maxLength |
'maxLength' => 100 |
Ciąg znaków nie może przekraczać tej długości |
minLength |
'minLength' => 3 |
Ciąg znaków musi mieć co najmniej taką długość |
format: "email" |
'format' => 'email' |
Musi to być prawidłowy adres e-mail |
format: "url" |
'format' => 'url' |
Musi to być prawidłowy URL |
Walidacja niestandardowa
Dodaj funkcję zwrotną validate do dowolnego pola, aby przeprowadzać po stronie serwera kontrole wykraczające poza wbudowane reguły. Zwróć true, aby zaliczyć walidację, albo ciąg znaków z komunikatem o błędzie:
'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;
},
],
Funkcja zwrotna otrzymuje wartość pola i całą tablicę danych, co pozwala przeprowadzać walidację między polami.
Format odpowiedzi z błędami
Błędy walidacji zwracają status 400 z tablicami błędów dla poszczególnych pól. Ten format jest wzorowany na ZodfieldErrors i ułatwia przypisywanie błędów do pól formularza:
{
"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."]
}
}
}
Każdemu polu odpowiada tablica ciągów znaków opisujących błędy. Dla jednego pola może wystąpić błąd kilku reguł. Po stronie frontendu:
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]);
});
}
Endpointy REST
Wszystkie endpointy znajdują się w przestrzeni nazw blockstudio/v1/db/:
/db/{block-name}/{schema-name}
W nazwie bloku / jest zastępowane przez -. W blokach z jednym schematem nazwą schematu jest default.
| Metoda | Endpoint | Opis |
|---|---|---|
GET |
/db/{block}/{schema} |
Lista rekordów |
POST |
/db/{block}/{schema} |
Utworzenie rekordu |
GET |
/db/{block}/{schema}/{id} |
Pobranie pojedynczego rekordu |
PUT |
/db/{block}/{schema}/{id} |
Aktualizacja rekordu |
DELETE |
/db/{block}/{schema}/{id} |
Usunięcie rekordu |
Parametry zapytania (lista)
| Parametr | Opis |
|---|---|
limit |
Maksymalna liczba zwracanych rekordów (domyślnie 50, maks. 100) |
offset |
Liczba pomijanych rekordów |
| Dowolna nazwa pola | Filtrowanie według dokładnej zgodności wartości |
Przykład: GET /db/my-theme-app/subscribers?plan=pro&limit=10
Renderowanie formularza
Pola mogą definiować klucz component odwołujący się do bloku Blockstudio. Wywołaj bs_db_form() w szablonie, aby wyrenderować wszystkie pola jako formularz z użyciem ich bloków komponentów.
'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']],
],
],
],
],
],
<form>
<?php bs_db_form('my-theme/app', 'subscribers'); ?>
<button type="submit">Subscribe</button>
</form>
Każdy komponent otrzymuje pełną definicję pola jako field w swoich atrybutach, dzięki czemu może dostosować sposób renderowania do schematu. Na przykład $a['field']['name'] zawiera nazwę pola, $a['field']['type'] jego typ, a $a['field']['required'] informuje, czy pole jest wymagane itd.
Struktura komponentu ma ten sam format name, attributes, innerBlocks co bloki WordPress. Najpierw renderowane są bloki wewnętrzne i przekazywane rodzicowi jako $content.
Przy użyciu PHP bez wyświetlania:
use Blockstudio\Db;
$db = Db::get('my-theme/app', 'subscribers');
$html = $db->form();
Hooki
Akcje są uruchamiane przed każdą operacją zapisu i po niej. Wszystkie hooki otrzymują pojedynczą
$params tablicę. Pełną listę znajdziesz w dokumentacji PHP hooków.
Hooki wbudowane
Definiuj hooki bezpośrednio w db.php. Ich zakres jest automatycznie ograniczony do danego schematu, więc nie musisz sprawdzać nazwy bloku ani schematu:
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']);
},
],
];
Hooki globalne
Nasłuchuj zdarzeń we wszystkich schematach z dowolnego miejsca:
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
}
});
Łączenie z RPC
db.php i rpc.php to niezależne systemy. db.php generuje punkty końcowe CRUD na podstawie definicji schematu. rpc.php definiuje niestandardowe funkcje serwera. Każdy z nich działa samodzielnie.
Łącz je, gdy potrzebujesz standardowych operacji na danych oraz niestandardowej logiki biznesowej:
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',
],
];
Przenośność
W przypadku przechowywania JSONC dane znajdują się obok kodu. Skopiuj folder bloku do innej witryny, a wszystko przeniesie się razem: UI, logika, kontrola dostępu i same dane.
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
Bez migracji bazy danych ani kroków eksportu i importu. Wystarczy skopiować folder.
Przechowywanie Storh również jest przenośne, ale znajduje się w uploads/blockstudio/db/, a nie w folderze bloku. Dzięki temu aktywne, zapisywalne dane pozostają poza drzewem źródłowym, a każdy schemat nadal ma magazyn w postaci zwykłych plików, który można niezależnie tworzyć w kopii zapasowej, kopiować lub migrować.
Filtr
Modyfikuj schematy programowo spoza bloku:
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;
});