
Blockstudio 7.1 е първото функционално издание след преработката на v7. Докато v7 изгради основата, 7.1 добавя елементите, които превръщат блоковете в нещо повече: слой за база данни, сървърни функции, планирани задачи и CLI. Вече една папка с блок може да бъде цялостно приложение.

Ето всичко ново.

## Компоненти

Винаги е имало напрежение между блоковете, които редакторите използват в инструмента за вмъкване, и блоковете, които разработчиците използват като градивни елементи за други неща. Карта, значка, джаджа със статистика, поле за въвеждане във формуляр. Те се нуждаят от пълния процес на Blockstudio (атрибути, шаблони, активи, Tailwind), но нямат място в инструмента за вмъкване.

Във версия 7.1 са въведени компонентите, които решават този проблем. Задайте `"component": true` във вашия block.json и блокът ще премине през целия процес на компилация, но няма да бъде регистриран в регистъра на типовете блокове на WordPress. Няма да се показва в инструмента за вмъкване или в данните от редактора, изпращани към JavaScript, но ще е напълно достъпен за програмно рендиране.

```json title="block.json"
{
  "name": "my-theme/card",
  "title": "Card",
  "blockstudio": {
    "component": true,
    "attributes": [
      { "id": "title", "type": "text" },
      { "id": "description", "type": "textarea" }
    ]
  }
}
```

Рендирайте ги от PHP:

```php
bs_render_block([
  'name' => 'my-theme/card',
  'data' => ['title' => 'My Card', 'description' => 'Card content.'],
]);
```

Или използвайте новия синтаксис с етикети HTML:

```html
<bs:my-theme-card title="My Card" description="Card content." />
```

## Етикети за блокове

Вече можете да вграждате блокове като етикети HTML, като използвате два взаимозаменяеми синтаксиса:

```html
<bs:acme-hero title="Welcome" />
<block name="acme/hero" title="Welcome" />
```

Резултатът и от двата е еднакъв. И двата работят с блокове Blockstudio и основните блокове на WordPress. В шаблоните за блокове те се рендират автоматично, без да е необходимо изрично включване. Така можете да съставяте цели оформления от други блокове директно в шаблона си:

```twig title="index.twig"
<div class="my-page">
  <bs:mytheme-card title="Featured" />
  <block name="core/separator" />
  <bs:core-heading level="2">Section Title</bs:core-heading>
  <block name="core/group">
    <block name="core/paragraph">Inside a core group block.</block>
    <bs:mytheme-cta variant="primary" />
  </block>
</div>
```

