Pāriet uz saturu

Pilna steka bloki

Blockstudio ļauj veidot pilnvērtīgas lietotnes bloka mapē. Vienā direktorijā var atrasties UI, servera loģika, datu modelis, ieplānotie uzdevumi un pat paši dati.

Šajā ceļvedī ir izveidotas divas īstas lietotnes, lai parādītu šo pieeju: uzdevumu lietotne katram lietotājam un publiska pieteikšanās jaunumu saņemšanai. Failu struktūra ir viena un tā pati, bet piekļuves modeļi atšķiras.

Tālākajos piemēros izmantota masīvu sintakse, jo tā ir viskompaktākā, taču visām trim PHP vidēm ir arī PHP pamata alternatīvas:

  • db.php var izmantot Blockstudio\\Db\\Schema un Blockstudio\\Db\\Field
  • rpc.php var atgriezt objektu ar #[Rpc] metodēm
  • cron.php var atgriezt objektu ar #[Cron] metodēm

Uzdevumu lietotne

Uzdevumu pārvaldības rīks katram lietotājam. Katrs pieteicies lietotājs redz tikai savus uzdevumus. Tiek izmantots userScoped: true, lai automātiski nodalītu lietotājus, SQLite pārnēsājamai datu glabāšanai, bs.mutate() optimistiskiem atjauninājumiem un reāllaika aptauja, lai citās cilnēs veiktās izmaiņas parādītos automātiski.

Failu struktūra

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

Bloka definīcija

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 iespējo WordPress direktīvu apstrādi (SSR priekš data-wp-each, data-wp-bind u.c.). interactivity.enqueue ielādē moduli @wordpress/interactivity priekšgalā.

Datu modelis

userScoped: true automātiski pievieno kolonnu user_id, iestata tās vērtību, veidojot ierakstu, un visus vaicājumus filtrē pēc pašreizējā lietotāja. realtime iespējo automātisku aptauju, lai izmaiņas citās cilnēs vai ierīcēs būtu redzamas bez lapas atsvaidzināšanas.

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 glabāšanas režīmā datubāzes fails atrodas vietā todo/db/default.sqlite. Pārkopējiet bloka mapi uz citu vietni, un dati būs tai līdzi.

Konfigurācija realtime liek klientam ik pēc 3 sekundēm pārbaudīt izmaiņas, izmantojot vieglu jaucējvērtību salīdzināšanu. Kad dati mainās, tiek atjaunināts state.todos un UI tiek automātiski renderēts no jauna.

Pielāgota servera loģika

Tā kā userScoped automātiski filtrē pēc pašreizējā lietotāja, iebūvētais bs.db().list() jau atgriež tikai pašreizējā lietotāja ierakstus. RPC ir nepieciešams tikai darbībām ārpus CRUD: pārslēgšanai un visu ierakstu dzēšanai.

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

Ieplānota tīrīšana

Vecie izpildītie uzdevumi tiek automātiski iztīrīti.

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

Veidne

PHP ielādē sākotnējos uzdevumus servera pusē, izmantojot wp_interactivity_state(), kas nodrošina datus gan SSR direktīvu apstrādei, gan klienta puses hidratācijai. UI stāvoklis katrai instancei atsevišķi (piemēram, ievades lauka vērtība) tiek glabāts objektā data-wp-context.

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>

Galvenie modeļi:

  • wp_interactivity_state() datiem, kas iegūti no servera (uzdevumiem, skaitam)
  • data-wp-context pagaidu UI stāvoklim (ievades tekstam)
  • data-wp-each--todo katram cikla elementam piešķir nosauktu kontekstu (context.todo)
  • state.* atsaucas uz globālo krātuvi, context.* atsaucas uz katras instances datiem

Klienta loģika

bs.mutate() apstrādā visas rakstīšanas darbības ar optimistiskiem atjauninājumiem un automātisku atcelšanu. UI tiek atjaunināts uzreiz; ja servera izsaukums neizdodas, stāvoklis tiek atjaunots. Validācijas vai atļaujas kļūda atgriež kļūdas pamattekstu, nevis izraisa noraidījumu, kā aprakstīts sadaļā Mainīt.

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

Galvenie modeļi:

  • bs.mutate() automātiskais režīms izveidei, atjaunināšanai un dzēšanai: padodiet state, key, action un optimistic datus. UI tiek atjaunināts nekavējoties, servera izsaukums notiek fonā, bet kļūmes gadījumā stāvoklis tiek atjaunots.
  • bs.mutate() manuālais režīms clearDone gadījumā: before() izveido momentuzņēmumu un piemēro izmaiņas, savukārt onError() atjauno datus no momentuzņēmuma.
  • Ģeneratora funkcijas (*addTodo) ar yield asinhronām darbībām Interactivity API.
  • bs.db() tiešām CRUD darbībām, bs.fn() pielāgotām servera funkcijām.

Stili

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

Apvalks
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

Pieteikšanās jaunumu saņemšanai

Publiska abonēšanas veidlapa. Abonēt var ikviens, bet abonentus var skatīt un pārvaldīt tikai administratori. Galvenajai darbībai nav userScoped un nav nepieciešama autentifikācija. Ražošanas vidē tiek izmantota MySQL tabulu glabāšana.

Failu struktūra

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

Bloka definīcija

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

Datu modelis

Publiska izveide ar CSRF aizsardzību. Pielāgota validācija bloķē vienreizlietojamas e-pasta adreses. Lasīt un dzēst drīkst tikai administratori.

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

Pielāgota loģika

Publisks atteikšanās no abonēšanas galapunkts (darbojas e-pasta saitēs bez pieteikšanās) un statistika, kas pieejama tikai administratoriem:

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

Ieplānota tīrīšana

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

Veidne

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>

Klienta loģika

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

Stili

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

Apvalks
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

Salīdzinājums

Aspekts Uzdevumu lietotne Jaunumu vēstule
Autentifikācijas modelis userScoped: true Publiska izveide, administratori var lasīt
Glabāšana SQLite (pārnēsājama) MySQL tabula (ražošanai)
Lietotāju filtrēšana Automātiska Nav nepieciešama
CSRF Ar X-BS-Token Ar X-BS-Token
Pielāgota RPC Pārslēgšana, pabeigto dzēšana Abonēšanas atcelšana, statistika
Cron Veco pabeigto uzdevumu dzēšana Atteikušos abonentu noņemšana
Validācija Garuma ierobežojumi E-pasta formāts un domēna bloķēšana
Reāllaiks Aptauja ik pēc 3 sekundēm Nav nepieciešams
Optimistiski UI bs.mutate() automātiskais režīms Tiešs bs.db().create()
Stāvoklis wp_interactivity_state() wp_interactivity_state() + konteksts

Viena un tā pati pieeja, atšķirīgi piekļuves modeļi. Pamatelementi ir identiski: db.php datu modelim, rpc.php biznesa loģikai, cron.php fona uzdevumiem, index.php + script.inline.js UI, style.css izskatam. Katrs bloks ir pašpietiekama lietotne.