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
- Blok dizininizde
db.phpoluşturursunuz - Bu, alanları, türleri, doğrulama kurallarını ve erişim denetimini içeren bir şema döndürür
- Blockstudio depolamayı (tablo, dosya veya yazı meta verisi) oluşturur
- Beş REST uç noktası otomatik olarak oluşturulur (listeleme, alma, oluşturma, güncelleme, silme)
bs.db()veDb::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.
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
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:
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.
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.
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:
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.
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:
wp bs db migrate my-theme/app subscribers --to=storh
Tek şemalı bloklar için:
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.
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:
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:
// 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).
// 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:
// 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:
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:
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.
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:
$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.
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
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
- Sayfa yüklendiğinde istemci mevcut verilerin hafif bir özetini getirir
- Her
intervalmilisaniyede bir özeti yeniden getirir - Özet değişmişse tüm veri kümesini getirir
- Yeni verileri
store()aracılığıyla Interactivity API deposuna aktarır - 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:
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ı) |
'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:
'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:
{
"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:
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:
/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.
'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>
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:
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:
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:
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:
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.
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:
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;
});