Lewati ke konten

Basis Data

Lapisan basis data memungkinkan Anda menentukan model data untuk blok dalam file db.php. Blockstudio menghasilkan endpoint CRUD REST, memvalidasi input terhadap skema, mengelola penyimpanan secara otomatis, serta menyediakan klien JavaScript (bs.db()) dan PHP API (kelas Db).

Ini adalah tulang punggung data untuk blok full-stack. Jika RPC menangani logika khusus, lapisan basis data menangani data terstruktur tanpa boilerplate.

Cara kerjanya

  1. Buat db.php di direktori blok Anda
  2. Ini mengembalikan skema: field, tipe, aturan validasi, kontrol akses
  3. Blockstudio membuat penyimpanan (tabel, file, atau post meta)
  4. Lima endpoint REST dibuat secara otomatis (daftar, ambil, buat, perbarui, hapus)
  5. bs.db() dan Db::get() menyediakan akses klien dan server

Tanpa migrasi, controller, atau pendaftaran rute.

Teruskan nilai literal ke API REST dan PHP. Backend meta dan post_type menangani pemiringan meta WordPress secara internal, dengan mempertahankan garis miring terbalik dan string bertanda kutip, baik dalam nilai skalar maupun objek atau larik bertingkat. Jangan awali nilai rekaman database dengan garis miring.

Menentukan skema

Skema tunggal

Bentuk paling sederhana: satu model data per 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'],
    ],
];

Sintaks builder native PHP

db.php juga dapat menggunakan API builder kecil yang dibuat berdasarkan argumen bernama dan objek definisi readonly. Array tetap menjadi format default, tetapi opsi native PHP ini lebih mudah ditemukan saat skema mulai membesar.

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

Gunakan Schema::make() untuk satu skema, atau kembalikan array bernama berisi pemanggilan Schema::make(...) untuk blok dengan beberapa skema.

Beberapa skema

Satu blok dapat memiliki beberapa model data. Kembalikan array bernama:

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

Setiap skema memiliki endpoint, penyimpanan, dan kontrol akses sendiri.

Mode penyimpanan

Enam backend penyimpanan, masing-masing sesuai untuk kasus penggunaan yang berbeda.

Tabel khusus (storage: "table")

Setiap rekaman adalah baris dalam tabel MySQL khusus. Blockstudio membuat dan mengelola tabel secara otomatis menggunakan fungsi dbDelta() milik WordPress. Penambahan field baru ke skema akan menambahkan kolom saat halaman dimuat berikutnya. Kolom yang sudah ada tidak pernah dihapus.

Cocok untuk: data terstruktur, kueri, aplikasi produksi.

SQLite (storage: "sqlite")

Setiap skema memiliki file basis data SQLite sendiri di subfolder db/. Blockstudio membuat file dan tabel secara otomatis, serta menambahkan kolom yang belum ada saat skema berubah (seperti dbDelta untuk MySQL). Menggunakan mode jurnal WAL untuk performa pembacaan bersamaan.

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

Cocok untuk: data terstruktur yang memerlukan kueri SQL sungguhan tetapi harus tetap portabel. Menangani ribuan rekaman secara efisien tanpa memuat semuanya ke memori. Salin folder untuk memindahkan data.

File JSONC (storage: "jsonc")

Rekaman disimpan sebagai satu objek JSON per baris dalam file .jsonc di dalam subfolder db/. File dibuat otomatis saat penulisan pertama. Baris yang diawali // dianggap sebagai komentar dan dipertahankan.

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

Cocok untuk: kumpulan data kecil, data mirip konfigurasi, rekaman awal, dan contoh yang dapat dikontrol versinya. JSONC sengaja dibuat sebagai satu file di folder blok Anda. Gunakan saat Anda ingin data ikut berpindah bersama kode, bukan saat Anda memperkirakan akan ada banyak penulisan bersamaan.

File Storh (storage: "storh")

Storh menyimpan setiap rekaman sebagai file tersendiri di bawah unggahan WordPress:

