Μετάβαση στο περιεχόμενο

Βάση δεδομένων

Το επίπεδο βάσης δεδομένων σάς επιτρέπει να ορίσετε ένα μοντέλο δεδομένων για το block σας σε ένα αρχείο db.php. Το Blockstudio δημιουργεί αυτόματα τελικά σημεία CRUD REST, επικυρώνει τα δεδομένα εισόδου σύμφωνα με το σχήμα, διαχειρίζεται αυτόματα την αποθήκευση και παρέχει τόσο έναν πελάτη JavaScript (bs.db()) όσο και ένα PHP API (κλάση Db).

Αυτό είναι η ραχοκοκαλιά δεδομένων για block πλήρους στοίβας. Εκεί όπου το RPC] χειρίζεται προσαρμοσμένη λογική, το επίπεδο βάσης δεδομένων διαχειρίζεται δομημένα δεδομένα χωρίς επαναλαμβανόμενο βασικό κώδικα.

Πώς λειτουργεί

  1. Δημιουργείτε το db.php στον κατάλογο του block σας
  2. Επιστρέφει ένα σχήμα: πεδία, τύπους, κανόνες επικύρωσης, έλεγχο πρόσβασης
  3. Το Blockstudio δημιουργεί την αποθήκευση (πίνακα, αρχείο ή μεταδεδομένα ανάρτησης)
  4. Δημιουργούνται αυτόματα πέντε τελικά σημεία REST (λίστα, λήψη, δημιουργία, ενημέρωση, διαγραφή)
  5. Τα bs.db() και Db::get() παρέχουν πρόσβαση από την πλευρά του πελάτη και του διακομιστή

Χωρίς μεταφορές, ελεγκτές ή καταχώριση διαδρομών.

Περάστε κυριολεκτικές τιμές στα API REST και PHP. Τα backends meta και post_type χειρίζονται εσωτερικά την προσθήκη καθέτων στα meta του WordPress, διατηρώντας τις ανάστροφες καθέτους και τις συμβολοσειρές σε εισαγωγικά τόσο σε βαθμωτές τιμές όσο και σε ένθετα αντικείμενα ή πίνακες. Μην προσθέτετε καθέτους εκ των προτέρων στις τιμές εγγραφών της βάσης δεδομένων.

Ορισμός σχημάτων

Μεμονωμένο σχήμα

Η απλούστερη μορφή: ένα μοντέλο δεδομένων ανά block.

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

Το db.php μπορεί επίσης να χρησιμοποιήσει μια μικρή βιβλιοθήκη δόμησης API, βασισμένη σε ορίσματα με ονόματα και αντικείμενα ορισμού μόνο για ανάγνωση. Οι πίνακες παραμένουν η προεπιλεγμένη μορφή, αλλά αυτή η επιλογή, εγγενής στο PHP, κάνει το σχήμα πιο εύκολο στην εξερεύνηση όταν αρχίζει να μεγαλώνει.

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

Χρησιμοποιήστε το Schema::make() για ένα μεμονωμένο σχήμα ή επιστρέψτε έναν επώνυμο πίνακα κλήσεων Schema::make(...) για block με πολλά σχήματα.

Πολλαπλά σχήματα

Ένα block μπορεί να περιέχει πολλά μοντέλα δεδομένων. Επιστρέψτε έναν επώνυμο πίνακα:

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

Κάθε σχήμα έχει τα δικά του τελικά σημεία, αποθήκευση και έλεγχο πρόσβασης.

Λειτουργίες αποθήκευσης

Έξι συστήματα αποθήκευσης, καθένα κατάλληλο για διαφορετικές περιπτώσεις χρήσης.

Προσαρμοσμένος πίνακας (storage: "table")

