Pular para o conteúdo

Dennis · 10 de abril de 2026

Blockstudio 7.2

Blockstudio 7.2 expande o framework em duas frentes ao mesmo tempo.

A primeira é visibilidade e fluxo de trabalho dentro de um único projeto: uma nova visão geral administrativa, um navegador de banco de dados, um navegador do registro administrativo e prelúdios SCSS para configurações compartilhadas de Sass.

A segunda é o ecossistema em torno de Blockstudio: um registro CLI para distribuir blocos (como shadcn para WordPress) e uma extensão PHPStan que traz segurança de tipos no estilo TypeScript para templates, tags de bloco, db.php, rpc.php, cron.php e os arquivos de esquema relacionados.

As duas frentes têm o mesmo objetivo: facilitar o entendimento, a evolução e o compartilhamento de projetos maiores de Blockstudio.

Experiência administrativa

Duas adições facilitam a navegação de projetos maiores no wp-admin.

Visão geral administrativa

Agora, Blockstudio inclui uma tela administrativa em Ferramentas > Blockstudio. Ela oferece um só lugar para inspecionar o que o sistema registrou a partir do sistema de arquivos.

A visão geral inclui abas dedicadas a:

  • Blocos
  • Extensões
  • Campos
  • Páginas
  • Esquemas

Além dessa visão geral, a área administrativa agora inclui uma seção dedicada a Bancos de dados. Ela lista todos os esquemas Blockstudio\Db registrados e permite inspecionar registros reais diretamente no wp-admin.

Em vez de criar uma grade personalizada de painéis, a tela usa tabelas DataViews nativas do WordPress. Assim, a UI fica alinhada ao wp-admin e continua prática mesmo quando um projeto tem dezenas ou centenas de registros.

