
Blockstudio 7.2 разширява рамката в две посоки едновременно.

Първата е **видимост и работен процес** в рамките на един проект: нов административен преглед, браузър за базата данни, браузър за административния регистър и прелюдии SCSS за споделена настройка на Sass.

Втората е **екосистемата около Blockstudio**: регистър CLI за разпространение на блокове (като shadcn за WordPress) и разширение PHPStan, което добавя към шаблоните, етикетите на блокове, `db.php`, `rpc.php`, `cron.php` и свързаните файлове на схемата безопасност на типовете в стил TypeScript.

И двете посоки са насочени към едно и също: да улеснят разбирането, надграждането и споделянето на по-големи проекти с Blockstudio.

## Административна среда

Две допълнения улесняват навигацията в по-голям проект в wp-admin.

### Административен преглед

Blockstudio вече включва административен екран в **Инструменти > Blockstudio**. Той предоставя едно място, където да прегледате какво е регистрирала системата от файловата система.

Прегледът включва отделни раздели за:

- Блокове
- Разширения
- Полета
- Страници
- Схеми

Наред с този преглед, административната област вече включва отделен раздел **Бази данни**. В него са изброени всички регистрирани схеми `Blockstudio\Db` и можете да проверявате записите директно в wp-admin.

Вместо да се изгражда потребителска мрежа от панели, екранът използва вградени таблици DataViews на WordPress. Така UI се съгласува с wp-admin и остава практичен, когато проектът има десетки или стотици регистрации.

При малка инсталация можете да държите състоянието по време на изпълнение в главата си. При по-голяма кодова база това вече не работи. Започвате да си задавате въпроси като:

- Кои блокове са регистрирани в момента?
- Кои разширения са насочени към `core/*` и кои към отделни блокове?
- Кои страници са синхронизирани и към кои типове публикации принадлежат?
- Кои многократно използваеми полета съществуват в този проект?
- Кои схеми са регистрирани и кое хранилище използват?

Досега отговорът изискваше комбинация от преглеждане на папки, отваряне на файлове JSON и проследяване на PHP. Прегледът превръща това в пълноценен административен интерфейс.

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

- **Блокове** показва регистрираните типове блокове, режима на рендиране, версията на API и броя на атрибутите
- **Разширения** показва към кои блокове са насочени, както и приоритета и подробностите за рендиране
- **Полета** дава бърз преглед на дефинициите на многократно използваемите потребителски полета
- **Страници** показва синхронизираните страници, базирани на файлове, с типа публикация, състоянието, шаблонния механизъм и състоянието на синхронизацията
- **Схеми** показва регистрираните схеми за съхранение с хранилището, броя на полетата и обхвата на възможностите

Браузърът на базата данни умишлено е отделен от първоначалния обзорен
payload. Вместо да сериализира всеки ред при зареждане на страницата, той
предварително зарежда само наличните схеми и извлича записи при поискване,
когато отворите раздел на база данни. Така административният интерфейс остава
полезен дори когато проектът съдържа големи масиви от данни зад `db.php`.

Първата версия умишлено е съсредоточена върху регистрации, базирани на схеми.
Това не е страница с настройки. Това е страница за преглед.

Ако изобщо не я искате, деактивирайте я напълно:

```php
add_filter('blockstudio/admin/enabled', '__return_false');
```

### Браузър на административния регистър

До обзора има втори раздел: **Регистър**. Той е браузър за отдалечените регистри на блокове, конфигурирани във файла `blocks.json` на темата ви, и ви позволява да импортирате блокове директно от администрацията на WordPress, без да докосвате CLI.

```json title="blocks.json"
{
  "directory": "blockstudio",
  "registries": {
    "ui": "https://blocks.example.com/registry.json",
    "private": {
      "url": "https://api.example.com/registry.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}
```

Браузърът извлича данните от всеки конфигуриран регистър, показва всички налични блокове и указва дали вече са инсталирани локално, или могат да бъдат импортирани. Всеки ред има бутон „Импортиране“, който изтегля файловете на блока в конфигурираната директория на темата ви. За вече инсталираните блокове вместо него има бутон „Импортиране отново“.

Поддържат се регистри с удостоверяване чрез обектен формат с `headers`, включително интерполация на `${ENV_VAR}`, така че токените никога да не попадат в контрола на версиите.

Така разглеждането и използването на регистри става първокласна административна функционалност, а не просто работен процес с CLI.

## Регистър CLI

Другата част от историята с регистрите е самостоятелен CLI: `blockstudio/registry`.

Това е инструмент в стила на shadcn за блокове WordPress. Няма пакет npm, няма стъпка за изграждане.
Изпълнявате команда, изходният код на блока се копира в проекта ви и
остава изцяло ваш.

```bash
npx blockstudio init
npx blockstudio add ui/tabs
```

CLI работи с всеки тип блок: блокове Blockstudio, изход `@wordpress/create-block`,
обикновени блокове PHP. Регистърът не се интересува какво има в папката.
Той прочита манифеста на файловете от `registry.json` и копира точно посочените файлове.