Κάθε εγγραφή είναι μια γραμμή σε έναν αποκλειστικό πίνακα MySQL. Το Blockstudio δημιουργεί και διαχειρίζεται τον πίνακα αυτόματα, χρησιμοποιώντας τη συνάρτηση dbDelta() του WordPress. Η προσθήκη νέων πεδίων στο σχήμα προσθέτει στήλες στην επόμενη φόρτωση σελίδας. Οι υπάρχουσες στήλες δεν αφαιρούνται ποτέ.

Ιδανικό για: δομημένα δεδομένα, ερωτήματα, εφαρμογές παραγωγής.

SQLite (storage: "sqlite")

Κάθε σχήμα αποκτά το δικό του αρχείο βάσης δεδομένων SQLite σε έναν υποφάκελο db/. Το Blockstudio δημιουργεί αυτόματα το αρχείο και τον πίνακα και προσθέτει στήλες που λείπουν όταν αλλάζει το σχήμα (όπως το dbDelta για το MySQL). Χρησιμοποιεί τη λειτουργία καταγραφής WAL για ταυτόχρονη ανάγνωση.

Κώδικας
blocks/my-block/
├── db.php
└── db/
    └── subscribers.sqlite   ← single-file database

Ιδανικό για: δομημένα δεδομένα που χρειάζονται πραγματικά ερωτήματα SQL, αλλά πρέπει να παραμένουν φορητά. Διαχειρίζεται αποτελεσματικά χιλιάδες εγγραφές χωρίς να φορτώνει τα πάντα στη μνήμη. Αντιγράψτε τον φάκελο για να μεταφέρετε τα δεδομένα.

Αρχεία JSONC (storage: "jsonc")

Οι εγγραφές αποθηκεύονται ως ένα αντικείμενο JSON ανά γραμμή σε ένα αρχείο .jsonc, μέσα σε έναν υποφάκελο db/. Το αρχείο δημιουργείται αυτόματα κατά την πρώτη εγγραφή. Οι γραμμές που αρχίζουν με // θεωρούνται σχόλια και διατηρούνται.

Κώδικας
blocks/my-block/
├── db.php
└── db/
    └── subscribers.jsonc    ← one record per line

Ιδανικό για: μικρά σύνολα δεδομένων, δεδομένα τύπου ρύθμισης, αρχικές εγγραφές και παραδείγματα που μπορούν να ελεγχθούν σε σύστημα ελέγχου εκδόσεων. Το JSONC είναι σκόπιμα ένα μόνο αρχείο στον φάκελο του block σας. Χρησιμοποιήστε το όταν θέλετε τα δεδομένα να μεταφέρονται μαζί με τον κώδικα, όχι όταν περιμένετε πολλές ταυτόχρονες εγγραφές.

Αρχεία Storh (storage: "storh")

Το Storh αποθηκεύει κάθε εγγραφή ως ξεχωριστό αρχείο στα WordPress uploads:

Κώδικας
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

Τα δημόσια αναγνωριστικά εγγραφών παραμένουν οι ίδιοι ακέραιοι αριθμοί που χρησιμοποιεί και το υπόλοιπο bs.db(). Το Blockstudio αντιστοιχίζει αυτά τα αναγνωριστικά στα εσωτερικά αναγνωριστικά αρχείων UUIDv7 του Storh και αποθηκεύει τον ακέραιο αριθμό id στα δεδομένα της εγγραφής, ώστε οι καλούντες των JavaScript, REST και PHP να μη χρειάζεται να χειρίζονται UUID.

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

Το Blockstudio δημιουργεί ευρετήρια Storh από το σχήμα σας. Καθώς κάθε δηλωμένο πεδίο μπορεί να χρησιμοποιηθεί ως φίλτρο λίστας, όλα τα δηλωμένα πεδία καταχωρίζονται σε ευρετήριο. Τα πεδία ακέραιου, αριθμού και ημερομηνίας χρησιμοποιούν ευρετήρια εύρους· τα πεδία που επισημαίνονται με 'unique' => true ή 'index' => 'unique' χρησιμοποιούν μοναδικά ευρετήρια.