Kode
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

ID rekaman publik tetap berupa ID bilangan bulat yang sama dengan yang digunakan bagian lain dari bs.db(). Blockstudio memetakan ID tersebut ke ID file internal UUIDv7 milik Storh dan menyimpan bilangan bulat id dalam data rekaman, sehingga pemanggil JavaScript, REST, dan PHP tidak perlu menangani UUID.

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

Blockstudio membuat indeks Storh dari skema Anda. Karena setiap field yang dideklarasikan dapat digunakan sebagai filter daftar, setiap field tersebut diindeks. Field bertipe integer, number, dan mirip tanggal menggunakan indeks rentang; field yang ditandai dengan 'unique' => true atau 'index' => 'unique' menggunakan indeks unik.

Cocok untuk: data produksi berbasis file yang memerlukan penulisan bersamaan yang lebih aman, indeks turunan skema, dan penyimpanan tingkat uploads yang portabel tanpa memasukkan rekaman aktif ke pohon sumber blok.

Memigrasikan JSONC ke Storh

Jika Anda memulai dengan file .jsonc dan ingin rekaman yang sama di Storh, jalankan:

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

Untuk blok dengan satu skema:

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

Migrasi membaca db/{schema}.jsonc yang sudah ada, menulis rekaman ke Storh sambil mempertahankan ID bilangan bulat, membangun ulang indeks, memverifikasi penyimpanan target, dan membiarkan file JSONC tetap utuh. Untuk membatalkan, cukup ubah storage skema kembali ke "jsonc".

Post meta (storage: "meta")

Rekaman disimpan sebagai array JSON di post meta WordPress, yang dikaitkan dengan post tertentu melalui postId.

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

Cocok untuk: data yang terkait dengan post atau halaman tertentu.

Tipe post khusus (storage: "post_type")

Setiap rekaman adalah post WordPress dalam tipe post khusus yang didaftarkan otomatis. Setiap field dalam skema menjadi entri post_meta tersendiri. Dengan demikian, rekaman dapat dikueri dengan WP_Query, kompatibel dengan plugin REST API, dan terlihat oleh alat seperti GraphQL.

Cocok untuk: data yang harus terintegrasi secara native dengan WordPress. Setiap field dapat dikueri dan diindeks secara terpisah.

Klien JavaScript

Blockstudio menyisipkan bs.db() di halaman yang memiliki blok basis data. Ini mengembalikan objek dengan lima metode:

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

Argumen pertama adalah nama blok (dengan /), dan yang kedua adalah nama skema. Untuk blok dengan satu skema, nama skema dapat dihilangkan (default-nya "default").

Tembolok

bs.cache adalah tembolok kueri dalam memori yang digunakan bersama oleh semua pemanggilan bs.query dan bs.mutate. Anda juga dapat menggunakannya secara langsung:

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

Entri tembolok disimpan dalam memori dan dihapus saat navigasi halaman. Entri ini terutama digunakan secara internal oleh bs.query dan bs.mutate, tetapi akses langsung berguna untuk mengisi data terlebih dahulu atau membatalkan validasi secara manual setelah operasi khusus.

Kueri

bs.query() membungkus fungsi async dengan tembolok, deduplikasi, dan kontrol kedaluwarsa. Beberapa pemanggilan dengan kunci yang sama saat permintaan sedang berlangsung akan mengembalikan promise yang sama (tanpa pengambilan data duplikat).

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

Argumen pertama adalah kunci tembolok (string apa pun). Yang kedua adalah fungsi yang mengembalikan promise. Yang ketiga adalah objek opsi opsional:

Opsi Tipe Deskripsi
staleTime number Waktu dalam milidetik sebelum data dalam tembolok dianggap kedaluwarsa. 0 (default) selalu mengambil ulang data.

Jika tembolok memiliki data untuk kunci tersebut dan usianya kurang dari staleTime, nilai dalam tembolok langsung dikembalikan tanpa memanggil fungsi.

Mutasi