Двата синтаксиса могат свободно да се влагат един в друг. Блоковете Blockstudio се рендират през целия процес (шаблони, Tailwind, активи). Основните блокове се рендират чрез WordPress, като използват същите рендерери, които захранват [Страници и шаблони](https://blockstudio.dev/bg/docs/pages-and-patterns/).

За рендиране на ниво страница (съдържание на публикации, области с джаджи) го включете в `blockstudio.json`:

```json
{ "blockTags": { "enabled": true } }
```

Списъците с разрешени и забранени блокове определят кои блокове могат да се рендират чрез етикети, като използват шаблони със заместващи символи. Атрибутите `data-*` и `html-*` се предават на кореновия елемент HTML на рендирания блок. Потребителски рендерери могат да се регистрират чрез филтъра `blockstudio/block_tags/renderers`.

В основата си парсерът на етикети е нов лек скенер на низове, който напълно заменя DOMDocument. Той обработва вложени етикети с проследяване на дълбочината, рекурсивни контейнерни блокове и смесен синтаксис с едно преминаване. В сравнителни тестове парсира 1,000 плоски етикета за 2.4ms и 100 нива на влагане за 3.7ms — постоянно по-бързо от DOMDocument и `WP_HTML_Tag_Processor` на WordPress. Същият парсер обработва и парсирането на сурови елементи HTML за [Страници и шаблони](https://blockstudio.dev/bg/docs/pages-and-patterns/), като заменя базирания на DOMDocument парсер, който преди обработваше `<p>`, `<div>` и други елементи HTML.

## Нови типове полета

### Блок

Нов тип поле `block`, който ви позволява да посочите друг блок Blockstudio като атрибут. Полетата на посочения блок се разгъват в съответното място чрез `idStructure` и `overrides`, точно както потребителските полета. Разликата е, че в шаблона достъпът до стойността връща рендирания изход на блока.

```json title="block.json"
{
  "blockstudio": {
    "attributes": [
      {
        "id": "card",
        "type": "block",
        "block": "mytheme/card",
        "idStructure": "card_{id}"
      }
    ]
  }
}
```

Ако `mytheme/card` има полета `heading` и `content`, хостващият блок получава `card_heading` и `card_content` в страничната си лента. В шаблона `{{ a.card }}` извежда рендираната карта. Работи както с обикновени блокове, така и с компоненти.

### Етикет HTML

Всяка тема има блокове, чието ниво на заглавие трябва да се променя според контекста. H1 на началната страница, H2 на вътрешните страници. Вместо всеки път да създавате поле за избор с твърдо зададени опции, вече има специален тип поле `html-tag` с вградени предварително зададени стойности.

```json
{
  "id": "tag",
  "type": "html-tag",
  "default": "h2",
  "tags": "heading",
  "exclude": ["h5", "h6"]
}
```

Предварителни настройки: `heading` (h1-h6), `text` (заглавия + p, span, div), `structural` (div, section, article, aside, main, header, footer, nav), `all`. Или подайте собствен масив. `exclude` премахва конкретни етикети от всяка предварителна настройка.

```twig
<{{ a.tag }}>{{ a.title }}</{{ a.tag }}>
```

## База данни

Това е централната част на изданието. Добавете файл `db.php` към всяка папка с блок и Blockstudio генерира пет крайни точки REST за CRUD операции, валидира всяка операция за запис спрямо схемата, управлява автоматично хранилището и предоставя клиент JavaScript (`bs.db()`), както и PHP API (`Db::get()`). Не са нужни файлове за миграции, класове на контролери или регистрация на маршрути.

```php title="db.php"
return [
    'subscribers' => [
        'storage'    => 'table',
        'capability' => [
            'create' => true,
            'read'   => true,
            'update' => 'edit_posts',
            'delete' => 'manage_options',
        ],
        'fields' => [
            'email' => [
                'type'     => 'string',
                'format'   => 'email',
                'required' => true,
                'validate' => function ($value) {
                    if (str_ends_with($value, '@spam.com')) {
                        return 'This domain is blocked.';
                    }
                    return true;
                },
            ],
            'name' => ['type' => 'string', 'maxLength' => 100],
            'plan' => ['type' => 'string', 'enum' => ['free', 'pro']],
        ],
    ],
];
```

Само тази схема създава напълно работеща API с крайни точки за създаване, изброяване, получаване, актуализиране и изтриване, всички с проверка на входните данни.

### Хранилище

Пет хранилища, всяко подходящо за различни случаи на употреба:

- **`table`**: Персонализирана таблица MySQL, управлявана чрез `dbDelta()`. Добавянето на полета към схемата добавя колони при следващото зареждане на страницата. Стойността по подразбиране за продукционна среда.
- **`sqlite`**: Един файл SQLite в папката `db/` на блока. Истински SQL заявки, WAL режим за едновременни четения и напълно преносим. Копирайте папката, копирайте базата данни.
- **`jsonc`**: Един обект JSON на ред в обикновен файл. Четим от хора, с контрол на версиите и удобен за git.
- **`meta`**: Масив JSON в метаданните на публикация WordPress, свързан с конкретна публикация.
- **`post_type`**: Всеки запис става публикация WordPress в персонализиран тип публикация. Полетата се съхраняват като отделни записи в метаданните на публикацията и могат да се използват в заявки чрез `WP_Query`.

### Клиенти

От страната на JavaScript, `bs.db()` ви предоставя пълен клиент за CRUD операции:

```js
const db = bs.db('my-theme/block', 'subscribers');
const record = await db.create({ email: 'a@b.com', plan: 'pro' });
const pros = await db.list({ plan: 'pro' });
await db.update(record.id, { plan: 'free' });
await db.delete(record.id);
```

Заедно с него се предлагат три помощни инструмента:

- **`bs.cache`**: Кеш на заявките в паметта с `get`, `set`, `invalidate` и `clear`. Общ за всички заявки и операции за промяна.
- **`bs.query(key, fn, options)`**: Обвива всяка асинхронна функция с кеширане, обединяване на дублирани заявки и конфигурируеми `staleTime`. Няколко извиквания с един и същ ключ, докато заявката е в ход, връщат един и същ promise.
- **`bs.mutate(options)`**: Обработва оптимистични промени с автоматично връщане назад. Подайте реактивен обект за състоянието, действие (`create`, `update`, `delete`) и оптимистични данни. UI се актуализира незабавно. Ако извикването към сървъра се провали, състоянието се връща към моментната снимка преди промяната.

Заедно те покриват целия цикъл на четене и запис: `bs.query` за кеширани прочитания, `bs.mutate` за оптимистични записи, `bs.cache` за ръчно управление.

От страната на PHP класът `Db` предоставя същите операции:

```php
use Blockstudio\Db;

$db = Db::get('my-theme/block', 'subscribers');
$db->create(['email' => 'a@b.com', 'plan' => 'pro']);
$db->list(['plan' => 'pro']);
```

### Валидиране

Грешките при валидиране се връщат като масиви с грешки за всяко поле, по образец на формата `fieldErrors` на Zod. За едно и също поле могат да се провалят няколко правила, а структурата улеснява свързването на грешките с полетата на формуляра във фронтенда:

```json
{
  "data": {
    "status": 400,
    "errors": {
      "email": ["Must be a valid email address.", "This domain is blocked."],
      "plan": ["Must be one of: free, pro."]
    }
  }
}
```

Потребителските обратни извиквания `validate` за валидиране се изпълняват от страната на сървъра за всичко, което вградените правила не обхващат: блокиране на домейни, проверка между полета, външни справки.

### Данни за конкретен потребител

За данни за отделния потребител, като задачи, любими или чернови, задайте `userScoped` на `true`, а Blockstudio ще се погрижи за останалото. Той добавя колона `user_id`, задава я автоматично при създаване и ограничава всяка заявка до текущия потребител. Актуализациите и изтриванията проверяват собствеността. Не е нужно ръчно поле `user_id`, хук `before_create` или филтриране в RPC. Само един ред конфигурация. При използване на хранилище `post_type` `userScoped` се съпоставя с `post_author` вместо с отделна колона.

```php
return [
    'storage'    => 'sqlite',
    'userScoped' => true,
    'fields'     => [ /* ... */ ],
];
```

### Периодична проверка за актуализации

Задайте `'realtime' => true` във вашата схема и клиентът автоматично ще проверява за промени. Когато нещо се промени на сървъра, хранилището Interactivity API се актуализира и UI се рендира повторно без промени от ваша страна в JavaScript. Конфигурирайте чрез `'realtime' => ['key' => 'todos', 'interval' => 5000]`, за да зададете потребителски ключове на състоянието и интервали. Проверката използва сравнение на хешове, за да намали заявките, и спира, когато разделът на браузъра е скрит.

### Сигурност, хукове, преносимост

Публичните крайни точки са защитени с автоматично добавен CSRF хедър `X-BS-Token`. Използвайте `'open'`, когато ви е необходим наистина неавтентикиран достъп, например за входящи уебхукове.

Хуковете на жизнения цикъл се изпълняват преди и след всяка операция за запис. Дефинирайте ги директно в `db.php` или глобално чрез действията WordPress.

Полетата могат да дефинират ключ `component` за рендиране на формуляри, управлявано от схема, чрез `bs_db_form()`.

С хранилище SQLite или JSONC цялото приложение се съдържа в една папка: кодът, логиката, контролът на достъпа и данните. Копирайте папката, за да внедрите приложението.

## RPC

Понякога CRUD не е достатъчен. Нужна ви е потребителска логика на сървъра: превключване на задача, изпращане на известие, обобщаване на статистика. За това служи `rpc.php`. Дефинирайте функция PHP, извикайте я от фронтенда с `bs.fn()`, а Blockstudio ще се погрижи за крайната точка REST, удостоверяването, CSRF защитата и сериализацията JSON. Моделът е вдъхновен от [tRPC](https://trpc.io): процедурите се дефинират от страната на сървъра, а клиентът ги извиква по име.

```php title="rpc.php"
return [
    'subscribe' => function (array $params): array {
        $email = sanitize_email($params['email']);
        return ['success' => true];
    },
];
```

```js
const result = await bs.fn('subscribe', { email: 'user@example.com' });
```

Вградените скриптове (`script-inline.js`) автоматично разпознават името на блока от атрибута `data-block` в своя етикет script, така че не е нужно да го подавате ръчно. Скриптовете с модули го получават като трети аргумент.

Опциите за контрол на достъпа включват `public` (с CSRF), `'open'` (без защита), низове с възможности или масиви. Поддържат се и контрол на метода HTTP за всяка функция, хукове на жизнения цикъл и извиквания между блокове от JS и PHP.

## Cron

Фоновите задачи се дефинират във файл `cron.php`. Задайте график и обратно извикване, а Blockstudio ще ги регистрира в WordPress Cron при инициализация. При деактивиране на приставката всички задачи се премахват от графика.

```php title="cron.php"
return [
    'cleanup' => [
        'schedule' => 'daily',
        'callback' => function () {
            $db = Db::get('my-theme/app', 'logs');
            // delete old entries
        },
    ],
    'sync' => [
        'schedule' => 'hourly',
        'callback' => function () {
            // pull from external API
        },
    ],
];
```

Поддържат се всички вградени графици на WordPress, както и потребителски интервали чрез филтъра `cron_schedules`.

## CLI

Нова команда `wp bs` обхваща пълния набор функции на Blockstudio: блокове, база данни, RPC, cron, настройки, компилация на Tailwind, компилация на SCSS, потребителски полета и управление на активите.

```bash
wp bs blocks list --components
wp bs db schemas
wp bs db create my-theme/app subs --email=a@b.com
wp bs db list my-theme/app subs --plan=pro --format=json
wp bs rpc call my-theme/app subscribe --email=a@b.com
wp bs cron run my-theme/app cleanup
wp bs tailwind compile --file=template.html
wp bs scss compile --file=style.scss
wp bs fields list
wp bs assets list --type=global
wp bs settings get tailwind/enabled
```

Всички команди поддържат `--format=json` за скриптове.

## Подобрения на повтарящите се полета

### textMinimized за обектни полета

Свитите редове на повтарящите се полета вече обработват правилно стойностите на обектните полета. Преди, ако зададете `textMinimized` към поле за връзка, се показваше `[object Object]`. Сега Blockstudio автоматично прочита правилното подпотребителско свойство според типа на полето: `title` за връзки, `value` за цветове и градиенти, `icon` за икони. Можете също да зададете изрично свойство `key`, за да прочетете всяко подпотребителско свойство.

```json
{
  "type": "repeater",
  "textMinimized": { "id": "href", "fallback": "Add a link" },
  "attributes": [{ "id": "href", "type": "link" }]
}
```

### RichText и MediaPlaceholder

И двата компонента на шаблона вече работят в повтарящи се полета, като нотацията със скоби насочва към правилния ред. Във всеки ред на повтарящо се поле можете да редактирате заглавия и абзаци директно, както и да качвате медийни файлове.

```twig
{% for item in a.items %}
  <div class="card">
    <MediaPlaceholder attribute="items[{{ loop.index0 }}].image" />
    <RichText tag="h2" attribute="items[{{ loop.index0 }}].heading" />
    <RichText tag="p" attribute="items[{{ loop.index0 }}].content" />
  </div>
{% endfor %}
```

## Условия за потребителски полета с idStructure

При използване на потребителско поле с `idStructure` условията в дефиницията на полето вече автоматично променят идентификаторите си, за да съответстват на разгънатите имена. Ако групата ви полета за размер на шрифта има условие за `enable` и я разгънете с `idStructure: "title_font_{id}"`, условието вече правилно препраща към `title_font_enable` вместо към оригиналния `enable`.

Поддържат се и условия на ниво препратка. Добавете `conditions` към препратката към потребителското поле, за да ги приложите наведнъж към всяко разгънато поле.

## Динамични аргументи за попълване

Аргументите за попълване вече могат да препращат към други атрибути на блокове чрез синтаксиса `{attributes.*}`. Когато посоченият атрибут се промени, полето за избор автоматично зарежда отново опциите си. Свържете полетата за избор: едното избира типа публикация, а другото зарежда публикациите от този тип.

```json
{
  "id": "selected_post",
  "type": "select",
  "populate": {
    "type": "query",
    "query": "posts",
    "arguments": {
      "post_type": "{attributes.post_type}"
    }
  }
}
```

Задайте `post_type` на "page" и второто поле за избор ще зареди страниците. Задайте го на "post" и то ще зареди публикациите. Работи с всеки тип попълване и всеки атрибут.

## Composer

Blockstudio вече работи при зареждане от всяко място под `wp-content/`, а не само от директорията с приставки. URL адресите на активите се разрешават чрез константа `BLOCKSTUDIO_URL` вместо чрез `plugins_url()`, така че инсталациите с вграждане в тема работят веднага:

```php title="functions.php"
require_once __DIR__ . '/vendor/autoload.php';
require_once __DIR__ . '/vendor/blockstudio/blockstudio/blockstudio.php';
```

Зависимостите по време на изпълнение на `composer.json` са изчистени. Пакетите с обхват (TailwindPHP, ScssPhp, Minify), които вече са включени в `lib/`, вече не са посочени като зависимости по време на изпълнение. Остават само `php >= 8.2` и `plugin-update-checker`.

И трите начина на инсталиране (ZIP архив на приставка, приставка чрез Composer, вграждане в тема чрез Composer) се стартират с един и същ резултат: пълно активиране на WordPress, регистрация на блоковете и рендиране във фронтенда.

Вижте документацията на [Composer](https://blockstudio.dev/bg/docs/dev/composer/) за инструкции за настройка.

## Профилировчик на производителността

Добавете `?blockstudio-perf` към всеки URL на страница и в долната част ще се появи панел за отстраняване на грешки с времето за рендиране на всеки блок, разбивка по фази и проценти на попадения в кеша. Данните за времето се изпращат и като заглавки Server-Timing, видими в раздела Network на DevTools на браузъра.

```json title="blockstudio.json"
{ "dev": { "perf": true } }
```

Включете го за постоянно в настройките, за да профилирате всяко зареждане на страница. Вижда се само от влезли потребители с възможност `edit_posts`.

Самозатварящите се етикети на блокове вече също се кешират в паметта. Когато един и същ блок с идентични атрибути се появи няколко пъти на страницата, следващите рендирания пропускат целия процес на шаблона.

## Поправки на грешки

- **Предупреждения за остарели функции в PHP 8.4**: Поправени са предупрежденията за остарели функции `strpos()` и `str_replace()`, причинени от предаването на `null` към `add_submenu_page()`.

## Още

- **Полета за код SCSS**: Полетата за код поддържат `language: "scss"`. Стойностите се компилират чрез ScssPhp както в редактора, така и във фронтенда.
- **Стандартни блокове WordPress**: Директориите Blockstudio могат да съдържат изход `@wordpress/create-block` наред с блоковете Blockstudio. Те се регистрират автоматично без отделен код за приставка.

---

Ако искате да видите модела с пълен стек в действие, ръководството [Блокове с пълен стек](https://blockstudio.dev/bg/guides/full-stack-blocks/) описва стъпка по стъпка изграждането от нулата на приложение за задачи за отделни потребители и публичен формуляр за абонамент за бюлетин.