Ιδανικό για: δεδομένα παραγωγής που βασίζονται σε αρχεία και χρειάζονται ασφαλέστερες ταυτόχρονες εγγραφές, ευρετήρια που προκύπτουν από το σχήμα και φορητή αποθήκευση στο επίπεδο των uploads, χωρίς να καταχωρίζονται ενεργές εγγραφές στο δέντρο πηγαίου κώδικα του block.

Μετεγκατάσταση από JSONC σε Storh

Αν ξεκινήσατε με ένα αρχείο .jsonc και θέλετε τις ίδιες εγγραφές στο Storh, εκτελέστε:

Κέλυφος
wp bs db migrate my-theme/app subscribers --to=storh

Για block με ένα σχήμα:

Κέλυφος
wp bs db migrate my-theme/app --to=storh

Η μετεγκατάσταση διαβάζει το υπάρχον db/{schema}.jsonc και εγγράφει τις εγγραφές στο Storh, διατηρώντας τα ακέραια αναγνωριστικά, δημιουργεί ξανά τα ευρετήρια, επαληθεύει τον προορισμό και αφήνει ανέπαφο το αρχείο JSONC. Για αναίρεση, αρκεί να αλλάξετε ξανά το storage του σχήματος σε "jsonc".

Μεταδεδομένα ανάρτησης (storage: "meta")

Οι εγγραφές αποθηκεύονται ως πίνακας JSON στα μεταδεδομένα ανάρτησης WordPress και συνδέονται με συγκεκριμένη ανάρτηση μέσω του postId.

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

Ιδανικό για: δεδομένα που ανήκουν σε συγκεκριμένη ανάρτηση ή σελίδα.

Προσαρμοσμένος τύπος ανάρτησης (storage: "post_type")

Κάθε εγγραφή είναι μια ανάρτηση WordPress σε έναν προσαρμοσμένο τύπο ανάρτησης που καταχωρίζεται αυτόματα. Κάθε πεδίο του σχήματος γίνεται ξεχωριστή καταχώριση post_meta. Έτσι, μπορείτε να αναζητήσετε εγγραφές με το WP_Query, είναι συμβατές με πρόσθετα API REST και ορατές σε εργαλεία όπως το GraphQL.

Ιδανικό για: δεδομένα που πρέπει να ενσωματώνονται εγγενώς στο WordPress. Μπορείτε να αναζητήσετε και να δημιουργήσετε ευρετήριο για κάθε πεδίο ξεχωριστά.

Πελάτης JavaScript

Το Blockstudio εισάγει το bs.db() στις σελίδες με block βάσης δεδομένων. Επιστρέφει ένα αντικείμενο με πέντε μεθόδους:

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

Το πρώτο όρισμα είναι το όνομα του block (με /) και το δεύτερο είναι το όνομα του σχήματος. Για block με ένα σχήμα, παραλείψτε το όνομα του σχήματος (προεπιλογή: "default").

Προσωρινή μνήμη

Το bs.cache είναι μια κοινόχρηστη προσωρινή μνήμη ερωτημάτων στη μνήμη, για όλες τις κλήσεις bs.query και bs.mutate. Μπορείτε επίσης να τη χρησιμοποιήσετε απευθείας:

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

Οι καταχωρίσεις της προσωρινής μνήμης αποθηκεύονται στη μνήμη και διαγράφονται κατά την πλοήγηση σε άλλη σελίδα. Χρησιμοποιούνται κυρίως εσωτερικά από τα bs.query και bs.mutate, αλλά η άμεση πρόσβαση είναι χρήσιμη για την εκ των προτέρων συμπλήρωση δεδομένων ή τη μη αυτόματη ακύρωση μετά από προσαρμοσμένες λειτουργίες.

Ερώτημα

