İçeriğe geç

Veritabanı

Veritabanı katmanı, bloğunuz için bir db.php dosyasında veri modeli tanımlamanızı sağlar. Blockstudio, REST CRUD uç noktaları oluşturur, girdileri şemaya göre doğrular, depolamayı otomatik olarak yönetir ve hem bir JavaScript istemcisi (bs.db()) hem de bir PHP API (Db sınıfı) sunar.

Bu, tam yığın bloklar için veri omurgasıdır. RPC özel mantığı yönetirken, veritabanı katmanı sıfır şablon koduyla yapılandırılmış verileri yönetir.

Nasıl çalışır

  1. Blok dizininizde db.php oluşturursunuz
  2. Bu, alanları, türleri, doğrulama kurallarını ve erişim denetimini içeren bir şema döndürür
  3. Blockstudio depolamayı (tablo, dosya veya yazı meta verisi) oluşturur
  4. Beş REST uç noktası otomatik olarak oluşturulur (listeleme, alma, oluşturma, güncelleme, silme)
  5. bs.db() ve Db::get() istemci ve sunucu erişimi sağlar

Geçiş yok, denetleyici yok, rota kaydı yok.

REST ve PHP API’lerine düz değerler aktarın. meta ve post_type arka uçları, hem skaler değerlerde hem de iç içe nesne veya dizilerde ters eğik çizgileri ve tırnaklı dizeleri koruyarak WordPress meta verilerinin ters eğik çizgiyle kaçırılmasını kendi içinde yönetir. Veritabanı kayıtlarındaki değerleri önceden ters eğik çizgiyle kaçırmayın.

Şemaları tanımlama

Tek şema

En basit biçim: her blok için tek bir veri modeli.

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 yerel oluşturucu söz dizimi

db.php, adlandırılmış bağımsız değişkenlere ve salt okunur tanım nesnelerine dayanan küçük bir oluşturucu API da kullanabilir. Diziler varsayılan biçim olarak kalır; ancak şema büyüdükçe bu seçenek, PHP ile daha kolay keşfedilebilen yerel bir alternatif sunar.

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

Tek bir şema için Schema::make() kullanın; birden fazla şemaya sahip bloklar için adlandırılmış Schema::make(...) çağrılarından oluşan bir dizi döndürün.

Birden çok şema

Tek bir blok birden çok veri modeline sahip olabilir. Adlandırılmış bir dizi döndürün:

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

Her şemanın kendine ait uç noktaları, depolaması ve erişim denetimi olur.

Depolama modları

Her biri farklı kullanım alanlarına uygun altı depolama arka ucu.

Özel tablo (storage: "table")

Her kayıt, özel bir MySQL tablosunda bir satır olarak tutulur. Blockstudio, tabloyu WordPress’ın dbDelta() işlevini kullanarak otomatik biçimde oluşturur ve yönetir. Şemaya yeni alanlar eklenmesi, sonraki sayfa yüklemesinde yeni sütunlar ekler. Mevcut sütunlar hiçbir zaman kaldırılmaz.

En uygun olduğu alanlar: yapılandırılmış veriler, sorgular ve üretim uygulamaları.

SQLite (storage: "sqlite")

Her şema, db/ alt klasöründe kendine ait bir SQLite veritabanı dosyası alır. Blockstudio dosyayı ve tabloyu otomatik olarak oluşturur; şema değiştiğinde eksik sütunları ekler (MySQL için dbDelta gibi). Eşzamanlı okuma performansı için WAL günlük modunu kullanır.

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

En uygun olduğu alanlar: gerçek SQL sorguları gerektiren, ancak taşınabilir kalması gereken yapılandırılmış veriler. Her şeyi belleğe yüklemeden binlerce kaydı verimli biçimde işler. Verileri taşımak için klasörü kopyalayın.

JSONC dosyaları (storage: "jsonc")

Kayıtlar, db/ alt klasöründeki bir .jsonc dosyasında, her satırda bir JSON nesnesi olacak şekilde saklanır. Dosya ilk yazma işleminde otomatik olarak oluşturulur. // ile başlayan satırlar yorum olarak değerlendirilir ve korunur.

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

En uygun olduğu alanlar: küçük veri kümeleri, yapılandırma benzeri veriler, başlangıç kayıtları ve sürüm denetiminde tutulabilen örnekler. JSONC, blok klasörünüzde kasıtlı olarak tek bir dosya halinde tutulur. Verilerin kodla birlikte taşınmasını istediğinizde kullanın; çok sayıda eşzamanlı yazma bekliyorsanız kullanmayın.

