
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 і кількість атрибутів
- **Розширення** показують, на які блоки вони націлені, а також пріоритет і подробиці рендерингу
- **Поля** дають змогу швидко переглянути власні визначення полів, придатних для повторного використання
- **Сторінки** показують синхронізовані сторінки з файлів, їхній тип допису, статус, рушій шаблонів і стан синхронізації
- **Схеми** показують зареєстровані схеми сховищ, тип сховища, кількість полів і область дії можливостей

Переглядач бази даних навмисно відокремлено від початкових даних огляду. Замість того щоб серіалізувати кожен рядок під час завантаження сторінки, він спочатку локалізує лише доступні схеми, а записи завантажує за запитом, коли ви відкриваєте вкладку бази даних. Завдяки цьому панель адміністратора залишається корисною навіть за наявності великих наборів даних у проєкті за `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}"
      }
    }
  }
}
```

Переглядач отримує дані з кожного налаштованого реєстру, показує всі доступні блоки й указує, чи встановлено їх локально, чи їх можна імпортувати. У кожному рядку є кнопка Import, яка завантажує файли блоку до налаштованої директорії теми. Для вже встановлених блоків натомість з’являється кнопка Reimport.

Реєстри з автентифікацією підтримуються у форматі об’єкта з `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, запис файлів, перебіг виконання кожної команди та інтерактивний UI на базі Ink.

Повна документація: [Документаціяblockstudio.dev/registry](https://blockstudio.dev/uk/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"?
```

Розширення також містить заглушки для всього публічного API Blockstudio: `Db`, `Settings`, `Field_Registry`, `Build` і глобальних допоміжних функцій. Ви отримуєте автодоповнення та перевірку типів для всіх API Blockstudio без потреби мати вихідний код плагіна на вашій машині для розробки.

## Зручності для розробки

Реліз доповнюють дві менші зручності для розробки.

### Глобальні преамбули 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: додано обхід символів з урахуванням рівня вкладеності, який видаляє пробіли навколо комбінаторів селекторів лише за нульового рівня дужок.
- **Попередній перегляд у вставнику блоків**: у попередньому перегляді вставника блоків `$isPreview` завжди мав значення `false`, оскільки режим відображення не входив до хеш-ключа кешу. Тепер відображення в редакторі й попередньому перегляді зберігаються в окремих записах кешу.
- **Вкладений шаблон InnerBlocks**: компонент `<InnerBlocks template="..."/>` відкидав третій елемент (дочірні блоки) з кортежів шаблонів на кшталт `['core/group', {}, [['core/paragraph']]]`, через що блоки-контейнери залишалися порожніми. Тепер вкладені дочірні блоки зберігаються.