Το bs.query() προσθέτει προσωρινή αποθήκευση, αποδιπλοποίηση και έλεγχο παρωχημένων δεδομένων σε οποιαδήποτε ασύγχρονη συνάρτηση. Πολλαπλές κλήσεις με το ίδιο κλειδί όσο ένα αίτημα βρίσκεται σε εξέλιξη επιστρέφουν την ίδια υπόσχεση (χωρίς διπλές ανακτήσεις).

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

Το πρώτο όρισμα είναι ένα κλειδί προσωρινής μνήμης (οποιαδήποτε συμβολοσειρά). Το δεύτερο είναι μια συνάρτηση που επιστρέφει μια υπόσχεση. Το τρίτο είναι ένα προαιρετικό αντικείμενο επιλογών:

Επιλογή Τύπος Περιγραφή
staleTime number Χιλιοστά του δευτερολέπτου πριν τα αποθηκευμένα δεδομένα θεωρηθούν παρωχημένα. Το 0 (προεπιλογή) κάνει πάντα νέα ανάκτηση.

Αν η προσωρινή μνήμη περιέχει δεδομένα για το κλειδί και είναι νεότερα από staleTime, η αποθηκευμένη τιμή επιστρέφεται αμέσως, χωρίς να κληθεί η συνάρτηση.

Μεταβολή

Το bs.mutate() χειρίζεται λειτουργίες εγγραφής με αισιόδοξες ενημερώσεις και αυτόματη επαναφορά σε περίπτωση αποτυχίας. Έχει δύο λειτουργίες: αυτόματη, για συνήθη μοτίβα CRUD, και χειροκίνητη, για πλήρη έλεγχο.

Αυτόματη λειτουργία λειτουργεί με ένα αντιδραστικό αντικείμενο κατάστασης (όπως τα Alpine.js $data). Περάστε τα state, key, action και, προαιρετικά, το 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),
});

Σε περίπτωση επιτυχίας, τα αισιόδοξα δεδομένα αντικαθίστανται από την απόκριση του διακομιστή. Σε περίπτωση αποτυχίας, η κατάσταση επανέρχεται σε ένα στιγμιότυπο που λήφθηκε πριν από τη μεταβολή. Το κλειδί της προσωρινής μνήμης ακυρώνεται αυτόματα μετά από κάθε επιτυχημένη μεταβολή.

Αποτυχία σημαίνει ότι η υπόσχεση που επιστρέφει το fn απορρίπτεται. Τα bs.db() και bs.fn() επιστρέφουν κανονικά το σώμα σφάλματος σε περίπτωση σφάλματος επικύρωσης, ανύπαρκτης εγγραφής ή αποτυχίας ελέγχου δικαιωμάτων. Επομένως, προκαλέστε εξαίρεση όταν το αποτέλεσμα περιλαμβάνει ένα 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)),
});

Για λειτουργίες δημιουργίας, στο αισιόδοξο στοιχείο εκχωρείται ένα προσωρινό id (όπως το __temp_1). Όταν απαντήσει ο διακομιστής, το προσωρινό στοιχείο ενημερώνεται με τα πραγματικά δεδομένα, συμπεριλαμβανομένου του id που εκχωρήθηκε από τον διακομιστή.

