Към съдържанието

Dennis · 10 април 2026 г.

Blockstudio 7.2

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
{
  "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, няма стъпка за изграждане. Изпълнявате команда, изходният код на блока се копира в проекта ви и остава изцяло ваш.

Обвивка
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.

Разширение PHPStan

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

Обвивка
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
<?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
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
.hero {
  @include media-breakpoint-up(lg) {
    padding: 4rem;
  }
}

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

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

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

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

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
<?php
use Blockstudio\Attributes\Cron;
use Blockstudio\Cron\Schedule;

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

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

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']]], което създаваше празни блокове контейнери. Сега запазва вложените дъщерни елементи.