Storh dosyaları (storage: "storh")

Storh her kaydı WordPress yüklemeleri altında ayrı bir dosya olarak saklar:

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

Herkese açık kayıt kimlikleri, bs.db()‘ın geri kalanında kullanılan aynı tamsayı kimlikler olarak kalır. Blockstudio bu kimlikleri Storh’ın dahili UUIDv7 dosya kimlikleriyle eşleştirir ve kayıt verilerinde tamsayı id değerini saklar; böylece JavaScript, REST ve PHP çağıranlarının UUID’leri işlemesi gerekmez.

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

Blockstudio, şemanızdan Storh dizinleri oluşturur. Tanımlanan her alan liste filtresi olarak kullanılabildiğinden, tüm tanımlı alanlar dizinlenir. Tamsayı, sayı ve tarih benzeri alanlar aralık dizinlerini; 'unique' => true veya 'index' => 'unique' ile işaretlenen alanlar ise benzersiz dizinleri kullanır.

En uygun olduğu alanlar: daha güvenli eşzamanlı yazmalar, şemadan türetilen dizinler ve canlı kayıtları blok kaynak ağacına eklemeden taşınabilir yüklemeler düzeyinde depolama gerektiren üretim dosya verileri.

JSONC’ten Storh’e geçiş

Bir .jsonc dosyasıyla başladıysanız ve aynı kayıtları Storh içinde istiyorsanız şu komutu çalıştırın:

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

Tek şemalı bloklar için:

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

Geçiş, mevcut db/{schema}.jsonc dosyasını okur, tamsayı kimlikleri koruyarak kayıtları Storh içine yazar, dizinleri yeniden oluşturur, hedef depoyu doğrular ve JSONC dosyasına dokunmaz. Geri almak için şemanın storage değerini yeniden "jsonc" olarak ayarlamanız yeterlidir.

Yazı meta verisi (storage: "meta")

Kayıtlar, WordPress yazı meta verisinde bir JSON dizisi olarak saklanır ve postId aracılığıyla belirli bir yazıya bağlanır.

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

En uygun olduğu alanlar: belirli bir yazıya veya sayfaya ait veriler.

Özel yazı türü (storage: "post_type")

Her kayıt, otomatik olarak kaydedilen özel bir yazı türündeki WordPress yazısıdır. Şemadaki her alan ayrı bir post_meta girdisi olur. Böylece kayıtlar WP_Query ile sorgulanabilir, REST API eklentileriyle uyumlu olur ve GraphQL gibi araçlarda görünür.

En uygun olduğu alanlar: WordPress ile yerel olarak bütünleşmesi gereken veriler. Her alan bağımsız olarak sorgulanabilir ve dizinlenebilir.

JavaScript istemcisi

Blockstudio, veritabanı bloklarının bulunduğu sayfalara bs.db() ekler. Beş yöntemi olan bir nesne döndürür:

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

İlk bağımsız değişken blok adıdır (/ ile); ikincisi şema adıdır. Tek şemalı bloklarda şema adını belirtmeyin (varsayılan "default" olur).

Önbellek

bs.cache, tüm bs.query ve bs.mutate çağrılarının paylaştığı bellek içi bir sorgu önbelleğidir. Bunu doğrudan da kullanabilirsiniz:

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

Önbellek girdileri bellekte saklanır ve sayfa gezintisinde temizlenir. Öncelikli olarak bs.query ve bs.mutate tarafından dahili olarak kullanılır; ancak verileri önceden doldurmak veya özel işlemlerden sonra önbelleği elle geçersiz kılmak için doğrudan erişim yararlıdır.

Sorgu

bs.query(), herhangi bir asenkron işlevi önbelleğe alma, yinelenen istekleri birleştirme ve eskime denetimiyle sarmalar. Bir istek devam ederken aynı anahtarla yapılan birden çok çağrı aynı promise değerini döndürür (yinelenen getirme işlemi yapılmaz).

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

İlk bağımsız değişken bir önbellek anahtarıdır (herhangi bir dize). İkincisi promise döndüren bir işlevdir. Üçüncüsü isteğe bağlı bir seçenekler nesnesidir:

Seçenek Tür Açıklama
staleTime number Önbelleğe alınan verinin eski sayılmasına kalan milisaniye. 0 (varsayılan) her zaman yeniden getirir.