Em uma instalação pequena, você consegue manter na cabeça o estado de execução. Em uma base de código maior, isso deixa de funcionar. Surgem perguntas como:

  • Quais blocos estão realmente registrados agora?
  • Quais extensões se aplicam a core/* e quais se aplicam a blocos individuais?
  • Quais páginas estão sincronizadas e a quais tipos de publicação pertencem?
  • Quais campos reutilizáveis existem neste projeto?
  • Quais esquemas estão registrados e qual backend de armazenamento eles usam?

Até agora, a resposta exigia alguma combinação de examinar pastas, abrir arquivos JSON e percorrer PHP. A visão geral transforma isso em uma interface administrativa concreta.

Cada aba foi criada para responder a perguntas diferentes:

  • Blocos mostra os tipos de bloco registrados, o modo de renderização, a versão API e a contagem de atributos
  • Extensões mostra os blocos aos quais se aplicam, além da prioridade e dos detalhes de renderização
  • Campos oferece um inventário rápido das definições reutilizáveis de campos personalizados
  • Páginas mostra páginas sincronizadas baseadas em arquivos, com tipo de publicação, status, mecanismo de template e estado da sincronização
  • Esquemas apresenta os esquemas de armazenamento registrados, com backend, quantidade de campos e escopo de capacidade

O navegador do banco de dados é mantido intencionalmente separado da carga inicial da visão geral. Em vez de serializar todas as linhas ao carregar a página, ele apenas localiza os esquemas disponíveis de início e busca os registros sob demanda quando você abre uma aba do banco de dados. Assim, a área administrativa continua útil mesmo quando um projeto tem conjuntos de dados maiores por trás de db.php.

Esta primeira versão é intencionalmente voltada para registros vinculados a esquemas. Não é uma página de configurações. É uma página de inspeção.

Se não quiser usar esse recurso, desative-o por completo:

PHP
add_filter('blockstudio/admin/enabled', '__return_false');

Navegador do registro administrativo

Ao lado da visão geral, há uma segunda aba: Registro. Ela permite navegar pelos registros remotos de blocos configurados no blocks.json do seu tema e importar blocos diretamente do painel administrativo do WordPress sem tocar em um 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}"
      }
    }
  }
}

O navegador consulta cada registro configurado, lista todos os blocos disponíveis e mostra se já estão instalados localmente ou se podem ser importados. Cada linha tem um botão Importar que baixa os arquivos do bloco para o diretório configurado do seu tema. Para os blocos já instalados, aparece um botão Reimportar.

Há suporte a registros autenticados usando o formato de objeto com headers, incluindo interpolação de ${ENV_VAR} para que os tokens nunca sejam incluídos no controle de versão.

Isso torna a navegação e o uso de registros uma experiência administrativa integrada, em vez de apenas um fluxo de trabalho de CLI.

Registro CLI

A outra parte da história dos registros é um CLI independente: blockstudio/registry.

É uma ferramenta no estilo shadcn para blocos WordPress. Sem pacote npm, sem etapa de compilação. Você executa um comando, o código-fonte do bloco é copiado para o seu projeto e passa a ser totalmente seu.

Shell
npx blockstudio init
npx blockstudio add ui/tabs

O CLI funciona com qualquer tipo de bloco: blocos Blockstudio, saída @wordpress/create-block, blocos PHP simples. O registro não se importa com o conteúdo da pasta. Ele lê o manifesto de arquivos de registry.json e copia exatamente esses arquivos.

Os autores de blocos publicam um registry.json em qualquer URL (conteúdo bruto de GitHub, S3, um servidor personalizado) que lista os blocos disponíveis, com metadados, dependências e listas de arquivos. Os usuários adicionam o URL ao seu blocks.json e obtêm blocos pelo nome.

O CLI oferece suporte a:

  • Resolução de dependências: os blocos podem declarar dependências de outros blocos, resolvidas automaticamente com detecção de ciclos
  • Tratamento de conflitos entre vários registros: quando o mesmo nome de bloco existe em vários registros, o CLI pede que você escolha um
  • Registros autenticados: tokens bearer, autenticação básica e cabeçalhos personalizados com interpolação de variáveis de ambiente
  • TUI interativa: criada com Ink, com indicadores de atividade, prompts de seleção e indicadores de progresso
  • Modo não interativo: sinalizador --yes e fallback automático para CI/entrada redirecionada por pipe
  • Pesquisa e listagem: navegue pelos registros na linha de comando

O pacote inclui testes 130 que abrangem esquemas, resolução de dependências, busca de HTTP, gravação de arquivos, todos os fluxos de comandos e a UI interativa do Ink.

Documentação completa em blockstudio.dev/registry.

Extensão PHPStan

A outra grande novidade é blockstudio/phpstan: uma extensão de PHPStan que oferece aos usuários do Blockstudio a segurança de tipos que os desenvolvedores TypeScript esperam.

Shell
composer require --dev blockstudio/phpstan

A extensão lê os esquemas reais do seu projeto durante a análise e fornece os tipos resultantes ao PHPStan. Agora, isso abrange templates PHP, Twig, Blade, tags de bloco, registros de banco de dados tipados, caminhos de configurações, nomes de hooks e validação de esquemas em block.json, field.json, JSON de extensão, page.json, db.php, rpc.php, cron.php e blockstudio.json.

Templates de bloco com segurança de tipos

Os acessos a campos em $a são validados em relação ao block.json correspondente:

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"?

Registros de banco de dados com segurança de tipos

Db::get() retorna uma instância tipada com base no seu esquema db.php. A estrutura do registro é criada a partir dos campos reais:

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}

Validação de esquemas

Arquivos de esquema inválidos são detectados durante a análise: block.json, field.json, JSON de extensão, page.json, db.php, rpc.php, cron.php e blockstudio.json. Nomes ausentes, tipos de campo incorretos, definições malformadas e valores booleanos abreviados obsoletos ("tailwind": true em vez do objeto aninhado) são todos informados com a linha exata no arquivo de origem.

Validação de caminhos de configurações

As chamadas Settings::get() são validadas em relação ao esquema de configurações conhecido:

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"?

Validação de nomes de hooks

O mesmo vale para os nomes de hooks de filtro e de ação:

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

A extensão também inclui stubs para toda a Blockstudio API pública do Db: Settings, Field_Registry, Build e funções auxiliares globais. Você tem preenchimento automático e verificação de tipos para todas as APIs do Blockstudio sem precisar do código-fonte do plugin na sua máquina de desenvolvimento.

Facilidades para autoria

Duas pequenas facilidades para autoria completam esta versão.

Prelúdios globais de SCSS

Blockstudio já oferecia compilação de SCSS, mas havia um ponto de atrito incômodo: a configuração compartilhada de Sass.

Se você quisesse acessar um conjunto comum de variáveis, funções ou mixins, precisava importá-los em cada arquivo SCSS. Isso logo se torna repetitivo, especialmente em sistemas de design maiores ou em toolkits Sass como Bootstrap.

A versão 7.2 adiciona um hook de prelúdio para resolver exatamente isso:

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

Combinado com o filtro blockstudio/assets/process/scss/import_paths já existente, você define uma interface compartilhada de Sass uma única vez, e ela fica disponível para todos os arquivos compilados.

Assim, a folha de estilos de um bloco pode se concentrar nos estilos de que realmente precisa:

Scss
.hero {
  @include media-breakpoint-up(lg) {
    padding: 4rem;
  }
}

Sem importações repetidas em cada recurso do bloco. Não é um “suporte a Bootstrap” em um modo especial. É um hook genérico para compartilhar Sass em um projeto, seja isso fornecido por Bootstrap ou pelo seu próprio toolkit interno.

Definições de API de blocos nativas de PHP

A versão 7.2 também adiciona uma sintaxe opcional nativa de PHP para as APIs full-stack de blocos. Os arrays continuam sendo o padrão e têm suporte completo. Nada foi substituído. Mas, se você prefere argumentos nomeados, enums e atributos a arrays de configuração aninhados, agora pode optar por esse estilo.

Para rpc.php, retorne um objeto com métodos atribuídos:

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

Para cron.php, a mesma ideia funciona com #[Cron]:

PHP
<?php
use Blockstudio\Attributes\Cron;
use Blockstudio\Cron\Schedule;

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

E, para db.php, agora há uma pequena camada de construção:

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

Isso oferece um equilíbrio melhor para bases de código maiores. Você mantém a simplicidade do formato de array quando quiser e pode mudar para uma interface de PHP mais fácil de explorar quando um bloco passa a ter mais do que alguns campos ou endpoints.

Por que esses recursos são lançados juntos

A visão geral administrativa, o navegador de registros, o CLI de registros e a extensão PHPStan respondem à mesma pergunta: como manter um projeto Blockstudio compreensível à medida que ele cresce?

As ferramentas administrativas respondem a essa pergunta no nível do projeto: visibilidade do que está registrado, possibilidade de obter blocos dos registros e menos suposições.

O CLI responde a essa pergunta no nível do ecossistema: uma forma de compartilhar blocos entre projetos e equipes sem agrupá-los em pacotes npm nem enfrentar sistemas de compilação.

A extensão PHPStan responde a essa pergunta no nível do código: ela detecta acessos a campos incorretos, erros de digitação em esquemas e callbacks de hooks com problemas antes que cheguem à execução.

Essa é a direção geral da versão 7.2: menos suposições, menos repetição, mais visibilidade e agora segurança de tipos de verdade.

Correções de bugs

  • Campo de classes: nomes de classes personalizados digitados pelo usuário eram descartados silenciosamente ao perder o foco, porque o validador aceitava apenas classes da lista predefinida de Tailwind/configurações. Agora, aceita qualquer string não vazia.
  • Campo de atributos: a remoção de um par de atributos deixava entradas null nos dados salvos. Substituímos lodash unset() (que define elementos de arrays como nulos) por splice() (que os remove).
  • Minificador de CSS: o minificador de TailwindPHP removia espaços em branco ao redor de + dentro de calc() e clamp(), gerando CSS inválido, como calc(1rem+0.5vw). A correção foi feita no projeto original em TailwindPHP v1.3.1 com uma varredura de caracteres que considera a profundidade e só remove espaços em branco ao redor de combinadores de seletores no nível de parênteses 0.
  • Prévia do inseridor de blocos: $isPreview sempre era false na prévia do inseridor de blocos porque o hash da chave do cache de renderização não incluía o modo de renderização. Agora, as renderizações do editor e da prévia geram entradas de cache separadas.
  • Template aninhado de InnerBlocks: o componente <InnerBlocks template="..."/> descartava o terceiro elemento (filhos) de tuplas de template como ['core/group', {}, [['core/paragraph']]], gerando blocos contêiner vazios. Agora, preserva os filhos aninhados.