İçeriğe geç

Tam Yığın Blokları

Blockstudio, bir blok klasörünün içinde eksiksiz uygulamalar oluşturmanızı sağlar. Tek bir dizin; UI, sunucu mantığını, veri modelini, zamanlanmış görevleri ve hatta verilerin kendisini içerebilir.

Bu kılavuz, bu yaklaşımı göstermek için iki gerçek uygulama oluşturur: kullanıcı başına bir yapılacaklar uygulaması ve herkese açık bir bülten aboneliği formu. Aynı dosya yapısı, farklı erişim modelleri.

Aşağıdaki örneklerde en kısa biçim olduğu için dizi söz dizimi kullanılıyor; ancak üç PHP yüzeyinin tümünde PHP tabanlı alternatifler de bulunuyor:

  • db.php, Blockstudio\\Db\\Schema ve Blockstudio\\Db\\Field kullanabilir
  • rpc.php, #[Rpc] yöntemlerine sahip bir nesne döndürebilir
  • cron.php, #[Cron] yöntemlerine sahip bir nesne döndürebilir

Yapılacaklar Uygulaması

Kullanıcı başına bir görev yöneticisi. Oturum açmış her kullanıcı yalnızca kendi yapılacaklarını görür. Otomatik kullanıcı yalıtımı için userScoped: true, taşınabilir depolama için SQLite, iyimser güncellemeler için bs.mutate() ve diğer sekmelerdeki değişikliklerin otomatik olarak görünmesi için gerçek zamanlı yoklama kullanır.

Dosya yapısı

Kod
blockstudio/
  todo/
    block.json
    index.php
    script.inline.js
    style.css
    db.php
    rpc.php
    cron.php

Blok tanımı

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "name": "my-theme/todo",
  "title": "Todo App",
  "category": "widgets",
  "icon": "editor-ul",
  "supports": {
    "interactivity": true
  },
  "blockstudio": {
    "interactivity": {
      "enqueue": true
    }
  }
}

supports.interactivity, WordPress yönergelerinin işlenmesini etkinleştirir (data-wp-each, data-wp-bind vb. için SSR). interactivity.enqueue, frontend’de @wordpress/interactivity modülünü yükler.

Veri modeli

userScoped: true otomatik olarak bir user_id sütunu ekler, oluşturma sırasında bu sütuna değer atar ve tüm sorguları geçerli kullanıcıya göre filtreler. realtime, diğer sekmelerdeki veya cihazlardaki değişikliklerin sayfa yenilenmeden görünmesi için otomatik yoklamayı etkinleştirir.

PHP
<?php
return [
    'storage'    => 'sqlite',
    'userScoped' => true,
    'realtime'   => [
        'key'      => 'todos',
        'interval' => 3000,
    ],
    'capability' => [
        'create' => true,
        'read'   => true,
        'update' => true,
        'delete' => true,
    ],
    'fields' => [
        'text' => [
            'type'      => 'string',
            'required'  => true,
            'minLength' => 1,
            'maxLength' => 500,
        ],
        'done' => [
            'type'    => 'boolean',
            'default' => false,
        ],
    ],
];

SQLite depolama, veritabanı dosyasının todo/db/default.sqlite konumunda bulunduğu anlamına gelir. Blok klasörünü başka bir siteye kopyaladığınızda veriler de onunla birlikte taşınır.

realtime yapılandırması, istemciye hafif bir karma karşılaştırması kullanarak her 3 saniyede bir değişiklikleri yoklamasını söyler. Veriler değiştiğinde state.todos güncellenir ve UI otomatik olarak yeniden oluşturulur.

Özel sunucu mantığı

userScoped geçerli kullanıcıya göre otomatik filtreleme yaptığından, yerleşik bs.db().list() yalnızca geçerli kullanıcının kayıtlarını döndürür. RPC yalnızca CRUD dışındaki işlemler için gerekir: durum değiştirme ve tümünü temizleme.

PHP
<?php
use Blockstudio\Db;