Önbellekte bu anahtara ait veri varsa ve veri staleTime değerinden daha yeniyse, işlev çağrılmadan önbellekteki değer hemen döndürülür.

Değiştir

bs.mutate(), yazma işlemlerini iyimser güncellemeler ve başarısızlık durumunda otomatik geri alma ile yönetir. İki modu vardır: yaygın CRUD kalıpları için otomatik mod ve tam denetim için elle mod.

Otomatik mod, reaktif bir durum nesnesiyle çalışır (Alpine.js $data gibi). state, key, action ve isteğe bağlı olarak optimistic değerlerini iletin:

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

Başarılı olursa iyimser verinin yerini sunucu yanıtı alır. Başarısız olursa durum, değişiklikten önce alınan anlık görüntüye geri döner. Her başarılı değişiklikten sonra önbellek anahtarı otomatik olarak geçersiz kılınır.

Başarısızlık, fn tarafından döndürülen promise’ın reddedilmesi demektir. Doğrulama hatasında, kayıt bulunamadığında veya izin denetimi başarısız olduğunda bs.db() ve bs.fn() hata gövdesiyle sonuçlanır; bu durumların da geri almaya yol açması gerekiyorsa sonuç bir code içerdiğinde hata fırlatın:

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

Oluşturma işlemlerinde, iyimser öğeye geçici bir id atanır (__temp_1 gibi). Sunucu yanıt verdiğinde geçici öğeye, sunucunun atadığı id dahil olmak üzere gerçek veriler uygulanır.

Elle mod, before, onSuccess ve onError geri çağrılarıyla tam denetim sağlar:

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;
  },
});
Seçenek Tür Mod Açıklama
fn function Her ikisi Değişikliği gerçekleştiren asenkron işlev. Zorunludur.
state object Otomatik Reaktif durum nesnesi (e.g., Alpine $data).
key string Otomatik Diziyi tutan durum özelliğinin adı. Önbellek anahtarı olarak da kullanılır.
action string Otomatik create, update veya delete seçeneklerinden biri.
id any Otomatik update ve delete işlemleri için kayıt kimliği.
optimistic object Otomatik Sunucu yanıt vermeden önce iyimser biçimde uygulanacak veri.
before function Elle fn öncesinde çağrılır. Dönüş değeri, onSuccess/onError işlevlerine snapshot olarak iletilir.
onSuccess function Elle Başarı durumunda (result, snapshot) ile çağrılır.
onError function Elle Başarısızlık durumunda (error, snapshot) ile çağrılır.
invalidate string Elle Başarı durumunda geçersiz kılınacak önbellek anahtarı.

PHP API

Db sınıfı aynı işlemleri sunucu tarafında da sağlar. Bunu rpc.php, cron.php, şablonlarda veya herhangi bir PHP kodunda kullanın.

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

Tek şemalı bloklar için:

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

Gerçek zamanlı yoklama

Otomatik yoklamayı etkinleştirmek için şemanıza realtime ekleyin. Sunucudaki veriler değiştiğinde UI, Interactivity API deposu üzerinden otomatik olarak güncellenir. JavaScript değişikliği gerekmez.

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

true ile Blockstudio, Interactivity API durum anahtarı olarak şema adını kullanıp her 3 saniyede bir yoklama yapar (tek şemalı bloklarda default).

Özel yapılandırma

PHP
return [
    'storage'  => 'table',
    'realtime' => [
        'key'      => 'todos',
        'interval' => 5000,
    ],
    'fields' => [ /* ... */ ],
];
Seçenek Tür Varsayılan Açıklama
key string şema adı Veri dizisini tutan state özelliğinin adı
interval number 3000 Milisaniye cinsinden yoklama aralığı

Nasıl çalışır

  1. Sayfa yüklendiğinde istemci mevcut verilerin hafif bir özetini getirir
  2. Her interval milisaniyede bir özeti yeniden getirir
  3. Özet değişmişse tüm veri kümesini getirir
  4. Yeni verileri store() aracılığıyla Interactivity API deposuna aktarır
  5. Bu durum özelliğine bağlı tüm yönergeler otomatik olarak yeniden işlenir

Yoklama yalnızca eşleşen bir data-wp-interactive öğesinin bulunduğu sayfalarda çalışır. Tarayıcı sekmesi gizlendiğinde duraklar, görünür olduğunda devam eder.