Η χειροκίνητη λειτουργία σάς δίνει πλήρη έλεγχο με τις συναρτήσεις επανάκλησης before, onSuccess και 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;
  },
});
Επιλογή Τύπος Λειτουργία Περιγραφή
fn function Και οι δύο Ασύγχρονη συνάρτηση που εκτελεί τη μεταβολή. Απαιτείται.
state object Αυτόματη Αντιδραστικό αντικείμενο κατάστασης (e.g., Alpine $data).
key string Αυτόματη Όνομα ιδιότητας της κατάστασης που περιέχει τον πίνακα. Χρησιμοποιείται επίσης ως κλειδί προσωρινής μνήμης.
action string Αυτόματη Ένα από τα create, update ή delete.
id any Αυτόματη Αναγνωριστικό εγγραφής για ενέργειες update και delete.
optimistic object Αυτόματη Δεδομένα που εφαρμόζονται αισιόδοξα πριν απαντήσει ο διακομιστής.
before function Χειροκίνητη Καλείται πριν από το fn. Η τιμή επιστροφής περνά στα onSuccess/onError ως snapshot.
onSuccess function Χειροκίνητη Καλείται με το (result, snapshot) σε περίπτωση επιτυχίας.
onError function Χειροκίνητη Καλείται με το (error, snapshot) σε περίπτωση αποτυχίας.
invalidate string Χειροκίνητη Κλειδί προσωρινής μνήμης που ακυρώνεται σε περίπτωση επιτυχίας.

PHP API

Η κλάση Db παρέχει τις ίδιες λειτουργίες από την πλευρά του διακομιστή. Χρησιμοποιήστε την σε rpc.php, cron.php, πρότυπα ή οποιονδήποτε κώδικα 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);

Για block με ένα σχήμα:

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

Δημοσκόπηση σε πραγματικό χρόνο

Προσθέστε το realtime στο σχήμα σας για να ενεργοποιήσετε την αυτόματη δημοσκόπηση. Όταν αλλάζουν τα δεδομένα στον διακομιστή, το UI ενημερώνεται αυτόματα μέσω της αποθήκης API του Interactivity. Δεν απαιτούνται αλλαγές στο JavaScript.

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

Με το true, το Blockstudio εκτελεί δημοσκόπηση κάθε 3 δευτερόλεπτα, χρησιμοποιώντας το όνομα του σχήματος ως κλειδί κατάστασης API του Interactivity (default για block με ένα σχήμα).

Προσαρμοσμένες ρυθμίσεις

PHP
return [
    'storage'  => 'table',
    'realtime' => [
        'key'      => 'todos',
        'interval' => 5000,
    ],
    'fields' => [ /* ... */ ],
];
Επιλογή Τύπος Προεπιλογή Περιγραφή
key string όνομα σχήματος Όνομα ιδιότητας στο state που περιέχει τον πίνακα δεδομένων
interval number 3000 Διάστημα δημοσκόπησης σε χιλιοστά του δευτερολέπτου

Πώς λειτουργεί

  1. Κατά τη φόρτωση της σελίδας, ο πελάτης λαμβάνει ένα ελαφρύ hash των τρεχόντων δεδομένων
  2. Κάθε interval χιλιοστά του δευτερολέπτου, λαμβάνει ξανά το hash
  3. Αν το hash έχει αλλάξει, λαμβάνει ολόκληρο το σύνολο δεδομένων
  4. Τα νέα δεδομένα αποστέλλονται στην αποθήκη API του Interactivity μέσω του store()
  5. Οποιεσδήποτε οδηγίες είναι συνδεδεμένες με αυτή την ιδιότητα κατάστασης αποδίδονται ξανά αυτόματα

Η δημοσκόπηση εκτελείται μόνο σε σελίδες όπου υπάρχει αντίστοιχο στοιχείο data-wp-interactive. Παύει όταν η καρτέλα του προγράμματος περιήγησης είναι κρυφή και συνεχίζεται όταν γίνει ορατή.

Το τελικό σημείο hash (?_hash=1) επιστρέφει μόνο ένα άθροισμα ελέγχου md5 και τον αριθμό εγγραφών, ώστε τα αιτήματα δημοσκόπησης να παραμένουν ελαφριά.

Δεδομένα ανά χρήστη

Ορίστε το userScoped: true για να περιορίζονται αυτόματα όλες οι εγγραφές στον τρέχοντα χρήστη. Το Blockstudio προσθέτει μια στήλη user_id, τη συμπληρώνει κατά τη δημιουργία και φιλτράρει όλες τις λειτουργίες ώστε να αφορούν μόνο τις εγγραφές του τρέχοντος χρήστη:

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