return [
    'toggle' => [
        'callback' => function (array $params) {
            $id = (int) ($params['id'] ?? 0);

            if (!$id) {
                return new \WP_Error('missing_id', 'ID is required.', ['status' => 400]);
            }

            $db   = Db::get('my-theme/todo');
            $todo = $db->get_record($id);

            if (!$todo) {
                return new \WP_Error('not_found', 'Not found.', ['status' => 404]);
            }

            return $db->update($id, ['done' => !$todo['done']]);
        },
        'public'  => true,
        'methods' => ['POST'],
    ],
    'clear_done' => [
        'callback' => function () {
            $db    = Db::get('my-theme/todo');
            $todos = $db->list();
            $count = 0;

            foreach ($todos as $todo) {
                if (!empty($todo['done'])) {
                    $db->delete((int) $todo['id']);
                    ++$count;
                }
            }

            return ['deleted' => $count];
        },
        'public'  => true,
        'methods' => ['POST'],
    ],
];

Zamanlanmış temizleme

Eski ve tamamlanmış yapılacaklar otomatik olarak temizlenir.

PHP
<?php
use Blockstudio\Db;

return [
    'cleanup_old_todos' => [
        'schedule' => 'daily',
        'callback' => function () {
            $db    = Db::get('my-theme/todo');
            $todos = $db->list();

            foreach ($todos as $todo) {
                $is_done = $todo['done'];
                $is_old  = strtotime($todo['updated_at']) < strtotime('-30 days');

                if ($is_done && $is_old) {
                    $db->delete((int) $todo['id']);
                }
            }
        },
    ],
];

Şablon

PHP, başlangıçtaki yapılacakları sunucu tarafında wp_interactivity_state() aracılığıyla yükler; bu, hem SSR yönerge işlemesi hem de istemci tarafı hidratasyonu için veri sağlar. Örnek başına UI durumu (giriş alanının değeri gibi) data-wp-context içinde tutulur.

PHP
<?php
$db         = \Blockstudio\Db::get('my-theme/todo');
$todos      = $db ? $db->list() : [];
$items_left = count(array_filter($todos, fn($t) => empty($t['done'])));

wp_interactivity_state('my-theme/todo', [
    'todos'     => array_values($todos),
    'hasTodos'  => !empty($todos),
    'hasDone'   => count($todos) !== $items_left,
    'itemsLeft' => $items_left . ($items_left === 1 ? ' item left' : ' items left'),
]);
?>
<div
    data-wp-interactive="my-theme/todo"
    data-wp-context='<?php echo esc_attr(wp_json_encode(['newText' => ''])); ?>'
    useBlockProps
    class="todo-app"
>
    <h2>Todos</h2>

    <div class="todo-input">
        <input
            type="text"
            placeholder="What needs to be done?"
            data-wp-bind--value="context.newText"
            data-wp-on--input="my-theme/todo::actions.updateNewText"
            data-wp-on--keydown="my-theme/todo::actions.handleKeyDown"
        />
        <button
            data-wp-on--click="my-theme/todo::actions.addTodo"
            data-wp-bind--disabled="!state.canAdd"
        >Add</button>
    </div>

    <ul class="todo-list">
        <template data-wp-each--todo="state.todos" data-wp-each-key="context.todo.id">
            <li>
                <label>
                    <input
                        type="checkbox"
                        data-wp-bind--checked="context.todo.done"
                        data-wp-on--change="actions.toggleTodo"
                    />
                    <span
                        data-wp-text="context.todo.text"
                        data-wp-class--done="context.todo.done"
                    ></span>
                </label>
                <button
                    class="todo-delete"
                    data-wp-on--click="actions.deleteTodo"
                >&times;</button>
            </li>
        </template>
    </ul>

    <div class="todo-footer" data-wp-bind--hidden="!state.hasTodos">
        <span data-wp-text="state.itemsLeft"></span>
        <button
            data-wp-on--click="my-theme/todo::actions.clearDone"
            data-wp-bind--hidden="!state.hasDone"
        >Clear done</button>
    </div>
</div>

Temel kalıplar:

  • Sunucudan gelen veriler için (yapılacaklar, sayılar) wp_interactivity_state() kullanın
  • Geçici UI durumu (giriş metni) için data-wp-context kullanın
  • data-wp-each--todo, her yineleme öğesine adlandırılmış bir bağlam verir (context.todo)
  • state.* genel depoya, context.* ise örnek başına verilere başvurur

İstemci mantığı

bs.mutate() tüm yazma işlemlerini iyimser güncellemeler ve otomatik geri alma ile yürütür. UI hemen güncellenir; sunucu çağrısı reddedilirse durum geri alınır. Mutate bölümünde açıklandığı gibi, doğrulama veya izin hatası reddedilmek yerine hata gövdesiyle sonuçlanır.