Özet uç noktası (?_hash=1) yalnızca md5 sağlama toplamını ve kayıt sayısını döndürerek yoklama isteklerini hafif tutar.

Kullanıcı kapsamlı veriler

Tüm kayıtların kapsamını otomatik olarak mevcut kullanıcıyla sınırlamak için userScoped: true değerini ayarlayın. Blockstudio, bir user_id sütunu ekler, oluşturma sırasında değerini ayarlar ve tüm işlemleri yalnızca mevcut kullanıcının kayıtlarını kapsayacak şekilde filtreler:

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

Elle user_id alanı gerekmez, before_create kancası gerekmez, RPC içinde filtreleme gerekmez. Kullanıcılar yalnızca kendi kayıtlarını görebilir, düzenleyebilir ve silebilir. user_id sütunu tamamen Blockstudio tarafından yönetilir.

post_type depolaması kullanıldığında userScoped, ayrı bir user_id sütunu yerine post_author ile eşleştirilir.

Erişim denetimi

Her CRUD işleminin kendine ait bir izin düzeyi vardır:

Değer Davranış
true CSRF korumalı herkese açık (oturum açmamış kullanıcılar erişebilir, X-BS-Token gerekir)
'open' Tamamen herkese açık; CSRF veya kimlik doğrulaması yok (webhook’lar ve harici API’ler için)
'edit_posts' WordPress yeteneği denetimi
['cap_a', 'cap_b'] Kullanıcının listelenen yeteneklerden en az birine sahip olması gerekir
belirtilmez / null Kimlik doğrulaması gerekir (oturum açmış kullanıcı)
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 koruması

Genel uç noktalar (true) bir X-BS-Token başlığıyla korunur. bs.db() ve bs.fn(), süresi dolan belirteçleri sayfa HTML içine yerleştirmek yerine önbelleğe alınmayan aynı kaynaklı bir uç noktadan güncel kimlik bilgilerini alır. Uzun süreli harici önbelleklerden sunulan sayfalar çalışmaya devam eder. Geçerli belirteci olmayan anonim çağrılar 403 yanıtı alır.

Kimlik bilgileri her sayfa görüntülemesinde değil, ilk API çağrısında istenir. Veritabanının gerçek zamanlı sorgulaması da dahil olmak üzere her iki istemci, devam eden tek bir kimlik bilgisi yenileme işlemini paylaşır. Kimlik bilgileri beş dakikalık kullanımdan sonra yenilenir. Reddedilen bir WordPress nonce’u veya Blockstudio CSRF belirteci bir yenileme ve yeniden denemeyi tetikler; sıradan izin hataları yeniden denenmez. Oturum açmış isteklerde yine ziyaretçinin oturumu ve şemanın yetenek ve kayıt sahipliği kontrolleri kullanılır.

POST /wp-json/blockstudio/v1/client/credentials öğesini herhangi bir proxy veya CDN önbelleğinin dışında tutun. Cache-Control: private, no-store gönderir ve aynı kaynaklı, basit olmayan bir başlık içeren istek gerektirir. Yerleşik istemciler bunu otomatik olarak halleder.

Örneğin harici hizmetlerden gelen web kancaları için CSRF olmadan gerçekten kimlik doğrulamasız erişim gerektiğinde 'open' kullanın.

Alan türleri

Tür MySQL sütunu PHP türü Açıklama
string varchar(maxLength) string Metin, varsayılan maxLength 255
integer bigint(20) int Tam sayılar
number decimal(20,6) float Ondalık sayılar
boolean tinyint(1) bool Doğru/yanlış
text longtext string Uzun biçimli metin içeriği

Doğrulama

Tüm yazma işlemleri (oluşturma ve güncelleme), depolamaya dokunulmadan önce şemaya göre doğrulanır. İstek bs.db(), REST API veya Db::get() üzerinden gelsin, doğrulama sunucu tarafında yapılır.

Yerleşik kurallar

Kural Örnek Açıklama
required 'required' => true Alan, oluşturma sırasında mevcut olmalıdır
type 'type' => 'integer' Değer, tanımlanan türle eşleşmelidir
enum 'enum' => ['a', 'b'] Değer, listelenen seçeneklerden biri olmalıdır
maxLength 'maxLength' => 100 Dize bu uzunluğu aşamaz
minLength 'minLength' => 3 Dize en az bu uzunlukta olmalıdır
format: "email" 'format' => 'email' Geçerli bir e-posta adresi olmalıdır
format: "url" 'format' => 'url' Geçerli bir URL olmalıdır