Δεν χρειάζεται μη αυτόματο πεδίο user_id, hook before_create ή φιλτράρισμα στο RPC. Οι χρήστες μπορούν να βλέπουν, να επεξεργάζονται και να διαγράφουν μόνο τις δικές τους εγγραφές. Η στήλη user_id διαχειρίζεται αποκλειστικά από το Blockstudio.

Όταν χρησιμοποιείτε την αποθήκευση post_type, το userScoped αντιστοιχίζεται στο post_author αντί για ξεχωριστή στήλη user_id.

Έλεγχος πρόσβασης

Κάθε λειτουργία CRUD έχει το δικό της επίπεδο δικαιωμάτων:

Τιμή Συμπεριφορά
true Δημόσια με προστασία CSRF (επιτρέπονται αποσυνδεδεμένοι χρήστες, απαιτείται X-BS-Token)
'open' Πλήρως δημόσια, χωρίς CSRF ή έλεγχο ταυτότητας (για webhooks και εξωτερικά API)
'edit_posts' Έλεγχος δικαιώματος WordPress
['cap_a', 'cap_b'] Ο χρήστης χρειάζεται οποιοδήποτε από τα αναφερόμενα δικαιώματα
παραλείπεται / null Απαιτείται έλεγχος ταυτότητας (συνδεδεμένος χρήστης)
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

Τα δημόσια endpoints (true) προστατεύονται με κεφαλίδα X-BS-Token. Τα bs.db() και bs.fn() ανακτούν νέα διαπιστευτήρια από ένα endpoint ίδιας προέλευσης χωρίς προσωρινή αποθήκευση, αντί να ενσωματώνουν λήγοντα διακριτικά στο HTML της σελίδας. Οι σελίδες που παρέχονται από εξωτερικές προσωρινές μνήμες μεγάλης διάρκειας εξακολουθούν να λειτουργούν. Οι ανώνυμες κλήσεις χωρίς έγκυρο διακριτικό λαμβάνουν απάντηση 403.

Τα διαπιστευτήρια ζητούνται στην πρώτη κλήση API, όχι σε κάθε προβολή σελίδας. Και οι δύο clients, συμπεριλαμβανομένης της περιοδικής ανάκτησης ενημερώσεων βάσης δεδομένων σε πραγματικό χρόνο, χρησιμοποιούν από κοινού μία ανανέωση διαπιστευτηρίων σε εξέλιξη. Τα διαπιστευτήρια ανανεώνονται μετά από πέντε λεπτά χρήσης. Ένα μη αποδεκτό nonce WordPress ή διακριτικό CSRF Blockstudio ενεργοποιεί μία ανανέωση και επανάληψη· τα συνηθισμένα σφάλματα δικαιωμάτων δεν οδηγούν σε επανάληψη. Τα αιτήματα συνδεδεμένων χρηστών εξακολουθούν να χρησιμοποιούν τη συνεδρία του επισκέπτη και τους ελέγχους δικαιωμάτων και ιδιοκτησίας εγγραφών του σχήματος.

Κρατήστε το POST /wp-json/blockstudio/v1/client/credentials έξω από κάθε proxy ή προσωρινή μνήμη CDN. Στέλνει Cache-Control: private, no-store και απαιτεί αίτημα ίδιας προέλευσης με μη απλή κεφαλίδα. Οι ενσωματωμένοι clients το χειρίζονται αυτόματα.

Χρησιμοποιήστε το 'open' όταν χρειάζεστε πραγματικά μη πιστοποιημένη πρόσβαση χωρίς CSRF, για παράδειγμα για εισερχόμενα webhooks από εξωτερικές υπηρεσίες.

Τύποι πεδίων