JavaScript
import { store, getContext } from '@wordpress/interactivity';

const { state } = store('my-theme/todo', {
    state: {
        get canAdd() {
            return getContext().newText.trim() !== '';
        },
        get hasTodos() {
            return state.todos.length > 0;
        },
        get hasDone() {
            return state.todos.some(t => t.done);
        },
        get itemsLeft() {
            const count = state.todos.filter(t => !t.done).length;
            return count + (count === 1 ? ' item left' : ' items left');
        },
    },
    actions: {
        updateNewText(event) {
            getContext().newText = event.target.value;
        },
        handleKeyDown(event) {
            if (event.key === 'Enter') {
                event.preventDefault();
                store('my-theme/todo').actions.addTodo();
            }
        },
        *addTodo() {
            const ctx = getContext();
            const text = ctx.newText.trim();
            if (!text) return;
            ctx.newText = '';

            yield bs.mutate({
                fn: () => bs.db('my-theme/todo').create({ text, done: false }),
                state, key: 'todos', action: 'create',
                optimistic: { text, done: false },
            });
        },
        *toggleTodo() {
            const todo = getContext().todo;

            yield bs.mutate({
                fn: () => bs.fn('toggle', { id: todo.id }, 'my-theme/todo'),
                state, key: 'todos', action: 'update', id: todo.id,
                optimistic: { ...todo, done: !todo.done },
            });
        },
        *deleteTodo() {
            const todo = getContext().todo;

            yield bs.mutate({
                fn: () => bs.db('my-theme/todo').delete(todo.id),
                state, key: 'todos', action: 'delete', id: todo.id,
            });
        },
        *clearDone() {
            yield bs.mutate({
                fn: () => bs.fn('clear_done', {}, 'my-theme/todo'),
                before() {
                    const snap = state.todos.slice();
                    state.todos = state.todos.filter(t => !t.done);
                    return snap;
                },
                onError(err, snap) { state.todos = snap; },
                invalidate: 'todos',
            });
        },
    },
});

Temel kalıplar:

  • Oluşturma/güncelleme/silme işlemleri için bs.mutate() otomatik mod: state, key, action ve optimistic verilerini iletin. UI hemen güncellenir, sunucu çağrısı arka planda yapılır ve hata durumunda durum geri alınır.
  • bs.mutate() işlemleri için clearDone el ile mod: before() anlık görüntü alır ve değişikliği uygular; onError() ise anlık görüntüden geri yükler.
  • Etkileşim API içindeki eşzamansız işlemler için yield kullanan üretici işlevler (*addTodo).
  • Doğrudan CRUD için bs.db(), özel sunucu işlevleri için bs.fn().

Stiller

CSS
.todo-app {
    max-width: 500px;
    margin: 0 auto;
    font-family: system-ui, sans-serif;
}

.todo-input {
    display: flex;
    gap: 0.5rem;
    margin-bottom: 1rem;
}

.todo-input input {
    flex: 1;
    padding: 0.5rem 0.75rem;
    border: 1px solid #d1d5db;
    border-radius: 0.375rem;
}

.todo-input button {
    padding: 0.5rem 1rem;
    background: #3b82f6;
    color: white;
    border: none;
    border-radius: 0.375rem;
    cursor: pointer;
}

.todo-list {
    list-style: none;
    padding: 0;
}

.todo-list li {
    display: flex;
    align-items: center;
    justify-content: space-between;
    padding: 0.75rem 0;
    border-bottom: 1px solid #f3f4f6;
}

.todo-list label {
    display: flex;
    align-items: center;
    gap: 0.5rem;
    flex: 1;
    cursor: pointer;
}

.todo-list .done {
    text-decoration: line-through;
    color: #9ca3af;
}

.todo-delete {
    background: none;
    border: none;
    color: #ef4444;
    font-size: 1.25rem;
    cursor: pointer;
    opacity: 0;
    transition: opacity 0.15s;
}

.todo-list li:hover .todo-delete {
    opacity: 1;
}

.todo-footer {
    display: flex;
    justify-content: space-between;
    align-items: center;
    padding: 0.75rem 0;
    font-size: 0.875rem;
    color: #6b7280;
}

.todo-footer button {
    background: none;
    border: none;
    color: #6b7280;
    cursor: pointer;
    text-decoration: underline;
}

CLI