bs.mutate() menangani operasi tulis dengan pembaruan optimistis dan pemulihan otomatis saat gagal. Tersedia dua mode: mode otomatis untuk pola CRUD umum, dan mode manual untuk kendali penuh.

Mode otomatis bekerja dengan objek status reaktif (seperti Alpine.js $data). Teruskan state, key, action, dan secara opsional 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),
});

Saat berhasil, data optimistis diganti dengan respons server. Saat gagal, status dikembalikan ke snapshot yang diambil sebelum mutasi. Kunci tembolok otomatis dibatalkan validasinya setelah setiap mutasi berhasil.

Kegagalan berarti promise yang dikembalikan oleh fn ditolak. bs.db() dan bs.fn() selesai dengan isi respons error saat terjadi error validasi, rekaman tidak ditemukan, atau pemeriksaan izin gagal. Karena itu, lempar error ketika hasil memuat code jika kasus tersebut juga harus memicu pemulihan:

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

Untuk operasi pembuatan, id sementara (seperti __temp_1) ditetapkan ke item optimistis. Saat server merespons, item sementara diperbarui dengan data sebenarnya, termasuk id yang ditetapkan server.

Mode manual memberi Anda kendali penuh dengan callback before, onSuccess, dan 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;
  },
});
Opsi Tipe Mode Deskripsi
fn function Keduanya Fungsi async yang menjalankan mutasi. Wajib.
state object Otomatis Objek status reaktif (e.g., Alpine $data).
key string Otomatis Nama properti pada status yang menyimpan array. Juga digunakan sebagai kunci tembolok.
action string Otomatis Salah satu dari create, update, atau delete.
id any Otomatis ID rekaman untuk tindakan update dan delete.
optimistic object Otomatis Data yang diterapkan secara optimistis sebelum server merespons.
before function Manual Dipanggil sebelum fn. Nilai yang dikembalikan diteruskan ke onSuccess/onError sebagai snapshot.
onSuccess function Manual Dipanggil dengan (result, snapshot) saat berhasil.
onError function Manual Dipanggil dengan (error, snapshot) saat gagal.
invalidate string Manual Kunci tembolok yang dibatalkan validasinya saat berhasil.

PHP API

Kelas Db menyediakan operasi yang sama di sisi server. Gunakan di rpc.php, cron.php, templat, atau kode PHP apa pun.

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

Untuk blok dengan satu skema:

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

Polling real-time

Tambahkan realtime ke skema Anda untuk mengaktifkan polling otomatis. Saat data berubah di server, UI diperbarui secara otomatis melalui penyimpanan Interactivity API. Tidak perlu perubahan JavaScript.

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

Dengan true, Blockstudio melakukan polling setiap 3 detik menggunakan nama skema sebagai kunci status Interactivity API (default untuk blok dengan satu skema).

Konfigurasi khusus

PHP
return [
    'storage'  => 'table',
    'realtime' => [
        'key'      => 'todos',
        'interval' => 5000,
    ],
    'fields' => [ /* ... */ ],
];
Opsi Tipe Default Deskripsi
key string nama skema Nama properti pada state yang menyimpan array data
interval number 3000 Interval polling dalam milidetik

Cara kerjanya

  1. Saat halaman dimuat, klien mengambil hash ringan dari data saat ini
  2. Setiap interval milidetik, klien mengambil ulang hash
  3. Jika hash berubah, klien mengambil seluruh kumpulan data
  4. Data baru dikirim ke penyimpanan Interactivity API melalui store()
  5. Semua direktif yang terikat pada properti status tersebut dirender ulang secara otomatis

Polling hanya berjalan di halaman yang memiliki elemen data-wp-interactive yang cocok. Polling dijeda saat tab browser tersembunyi dan dilanjutkan saat terlihat.

Endpoint hash (?_hash=1) hanya mengembalikan checksum md5 dan jumlah rekaman, agar permintaan polling tetap ringan.

Data dengan cakupan pengguna