Özel doğrulama

Yerleşik kuralların ötesinde sunucu tarafı denetimler için herhangi bir alana bir validate geri çağrısı ekleyin. Geçmek için true döndürün veya hata mesajını içeren bir dize döndürün:

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

Geri çağrı, alan değerini ve tüm veri dizisini alır; böylece alanlar arası doğrulama yapabilirsiniz.

Hata yanıtı biçimi

Doğrulama hataları, alan başına hata dizileri içeren bir 400 durumu döndürür. Bu biçim Zod’ın fieldErrors biçiminden esinlenmiştir ve hataların form alanlarıyla eşleştirilmesini kolaylaştırır:

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

Her alan, hata dizelerinden oluşan bir diziyle eşleşir. Aynı alan için birden fazla kural başarısız olabilir. Ön uçta:

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 uç noktaları

Tüm uç noktalar blockstudio/v1/db/ ad alanı altındadır:

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

Blok adında /, - ile değiştirilir. Tek şemalı bloklarda şema adı default olur.

Yöntem Uç nokta Açıklama
GET /db/{block}/{schema} Kayıtları listele
POST /db/{block}/{schema} Kayıt oluştur
GET /db/{block}/{schema}/{id} Tek bir kayıt al
PUT /db/{block}/{schema}/{id} Kaydı güncelle
DELETE /db/{block}/{schema}/{id} Kaydı sil

Sorgu parametreleri (liste)

Parametre Açıklama
limit Döndürülecek en fazla kayıt sayısı (varsayılan 50, en fazla 100)
offset Atlanacak kayıt sayısı
Herhangi bir alan adı Tam değer eşleşmesine göre filtrele

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

Form oluşturma

Alanlar, bir Blockstudio bloğuna başvuran bir component anahtarı tanımlayabilir. Tüm alanları bileşen bloklarını kullanarak form olarak oluşturmak için şablonunuzda bs_db_form() çağrısını yapın.

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>

Her bileşen, şemanın özelliklerine göre görüntülenmesini uyarlayabilmesi için alan tanımının tamamını özniteliklerinde field olarak alır. Örneğin, $a['field']['name'] alan adını, $a['field']['type'] türü, $a['field']['required'] zorunlu olup olmadığını belirtir.

Bileşen yapısı, WordPress bloklarıyla aynı name, attributes, innerBlocks biçimini izler. İç bloklar önce görüntülenir ve $content olarak üst bileşene aktarılır.

PHP çıktısını vermeden kullanım için:

PHP
use Blockstudio\Db;

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

Kancalar

Her yazma işleminden önce ve sonra eylemler tetiklenir. Tüm kancalar tek bir $params dizisi alır. Listenin tamamı için KancalarPHP başvurusuna bakın.

Satır içi kancalar

Kancaları doğrudan db.php içinde tanımlayın. Otomatik olarak bu şemayla sınırlandırılırlar; bu nedenle blok/şema adını denetlemeniz gerekmez:

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

Genel kancalar

Herhangi bir yerden tüm şemaları dinleyin:

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 ile birleştirme

db.php ve rpc.php birbirinden bağımsız sistemlerdir. db.php, şema tanımından CRUD uç noktaları oluşturur. rpc.php ise özel sunucu işlevlerini tanımlar. Her biri tek başına çalışır.

Standart veri işlemlerine ek olarak özel iş mantığına ihtiyaç duyduğunuzda bunları birlikte kullanın:

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

Taşınabilirlik

JSONC depolamada veriler kodun yanında tutulur. Blok klasörünü başka bir siteye kopyaladığınızda her şey birlikte taşınır: UI, mantık, erişim denetimi ve verilerin kendisi.

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

Veritabanı geçişleri veya dışa/içe aktarma adımları gerekmez. Klasörü kopyalamanız yeterlidir.

Storh depolama da taşınabilir, ancak blok klasörü yerine uploads/blockstudio/db/ altında bulunur. Böylece yazılabilir canlı veriler kaynak ağacınızın dışında kalırken her şemaya bağımsız olarak yedeklenebilen, kopyalanabilen veya taşınabilen düz dosya tabanlı bir depo sağlanır.

Filtre

Blok dışından şemaları programlı olarak değiştirin:

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