Kabuk
wp bs db list my-theme/todo
wp bs db create my-theme/todo --text="Buy milk" --user_id=1
wp bs cron run my-theme/todo cleanup_old_todos
wp bs rpc call my-theme/todo toggle --id=1

Bülten Aboneliği

Herkese açık bir abonelik formu. Herkes abone olabilir, aboneleri yalnızca yöneticiler görüntüleyip yönetebilir. Ana işlem için userScoped gerekmez, kimlik doğrulama gerekmez. Üretim kullanımı için MySQL tablo depolamasını kullanır.

Dosya yapısı

Kod
blockstudio/
  newsletter/
    block.json
    index.php
    style.css
    script.inline.js
    db.php
    rpc.php
    cron.php

Blok tanımı

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "name": "my-theme/newsletter",
  "title": "Newsletter Signup",
  "category": "widgets",
  "icon": "email",
  "supports": {
    "interactivity": true
  },
  "blockstudio": {
    "interactivity": {
      "enqueue": true
    }
  }
}

Veri modeli

CSRF korumalı herkese açık oluşturma. Özel doğrulama, tek kullanımlık e-posta adreslerini engeller. Okuma ve silme işlemleri yalnızca yöneticilere açıktır.

PHP
<?php
return [
    'storage'    => 'table',
    'capability' => [
        'create' => true,
        'read'   => 'manage_options',
        'update' => 'manage_options',
        'delete' => 'manage_options',
    ],
    'fields' => [
        'email' => [
            'type'     => 'string',
            'format'   => 'email',
            'required' => true,
            'validate' => function ($value) {
                $blocked = ['mailinator.com', 'tempmail.com', 'throwaway.email'];
                $domain  = substr($value, strpos($value, '@') + 1);
                if (in_array($domain, $blocked, true)) {
                    return 'Please use a permanent email address.';
                }
                return true;
            },
        ],
        'name' => [
            'type'      => 'string',
            'maxLength' => 100,
        ],
        'status' => [
            'type'    => 'string',
            'enum'    => ['active', 'unsubscribed'],
            'default' => 'active',
        ],
    ],
    'hooks' => [
        'after_create' => function ($params) {
            $name = $params['record']['name'];
            wp_mail(
                $params['record']['email'],
                'Welcome!',
                'Thanks for subscribing' . ($name ? ", $name" : '') . '.'
            );
        },
    ],
];

Özel mantık

Herkese açık abonelikten çıkma uç noktası (giriş yapmadan e-posta bağlantıları üzerinden çalışır) ve yalnızca yöneticilere açık istatistikler:

PHP
<?php
use Blockstudio\Db;

return [
    'unsubscribe' => [
        'callback' => function (array $params): array {
            $email = sanitize_email($params['email'] ?? '');
            $db    = Db::get('my-theme/newsletter');
            $subs  = $db->list(['email' => $email]);

            if (empty($subs)) {
                return ['error' => 'Email not found.'];
            }

            $db->update((int) $subs[0]['id'], ['status' => 'unsubscribed']);

            return ['success' => true];
        },
        'public' => true,
    ],
    'stats' => [
        'callback'   => function (array $params): array {
            $db = Db::get('my-theme/newsletter');
            return [
                'total'  => count($db->list()),
                'active' => count($db->list(['status' => 'active'])),
            ];
        },
        'capability' => 'manage_options',
    ],
];

Zamanlanmış temizleme

PHP
<?php
use Blockstudio\Db;

return [
    'cleanup' => [
        'schedule' => 'weekly',
        'callback' => function () {
            $db    = Db::get('my-theme/newsletter');
            $unsub = $db->list(['status' => 'unsubscribed']);

            foreach ($unsub as $row) {
                if (strtotime($row['updated_at']) < strtotime('-90 days')) {
                    $db->delete((int) $row['id']);
                }
            }
        },
    ],
];

Şablon

PHP
<?php
wp_interactivity_state('my-theme/newsletter', [
    'submitted' => false,
]);
?>
<div
    data-wp-interactive="my-theme/newsletter"
    data-wp-context='<?php echo esc_attr(wp_json_encode([
        'email'   => '',
        'name'    => '',
        'loading' => false,
        'error'   => '',
    ])); ?>'
    useBlockProps
    class="newsletter"