Atur userScoped: true agar semua rekaman otomatis dibatasi pada pengguna saat ini. Blockstudio menambahkan kolom user_id, menetapkannya saat pembuatan, dan memfilter semua operasi agar hanya mencakup rekaman milik pengguna saat ini:

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

Tidak perlu field user_id manual, hook before_create, atau pemfilteran di RPC. Pengguna hanya dapat melihat, mengedit, dan menghapus rekaman milik mereka sendiri. Kolom user_id sepenuhnya dikelola oleh Blockstudio.

Saat menggunakan penyimpanan post_type, userScoped dipetakan ke post_author, bukan ke kolom user_id terpisah.

Kontrol akses

Setiap operasi CRUD memiliki tingkat izin tersendiri:

Nilai Perilaku
true Publik dengan perlindungan CSRF (pengguna yang belum masuk diizinkan, perlu X-BS-Token)
'open' Benar-benar publik, tanpa CSRF dan autentikasi (untuk webhook dan API eksternal)
'edit_posts' Pemeriksaan kapabilitas WordPress
['cap_a', 'cap_b'] Pengguna memerlukan salah satu kapabilitas yang tercantum
dihilangkan / null Memerlukan autentikasi (pengguna sudah masuk)
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
],

Perlindungan CSRF

Endpoint publik (true) dilindungi oleh header X-BS-Token. bs.db() dan bs.fn() mengambil kredensial terbaru dari endpoint same-origin yang tidak di-cache, alih-alih menyematkan token yang kedaluwarsa di HTML halaman. Halaman yang disajikan dari cache eksternal berumur panjang tetap berfungsi. Panggilan anonim tanpa token valid menerima respons 403.

Kredensial diminta pada pemanggilan API pertama, bukan pada setiap tampilan halaman. Kedua klien, termasuk polling realtime basis data, menggunakan satu proses refresh kredensial yang sedang berjalan. Kredensial diperbarui setelah digunakan selama lima menit. Nonce WordPress atau token CSRF Blockstudio yang ditolak akan memicu satu kali refresh dan percobaan ulang; kesalahan izin biasa tidak dicoba ulang. Permintaan dari pengguna yang sudah masuk tetap menggunakan sesi pengguna yang berkunjung serta pemeriksaan kapabilitas dan kepemilikan rekaman dalam skema.

Tempatkan POST /wp-json/blockstudio/v1/client/credentials di luar cache proxy atau CDN. Ini mengirim Cache-Control: private, no-store dan memerlukan permintaan same-origin dengan header non-sederhana. Klien bawaan menangani ini secara otomatis.

Gunakan 'open' saat Anda memerlukan akses yang benar-benar tanpa autentikasi dan tanpa CSRF, misalnya untuk webhook masuk dari layanan eksternal.

Tipe field

Tipe Kolom MySQL Tipe PHP Deskripsi
string varchar(maxLength) string Teks, maxLength default 255
integer bigint(20) int Bilangan bulat
number decimal(20,6) float Bilangan desimal
boolean tinyint(1) bool Benar/salah
text longtext string Konten teks panjang

Validasi

Semua penulisan (pembuatan dan pembaruan) divalidasi terhadap skema sebelum menyentuh penyimpanan. Validasi dilakukan di sisi server, baik permintaan berasal dari bs.db(), REST API, maupun Db::get().

Aturan bawaan

Aturan Contoh Deskripsi
required 'required' => true Field harus ada saat pembuatan
type 'type' => 'integer' Nilai harus sesuai dengan tipe yang dideklarasikan
enum 'enum' => ['a', 'b'] Nilai harus merupakan salah satu opsi yang tercantum
maxLength 'maxLength' => 100 Panjang string tidak boleh melebihi nilai ini
minLength 'minLength' => 3 Panjang string harus setidaknya sebesar nilai ini
format: "email" 'format' => 'email' Harus berupa alamat email yang valid
format: "url" 'format' => 'url' Harus berupa URL yang valid

Validasi khusus

