Przejdź do treści

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

  1. Tworzysz db.php w katalogu bloku
  2. Zwraca on schemat: pola, typy, reguły walidacji i kontrolę dostępu
  3. Blockstudio tworzy miejsce przechowywania danych (tabelę, plik lub metadane wpisu)
  4. Pięć endpointów REST jest generowanych automatycznie (lista, pobranie, utworzenie, aktualizacja, usunięcie)
  5. bs.db() i Db::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.

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'],
    ],
];

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
<?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ę:

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'],
        ],
    ],
];

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.

Kod
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.

Kod
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:

Kod
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.

PHP
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:

Powłoka
wp bs db migrate my-theme/app subscribers --to=storh

W przypadku bloków z jednym schematem:

Powłoka
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.

PHP
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:

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

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:

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

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ń).

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

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:

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

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:

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

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:

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

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:

PHP
$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.

PHP
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

PHP
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

  1. Po wczytaniu strony klient pobiera skrót bieżących danych
  2. Co interval milisekund ponownie pobiera skrót
  3. Jeśli skrót się zmienił, pobiera cały zbiór danych
  4. Nowe dane są przekazywane do sklepu API Interactivity za pomocą store()
  5. 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:

PHP
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)
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
],

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:

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;
    },
],

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:

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

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:

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

Endpointy REST

Wszystkie endpointy znajdują się w przestrzeni nazw blockstudio/v1/db/:

Kod
/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.

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>

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:

PHP
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:

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']);
        },
    ],
];

Hooki globalne

Nasłuchuj zdarzeń we wszystkich schematach z dowolnego miejsca:

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

Łą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:

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',
    ],
];

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.

Kod
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:

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