Авторите на блокове публикуват `registry.json` на произволен URL (GitHub сурово съдържание, S3, персонализиран сървър), в който изброяват наличните си блокове заедно с метаданни, зависимости и списъци с файлове. Потребителите добавят URL към своя `blocks.json` и изтеглят блокове по име.

CLI поддържа:

- **Разрешаване на зависимости**: блоковете могат да декларират зависимости от други блокове, които се разрешават автоматично с откриване на цикли
- **Обработка на конфликти между множество регистри**: когато блок със същото име присъства в няколко регистъра, CLI ви подканва да изберете един
- **Регистри с удостоверяване**: bearer токени, базово удостоверяване и персонализирани заглавки с интерполация на променливи на средата
- **Интерактивен TUI**: изграден с Ink, със спинери, подкани за избор и индикатори за напредъка
- **Неинтерактивен режим**: флаг `--yes` и автоматично преминаване към резервен режим за CI/поток
- **Търсене и изброяване**: разглеждане на регистри от командния ред

Пакетът включва 130 теста, които обхващат схемите, разрешаването на зависимости,
извличането от HTTP, записването на файлове, всички командни потоци и
интерактивния Ink UI.

Пълната документация е на адрес [blockstudio.dev/registry](https://blockstudio.dev/bg/registry/).

## Разширение PHPStan

Другото голямо допълнение е `blockstudio/phpstan`: разширение за PHPStan, което предоставя на потребителите на Blockstudio безопасността на типовете, която разработчиците на TypeScript очакват.

```bash
composer require --dev blockstudio/phpstan
```

Разширението чете действителните схеми на проекта ви по време на анализа и подава получените типове обратно към PHPStan. Така вече се обхващат шаблони PHP, Twig,
Blade, етикети на блокове, типизирани записи в базата данни, пътища до настройки, имена на куки и валидиране на схеми в `block.json`, `field.json`, разширение JSON,
`page.json`, `db.php`, `rpc.php`, `cron.php` и `blockstudio.json`.

### Шаблони за блокове с проверка на типовете

Достъпите до полета в `$a` се проверяват спрямо съседния `block.json`:

```php title="blockstudio/hero/index.php"
<?php
/** @var array<string, mixed> $a */

echo $a['title'];     // OK
echo $a['cta']['href']; // OK
echo $a['typo'];      // ERROR: Field "typo" does not exist in block.json (block: hero). Did you mean "title"?
```

### Записи в базата данни с проверка на типовете

`Db::get()` връща типизиран екземпляр въз основа на схемата `db.php`. Структурата на записа се изгражда от действителните полета:

```php title="db.php"
return [
  'storage' => 'table',
  'fields' => [
    'email' => ['type' => 'string', 'required' => true],
    'name'  => ['type' => 'string'],
  ],
];
```

```php
$db = Db::get('mytheme/subscribers');
$record = $db->create(['email' => 'a@b.com']);

echo $record['email']; // PHPStan: string
echo $record['name'];  // PHPStan: string|null
echo $record['typo'];  // ERROR: Offset 'typo' does not exist on array{id: int, email: string, name: string|null}
```

### Валидиране на схеми

Невалидните файлове със схеми се откриват по време на анализа: `block.json`, `field.json`,
разширение JSON, `page.json`, `db.php`, `rpc.php`, `cron.php` и
`blockstudio.json`. Липсващи имена, грешни типове полета, неправилно оформени дефиниции,
остарели съкратени булеви стойности (`"tailwind": true` вместо вложения
обект) — всички се докладват с точния ред във файла с изходния код.

### Валидиране на пътищата до настройките

Извикванията на `Settings::get()` се проверяват спрямо известната схема на настройките:

```php
Settings::get('tailwind/enabled');  // OK, returns bool
Settings::get('tailwind/enabld');   // ERROR: Settings path "tailwind/enabld" is not a known Blockstudio setting. Did you mean "tailwind/enabled"?
```

### Валидиране на имена на куки

Същото важи и за имената на куки за филтри и действия:

```php
add_filter('blockstudio/render', $cb);  // OK
add_filter('blockstudio/rendrr', $cb);  // ERROR: Unknown Blockstudio hook "blockstudio/rendrr". Did you mean "blockstudio/render"?
```

Разширението включва и заглушки за целия публичен Blockstudio API: `Db`,
`Settings`, `Field_Registry`, `Build` и глобални помощни функции. Получавате автоматично довършване
и проверка на типовете за всички Blockstudio API, без да е необходим изходният код на плъгина на машината ви за разработка.

## Удобства при разработката

Две по-малки удобства при разработката допълват тази версия.

### Глобални прелюдии SCSS

Blockstudio вече поддържаше компилация на SCSS, но имаше един досаден проблем: споделена настройка на Sass.

Ако искахте достъп до общ набор от променливи, функции или миксини,
трябваше да ги импортирате във всеки файл SCSS. Това бързо става досадно, особено
при по-големи системи за дизайн или набори от инструменти Sass като Bootstrap.

Версия 7.2 добавя кука за прелюдия именно за тази цел:

```php
add_filter('blockstudio/assets/process/scss/prelude', function($prelude, $path, $scss) {
  return '@import "functions";' . "\n"
    . '@import "variables";' . "\n"
    . '@import "mixins";';
}, 10, 3);
```

В съчетание със съществуващия филтър `blockstudio/assets/process/scss/import_paths` веднъж дефинирате споделена
повърхност на Sass и тя става достъпна във всеки компилиран файл.

Стиловият файл на блока може да се съсредоточи върху реално необходимите стилове:

```scss title="style.scss"
.hero {
  @include media-breakpoint-up(lg) {
    padding: 4rem;
  }
}
```

Във всеки ресурс на блок няма нужда от повтарящи се импорти. Това не е специален режим за „поддръжка на Bootstrap“. Това е обща кука за споделяне на Sass в рамките на проекта, независимо дали идва от Bootstrap, или от ваш собствен вътрешен набор от инструменти.

### Дефиниции на блокове PHP с естествен синтаксис на API

Версия 7.2 добавя и незадължителен синтаксис с естествен за PHP подход за API на блокове с пълен набор от възможности. Масивите остават стандартният и напълно поддържан вариант. Нищо не е заменено. Но ако предпочитате именувани аргументи, енумерации и атрибути пред вложени конфигурационни масиви, вече можете да изберете този стил.

За `rpc.php` върнете обект с методи, декорирани с атрибути:

```php title="rpc.php"
<?php
use Blockstudio\Attributes\Rpc;
use Blockstudio\Rpc\Access;
use Blockstudio\Rpc\Method;

return new class {
    #[Rpc(access: Access::Session)]
    public function subscribe(array $params): array {
        return ['success' => true];
    }

    #[Rpc(name: 'status', methods: [Method::Get, Method::Post])]
    public function getStatus(array $params): array {
        return ['status' => 'ok'];
    }
};
```

За `cron.php` същият подход работи с `#[Cron]`:

```php title="cron.php"
<?php
use Blockstudio\Attributes\Cron;
use Blockstudio\Cron\Schedule;

return new class {
    #[Cron(schedule: Schedule::Hourly)]
    public function heartbeat(): void {
    }
};
```

А за `db.php` вече има и малък слой за изграждане:

```php title="db.php"
<?php
use Blockstudio\Db\Field;
use Blockstudio\Db\Schema;
use Blockstudio\Db\Storage;

return Schema::make(
    storage: Storage::Table,
    fields: [
        'email' => Field::string(required: true, format: 'email'),
        'active' => Field::boolean(default: false),
    ],
);
```

Това осигурява по-добър баланс за по-големи кодови бази. Когато ви е удобно, запазвате простотата на формата с масиви, а когато блокът надрасне няколкото полета или крайни точки, можете да преминете към по-лесна за откриване повърхност на PHP.

## Защо тези неща се доставят заедно

Административният обзор, браузърът на регистъра, регистърът CLI и разширението PHPStan са отговори на един и същ въпрос: как да поддържате проекта Blockstudio разбираем с разрастването му?

Административните инструменти отговарят на ниво проект: видимост върху регистрираните неща, възможност за добавяне на блокове от регистри и по-малко догадки.

CLI отговаря на ниво екосистема: начин за споделяне на блокове между проекти и екипи, без да ги пакетирате в npm пакети или да се борите със системите за изграждане.

Разширението PHPStan отговаря на ниво код: открива грешни достъпи до полета, печатни грешки в схемите и неработещи обратни извиквания на куки, преди да стигнат до изпълнение.

Това е общата посока на версия 7.2: по-малко догадки, по-малко повтаряне, по-добра видимост и вече истинска безопасност на типовете.

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

- **Поле за класове**: въведените от потребителя персонализирани имена на класове се премахваха безшумно при загуба на фокус, защото валидаторът приемаше само класове от предварително зададения списък Tailwind/настройки. Вече приема всеки непразен низ.
- **Поле за атрибути**: премахването на двойка атрибути оставяше записи `null` в запазените данни. Заменихме lodash `unset()` (който занулява елементи от масив) с `splice()` (който ги премахва).
- **Минификатор CSS**: минификаторът TailwindPHP премахваше интервалите около `+` в `calc()` и `clamp()`, като генерираше невалиден CSS, например `calc(1rem+0.5vw)`. Поправено в по-нова версия на TailwindPHP v1.3.1 чрез обхождане на символите с отчитане на дълбочината, което премахва интервали около комбинаторите в селекторите само при дълбочина на скобите 0.
- **Преглед в инструмента за вмъкване на блокове**: `$isPreview` винаги беше `false` в прегледа, защото хешът на кеша за рендиране не включваше режима на рендиране. Рендирането в редактора и в прегледа вече създава отделни записи в кеша.
- **Вложен шаблон InnerBlocks**: компонентът `<InnerBlocks template="..."/>` премахваше третия елемент (дъщерните елементи) от кортежи на шаблони като `['core/group', {}, [['core/paragraph']]]`, което създаваше празни блокове контейнери. Сега запазва вложените дъщерни елементи.