Tambahkan callback validate ke field mana pun untuk pemeriksaan sisi server di luar aturan bawaan. Kembalikan true jika valid, atau string berisi pesan error:

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

Callback menerima nilai field dan seluruh array data, sehingga Anda dapat melakukan validasi lintas field.

Format respons error

Kesalahan validasi mengembalikan status 400 dengan array kesalahan untuk setiap bidang. Format ini terinspirasi oleh ZodfieldErrors dan memudahkan pemetaan kesalahan ke bidang formulir:

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

Setiap field dipetakan ke array string error. Beberapa aturan dapat gagal pada field yang sama. Di sisi frontend:

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

Endpoint REST

Semua endpoint berada di namespace blockstudio/v1/db/:

Kode
/db/{block-name}/{schema-name}

Nama blok mengganti / dengan -. Untuk blok dengan satu skema, nama skemanya adalah default.

Metode Endpoint Deskripsi
GET /db/{block}/{schema} Daftar rekaman
POST /db/{block}/{schema} Buat rekaman
GET /db/{block}/{schema}/{id} Ambil satu rekaman
PUT /db/{block}/{schema}/{id} Perbarui rekaman
DELETE /db/{block}/{schema}/{id} Hapus rekaman

Parameter kueri (daftar)

Parameter Deskripsi
limit Jumlah maksimum rekaman yang dikembalikan (default 50, maks. 100)
offset Jumlah rekaman yang dilewati
Nama field apa pun Filter berdasarkan kecocokan nilai yang persis

Contoh: GET /db/my-theme-app/subscribers?plan=pro&limit=10

Merender formulir

Field dapat menentukan kunci component yang merujuk ke blok Blockstudio. Panggil bs_db_form() di templat Anda untuk merender semua field sebagai formulir menggunakan blok komponennya.

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>

Setiap komponen menerima definisi field lengkap sebagai field dalam atributnya, sehingga komponen dapat menyesuaikan tampilannya berdasarkan skema. Misalnya, $a['field']['name'] memberikan nama field, $a['field']['type'] tipenya, $a['field']['required'] apakah field wajib diisi, dan sebagainya.

Struktur komponen mengikuti format name, attributes, innerBlocks yang sama seperti blok WordPress. Blok bagian dalam dirender terlebih dahulu lalu diteruskan sebagai $content ke induknya.

Untuk penggunaan PHP tanpa melakukan echo:

PHP
use Blockstudio\Db;

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

Hook

Action dijalankan sebelum dan sesudah setiap operasi penulisan. Semua hook menerima satu array $params. Lihat referensi Hook PHP untuk daftar lengkap.

Hook inline

Definisikan hook langsung di db.php. Hook otomatis dibatasi pada skema tersebut, jadi Anda tidak perlu memeriksa nama blok/skema:

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

Hook global

Pantau semua skema dari mana saja:

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

Menggabungkan dengan RPC

db.php dan rpc.php adalah sistem yang berdiri sendiri. db.php membuat endpoint CRUD dari definisi skema. rpc.php mendefinisikan fungsi server khusus. Masing-masing dapat digunakan sendiri.

Gunakan keduanya bersama-sama saat Anda memerlukan operasi data standar sekaligus logika bisnis khusus:

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

Portabilitas

Dengan penyimpanan JSONC, data tersimpan bersama kode. Salin folder blok ke situs lain dan semuanya ikut terbawa: UI, logika, kontrol akses, dan datanya sendiri.

Kode
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

Tanpa migrasi basis data, tanpa langkah ekspor/impor. Cukup salin foldernya.

Penyimpanan Storh juga portabel, tetapi berada di bawah uploads/blockstudio/db/, bukan di folder blok. Dengan begitu, data aktif yang dapat ditulis tidak berada di pohon sumber, sementara setiap skema tetap memiliki penyimpanan berkas biasa yang dapat dicadangkan, disalin, atau dimigrasikan secara mandiri.

Filter

Ubah skema secara terprogram dari luar blok:

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