>
    <div data-wp-bind--hidden="state.submitted">
        <h3>Stay in the loop</h3>
        <div class="newsletter-form">
            <input
                type="text"
                placeholder="Name (optional)"
                data-wp-bind--value="context.name"
                data-wp-on--input="actions.setName"
            />
            <input
                type="email"
                placeholder="Email address"
                data-wp-bind--value="context.email"
                data-wp-on--input="actions.setEmail"
                data-wp-on--keydown="actions.handleKeydown"
            />
            <button
                data-wp-on--click="actions.subscribe"
                data-wp-bind--disabled="context.loading"
            >
                <span data-wp-text="context.loading ? 'Subscribing...' : 'Subscribe'"></span>
            </button>
        </div>
        <p data-wp-bind--hidden="!context.error" class="newsletter-error" data-wp-text="context.error"></p>
    </div>
    <div data-wp-bind--hidden="!state.submitted">
        <p class="newsletter-success">You're in! Check your email.</p>
    </div>
</div>

İstemci mantığı

JavaScript
import { store, getContext } from '@wordpress/interactivity';

const { state } = store('my-theme/newsletter', {
    actions: {
        setName(event) {
            getContext().name = event.target.value;
        },
        setEmail(event) {
            getContext().email = event.target.value;
        },
        handleKeydown(event) {
            if (event.key === 'Enter') {
                store('my-theme/newsletter').actions.subscribe();
            }
        },
        *subscribe() {
            const ctx = getContext();
            const email = ctx.email.trim();
            if (!email) return;

            ctx.loading = true;
            ctx.error = '';

            const result = yield bs.db('my-theme/newsletter').create({
                email,
                name: ctx.name.trim(),
            });

            if (result.data?.errors) {
                ctx.error = Object.values(result.data.errors)[0][0];
                ctx.loading = false;
                return;
            }

            if (result.code) {
                ctx.error = result.message || 'Something went wrong.';
                ctx.loading = false;
                return;
            }

            state.submitted = true;
            ctx.loading = false;
        },
    },
});

Stiller

CSS
.newsletter {
    max-width: 480px;
    margin: 0 auto;
    padding: 2rem;
    text-align: center;
}

.newsletter h3 {
    margin: 0 0 1rem;
}

.newsletter-form {
    display: flex;
    flex-direction: column;
    gap: 0.5rem;
}

.newsletter-form input {
    padding: 0.625rem 0.75rem;
    border: 1px solid #d1d5db;
    border-radius: 0.375rem;
    font-size: 1rem;
}

.newsletter-form button {
    padding: 0.625rem 1rem;
    background: #3b82f6;
    color: white;
    border: none;
    border-radius: 0.375rem;
    font-size: 1rem;
    cursor: pointer;
}

.newsletter-form button:disabled {
    opacity: 0.6;
    cursor: not-allowed;
}

.newsletter-error {
    color: #ef4444;
    font-size: 0.875rem;
    margin: 0.5rem 0 0;
}

.newsletter-success {
    color: #10b981;
    font-size: 1.125rem;
}

CLI

Kabuk
wp bs db list my-theme/newsletter --format=table
wp bs rpc call my-theme/newsletter stats
wp bs rpc call my-theme/newsletter unsubscribe --email=user@example.com
wp bs cron run my-theme/newsletter cleanup

Yan yana karşılaştırma

Özellik Yapılacaklar Uygulaması Bülten
Kimlik doğrulama modeli userScoped: true Herkese açık oluşturma, yönetici okuması
Depolama SQLite (taşınabilir) MySQL tablosu (üretim)
Kullanıcı filtreleme Otomatik Gerekmez
CSRF X-BS-Token aracılığıyla X-BS-Token aracılığıyla
Özel RPC Durum değiştirme, tamamlananları temizleme Abonelikten çıkma, istatistikler
Cron Eski ve tamamlanmışları silme Abonelikten çıkanları kaldırma
Doğrulama Uzunluk kısıtlamaları E-posta biçimi + etki alanı engelleme
Gerçek zamanlı 3 saniyelik yoklama Gerekmez
İyimser UI bs.mutate() otomatik mod Doğrudan bs.db().create()
Durum wp_interactivity_state() wp_interactivity_state() + bağlam

Aynı yaklaşım, farklı erişim modelleri. Yapı taşları aynıdır: veri modeli için db.php, iş mantığı için rpc.php, arka plan görevleri için cron.php, UI için index.php + script.inline.js ve görünüm için style.css. Her blok kendi içinde eksiksiz bir uygulamadır.