Τύπος Στήλη MySQL Τύπος PHP Περιγραφή
string varchar(maxLength) string Κείμενο, προεπιλεγμένο maxLength 255
integer bigint(20) int Ακέραιοι αριθμοί
number decimal(20,6) float Δεκαδικοί αριθμοί
boolean tinyint(1) bool Αληθές/ψευδές
text longtext string Περιεχόμενο κειμένου μεγάλης έκτασης

Επικύρωση

Όλες οι εγγραφές (δημιουργία και ενημέρωση) επικυρώνονται σύμφωνα με το σχήμα πριν από την αποθήκευση. Η επικύρωση γίνεται από την πλευρά του διακομιστή, ανεξάρτητα από το αν το αίτημα προέρχεται από το bs.db(), το REST API ή το Db::get().

Ενσωματωμένοι κανόνες

Κανόνας Παράδειγμα Περιγραφή
required 'required' => true Το πεδίο πρέπει να υπάρχει κατά τη δημιουργία
type 'type' => 'integer' Η τιμή πρέπει να συμφωνεί με τον δηλωμένο τύπο
enum 'enum' => ['a', 'b'] Η τιμή πρέπει να είναι μία από τις αναφερόμενες επιλογές
maxLength 'maxLength' => 100 Η συμβολοσειρά δεν μπορεί να υπερβαίνει αυτό το μήκος
minLength 'minLength' => 3 Η συμβολοσειρά πρέπει να έχει τουλάχιστον αυτό το μήκος
format: "email" 'format' => 'email' Πρέπει να είναι έγκυρη διεύθυνση email
format: "url" 'format' => 'url' Πρέπει να είναι έγκυρο URL

Προσαρμοσμένη επικύρωση

Προσθέστε μια συνάρτηση επανάκλησης validate σε οποιοδήποτε πεδίο για ελέγχους από την πλευρά του διακομιστή, πέρα από τους ενσωματωμένους κανόνες. Επιστρέψτε true για επιτυχία ή μια συμβολοσειρά με το μήνυμα σφάλματος:

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

Η συνάρτηση επανάκλησης λαμβάνει την τιμή του πεδίου και ολόκληρο τον πίνακα δεδομένων, ώστε να μπορείτε να κάνετε επικύρωση μεταξύ πεδίων.

Μορφή απόκρισης σφάλματος

Τα σφάλματα επικύρωσης επιστρέφουν κατάσταση 400 με πίνακες σφαλμάτων ανά πεδίο. Αυτή η μορφή είναι εμπνευσμένη από το Zod και το fieldErrors του και διευκολύνει την αντιστοίχιση των σφαλμάτων με τα πεδία της φόρμας:

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

Κάθε πεδίο αντιστοιχεί σε έναν πίνακα συμβολοσειρών σφάλματος. Μπορεί να αποτύχουν πολλοί κανόνες για το ίδιο πεδίο. Στο 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]);
  });
}

Τελικά σημεία REST

Όλα τα τελικά σημεία βρίσκονται στον χώρο ονομάτων blockstudio/v1/db/:

Κώδικας
/db/{block-name}/{schema-name}

Το όνομα του block έχει το / αντικατεστημένο με το -. Για block με ένα σχήμα, το όνομα του σχήματος είναι default.

Μέθοδος Τελικό σημείο Περιγραφή
GET /db/{block}/{schema} Λίστα εγγραφών
POST /db/{block}/{schema} Δημιουργία εγγραφής
GET /db/{block}/{schema}/{id} Λήψη μεμονωμένης εγγραφής
PUT /db/{block}/{schema}/{id} Ενημέρωση εγγραφής
DELETE /db/{block}/{schema}/{id} Διαγραφή εγγραφής

Παράμετροι ερωτήματος (λίστα)

Παράμετρος Περιγραφή
limit Μέγιστος αριθμός εγγραφών προς επιστροφή (προεπιλογή 50, μέγιστο 100)
offset Αριθμός εγγραφών προς παράλειψη
Οποιοδήποτε όνομα πεδίου Φιλτράρισμα με ακριβή αντιστοιχία τιμής

Παράδειγμα: GET /db/my-theme-app/subscribers?plan=pro&limit=10

Απόδοση φόρμας

Τα πεδία μπορούν να ορίζουν ένα κλειδί component που αναφέρεται σε ένα block Blockstudio. Καλέστε το bs_db_form() στο πρότυπό σας για να αποδώσετε όλα τα πεδία ως φόρμα, χρησιμοποιώντας τα block συστατικών τους.

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>

Κάθε στοιχείο λαμβάνει τον πλήρη ορισμό του πεδίου ως field στα χαρακτηριστικά του, ώστε τα στοιχεία να μπορούν να προσαρμόζουν την απόδοσή τους βάσει του σχήματος. Για παράδειγμα, το $a['field']['name'] δίνει το όνομα του πεδίου, το $a['field']['type'] τον τύπο, το $a['field']['required'] αν είναι υποχρεωτικό κ.λπ.

Η δομή των στοιχείων ακολουθεί την ίδια μορφή name, attributes, innerBlocks με τα μπλοκ WordPress. Τα εσωτερικά μπλοκ αποδίδονται πρώτα και περνούν ως $content στο γονικό μπλοκ.

Για χρήση του PHP χωρίς echo:

PHP
use Blockstudio\Db;

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

Άγκιστρα

Οι ενέργειες εκτελούνται πριν και μετά από κάθε λειτουργία εγγραφής. Όλα τα hooks λαμβάνουν έναν πίνακα $params. Για την πλήρη λίστα, δείτε την αναφορά PHP Hooks.

Ενσωματωμένα άγκιστρα

Ορίστε άγκιστρα απευθείας στο db.php. Περιορίζονται αυτόματα σε αυτό το σχήμα, επομένως δεν χρειάζεται να ελέγχετε το όνομα του μπλοκ/σχήματος:

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

Καθολικά άγκιστρα

Παρακολουθήστε όλα τα σχήματα από οπουδήποτε:

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

Τα db.php και rpc.php είναι ανεξάρτητα συστήματα. Το db.php δημιουργεί τελικά σημεία CRUD από έναν ορισμό σχήματος. Το rpc.php ορίζει προσαρμοσμένες λειτουργίες διακομιστή. Κάθε σύστημα λειτουργεί αυτόνομα.

Χρησιμοποιήστε τα μαζί όταν χρειάζεστε τυπικές λειτουργίες δεδομένων μαζί με προσαρμοσμένη επιχειρησιακή λογική:

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

Φορητότητα

Με αποθήκευση JSONC, τα δεδομένα βρίσκονται μαζί με τον κώδικα. Αντιγράψτε τον φάκελο του μπλοκ σε έναν άλλο ιστότοπο και όλα μεταφέρονται μαζί: το UI, η λογική, ο έλεγχος πρόσβασης και τα ίδια τα δεδομένα.

Κώδικας
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

Χωρίς μετεγκαταστάσεις βάσης δεδομένων και βήματα εξαγωγής/εισαγωγής. Απλώς αντιγράψτε τον φάκελο.

Η αποθήκευση Storh είναι επίσης φορητή, αλλά βρίσκεται στο uploads/blockstudio/db/ αντί για τον φάκελο του μπλοκ. Έτσι, τα ενεργά δεδομένα στα οποία επιτρέπεται η εγγραφή μένουν έξω από το δέντρο πηγαίου κώδικα, ενώ κάθε σχήμα εξακολουθεί να έχει αποθήκη απλών αρχείων που μπορεί να δημιουργηθεί αντίγραφο ασφαλείας, να αντιγραφεί ή να μετεγκατασταθεί ανεξάρτητα.

Φίλτρο

Τροποποιήστε σχήματα προγραμματιστικά από έξω από το μπλοκ:

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