Przejdź do treści

PHPStan

Rozszerzenie blockstudio/phpstan zapewnia analizę statyczną projektów Blockstudio. Podczas analizy sprawdza szablony bloków, pliki schematów, ścieżki ustawień i nazwy hooków, wykrywając błędy, zanim pojawią się w czasie działania.

Instalacja

Powłoka
composer require --dev blockstudio/phpstan

Sprawdzanie typów szablonów i rozszerzona weryfikacja tagów bloków w wersji 7.7 wymagają blockstudio/phpstan 0.1.9 lub nowszej oraz PHPStan 2.1.47 lub nowszej. Zaktualizuj pakiet niezależnie od wtyczki:

Powłoka
composer require --dev blockstudio/phpstan:^0.1.9

Rozszerzenie jest automatycznie wykrywane przez instalator rozszerzeń PHPStan. Nie wymaga ręcznej konfiguracji.

Co sprawdza

Dostęp do pól szablonu

Gdy plik PHP znajduje się obok pliku block.json, rozszerzenie sprawdza każde odwołanie $a['key'] względem atrybutów zadeklarowanych przez blok.

PHP
<?php

echo $a['title'];     // OK
echo $a['subtitle'];  // OK
echo $a['typo'];      // Error: Field "typo" does not exist in block.json

Rozszerzenie wie, że Blockstudio definiuje $a, $attributes, $b, $block, $c, $context, $content, $isEditor, $isPreview i zmienne wyspowe, zanim dołączy szablon. Dlatego bezpośrednie odczyty, takie jak $a['title'], nie są zgłaszane jako potencjalnie niezdefiniowane, a typ $a jest określany na podstawie block.json obok szablonu. Struktura zachowuje się podczas zawężania typów, więc $a['label'] ?? '', isset( $a['cta']['target'] ) i $a['cta']['title'] !== null zachowują zadeklarowane typy pól; szablon, który przypisuje wartość do samego $a, zachowuje przypisany mu typ. Nie dodawaj bloku dokumentacyjnego /** @var array<string, mixed> $a */, ponieważ zastępuje on tę strukturę otwartą tablicą.

Klucze pól podlegają regułom spłaszczania w czasie działania Blockstudio. Kontenery tabs i anonimowe group bez id służą wyłącznie do prezentacji, więc ich pola potomne pozostają w zakresie nadrzędnym. Nazwana grupa dodaje ID grupy jako prefiks do kluczy pól potomnych:

PHP
echo $a['heading'];  // Anonymous group child.
echo $a['cta_text']; // "text" inside the named "cta" group.

Wielokrotnego użytku pola niestandardowe

Odwołania custom/* oparte na plikach są rozwijane przed sprawdzeniem kluczy szablonu i struktur tablic. Rozszerzenie odczytuje pasujący plik field.json i stosuje te same reguły idStructure, overrides, zagnieżdżonych odwołań, grup, kart i pól powtarzalnych co Blockstudio:

JSON
{
  "name": "mytheme/hero",
  "attributes": [
    { "id": "heading", "type": "text" },
    { "id": "description", "type": "textarea" }
  ]
}
JSON
{
  "blockstudio": {
    "attributes": [
      {
        "type": "custom/mytheme/hero",
        "idStructure": "hero_{id}",
        "overrides": {
          "heading": { "id": "title" }
        }
      }
    ]
  }
}

Powstałe klucze szablonu to title i hero_description. Są rozpoznawane w PHP, Twig, Blade, tagach bloków i wywnioskowanych strukturach atrybutów.

Brakujące, niejednoznaczne, nieprawidłowe lub cykliczne definicje oparte na plikach powodują konkretny błąd blockstudio.customField.*. Sprawdzanie zależnych kluczy jest pomijane dla tego bloku, aby jedna nierozstrzygnięta definicja nie powodowała kolejnej fali błędów dotyczących nieznanych pól.

Definicji rejestrowanych wyłącznie w czasie działania za pomocą filtra blockstudio/fields PHP nie można wywnioskować w analizie statycznej. Jeśli pole musi udostępniać klucze szablonu sprawdzane statycznie, użyj definicji field.json.

Dostęp do szablonów Twig

Szablony Twig są skanowane automatycznie. Nie są wymagane adnotacje.

Twig
<h1>{{ a.title }}</h1>
<p>{{ a.typo }}</p>    {# Error: Field "typo" does not exist in block.json #}

Dostęp do szablonów Blade

Szablony Blade są skanowane w ten sam sposób.

Blade
<h1>{{ $a['title'] }}</h1>
<p>{{ $a['typo'] }}</p>    {{-- Error --}}

Weryfikacja tagów bloków

Tagi bloków są weryfikowane w miejscach, w których odczytuje je Blockstudio: tagi <bs:> i <block>, tagi prefiksowe skonfigurowane w blockTags.prefixes (takie jak <acme-card>, rozwiązywane w kolejności przestrzeni nazw, tak jak w czasie działania) oraz tagi aliasów w szablonach bloków PHP, Twig i Blade, a także w układach stron. Sprawdzane są również źródła stron w lokalizacji pages/ (index.php, index.html, index.twig, index.blade.php), w tym elementy HTML mapowane przez projekt na bloki. Dołączone bloki UI są rozpoznawane, gdy włączono ui.enabled.

HTML
<bs:mytheme-hero title="Hello" />
<!-- OK -->
<bs:mytheme-nonexistent />
<!-- Error: unknown block -->
<bs:mytheme-hero title="Hi" badattr="" />
<!-- Error: unknown attribute -->
<bs:mytheme-hero class="wide" />
<!-- Error: class is dropped unless the block declares a class field -->
<bs:mytheme-hero id="intro" aria-label="Intro" data-x="1" />
<!-- OK: forwarded to the root element -->
<block name="core/separator" />
<!-- OK (core blocks always valid) -->

Atrybut jest akceptowany, gdy blok deklaruje go jako pole (w tym pole niestandardowe lub pole typu blokowego przekazujące atrybuty pod swoim idStructure) albo gdy Blockstudio przekazuje go do elementu głównego bloku: data-*, aria-*, id, style, role, title, lang, dir, hidden i tabindex. W szablonach przekazywany jest każdy atrybut html-*; w źródłach stron prefiks html- wskazuje tylko jeden z przekazywanych atrybutów. Każdy inny atrybut, zwłaszcza niezadeklarowany class, jest zgłaszany, ponieważ Blockstudio go przechowuje, ale nigdy nie renderuje.

Środowisko uruchomieniowe rejestruje mapowania elementów i aliasy tagów w filtrach PHP, których analiza statyczna nie może ocenić, dlatego analiza odczytuje je z blockstudio.json. scanPhp sprawdza również tagi w innych plikach projektu PHP, takich jak znaczniki komponentów w modułach, nie zgłaszając tam nieznanych bloków:

JSON
{
  "phpstan": {
    "blockTags": {
      "elements": {
        "section": "theme/section",
        "h2": "theme/heading",
        "div": [
          { "attribute": "width", "block": "theme/row" },
          "theme/div"
        ]
      },
      "aliases": { "theme-button": "bsui/button" },
      "scanPhp": true
    }
  }
}

Element mapuje się na nazwę bloku albo na zestaw reguł sprawdzanych po kolei: wygrywa pierwsza reguła, której atrybut ma element, a zwykła nazwa bloku zawsze pasuje. Elementy, których projekt nie mapuje, zachowują swój blok rdzeniowy i nie są sprawdzane. Diagnostyka używa blockstudio.blockTag.unknown, blockstudio.blockTag.attribute i blockstudio.blockTag.class.

Typowanie rekordów bazy danych

Db::get() zwraca typowaną instancję na podstawie schematu db.php. Struktury rekordów są wywnioskowywane automatycznie.

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']; // string
echo $record['name'];  // string|null (optional field)
echo $record['typo'];  // Error: Offset 'typo' does not exist

Pola wymagane nie dopuszczają wartości null. Pola opcjonalne mają typ type|null. Pole id (int) jest zawsze obecne. To samo typowanie działa ze składnią buildera PHP-native Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field.

Walidacja ścieżek ustawień

Ścieżki Settings::get() są sprawdzane względem znanego schematu ustawień.

PHP
Settings::get('tailwind/enabled');  // OK, returns bool
Settings::get('tailwind/enabld');   // Error: Did you mean "tailwind/enabled"?

Walidacja nazw hooków

Nazwy hooków filtrów i akcji Blockstudio są weryfikowane.

PHP
add_filter('blockstudio/render', $cb);   // OK
add_filter('blockstudio/rendrr', $cb);   // Error: Did you mean "blockstudio/render"?

Dynamiczne hooki ustawień, takie jak blockstudio/settings/tailwind/enabled, są zawsze dozwolone. Hooki spoza Blockstudio są pomijane.

Walidacja schematów

Rozszerzenie weryfikuje każdy plik schematu Blockstudio w projekcie.

block.json:

  • Brakujące pole name
  • Brakujące pole type
  • Brakujące id w polach wartości, które go wymagają
  • Nieznane typy pól
  • Właściwości pola nieakceptowane przez jego typ, takie jak "translat" zamiast "translate", z podpowiedzią najbliższej znanej właściwości
  • select/radio/checkbox bez options lub populate
  • Zduplikowane identyfikatory pól
  • Pole tabs wewnątrz pola powtarzalnego, bezpośrednio lub w grupie bez id
  • Nieprawidłowe deklaracje pluginDependencies

Pola kontenerowe, takie jak group i tabs, oraz odwołania do pól custom/* mogą pomijać id, jeśli tylko rozwijają lub opakowują inne pola.

Właściwości pól są sprawdzane pod kątem właściwości schemas/block.json zadeklarowanych dla każdego wbudowanego typu pola oraz właściwości akceptowanych przez każde pole. Właściwości specyficzne dla opakowania w odwołaniach custom/* i projektowe typy pól z przestrzeniami nazw nie są objęte tym sprawdzeniem. Nadal obowiązuje dotychczasowa walidacja typów pól i niestandardowych odwołań. Identyfikatory to blockstudio.blockJson.property i blockstudio.fieldJson.property.

Sprawdzane są nazwy właściwości, a nie tylko ich wartości: minimized jest prawidłowe w polu powtarzalnym, ale zostanie zgłoszone w polu tekstowym. Działanie wtyczki w czasie wykonywania pozostaje bez zmian. Jeśli projekt celowo dodaje własne metadane do wbudowanych pól, wycisz tylko te wyniki, nie wyłączając pozostałych kontroli struktury:

Neon
parameters:
    ignoreErrors:
        - identifier: blockstudio.blockJson.property
        - identifier: blockstudio.fieldJson.property

Wbudowane pola wewnątrz wielokrotnego użytku field.json są nadal sprawdzane, nawet gdy odwołanie custom/* ma własne opcje opakowania. Pliki rozszerzeń nie są objęte diagnostyką nazw właściwości; reguły set specyficzne dla rozszerzeń pozostają prawidłowe.

field.json (wielokrotnego użytku pola niestandardowe):

  • Brak name
  • Brak lub pusty attributes
  • Nieprawidłowe obiekty atrybutów lub brak pola type
  • Brak id w polach wartości, które go wymagają
  • Nieznane typy pól
  • Właściwości pola, których dany typ pola nie akceptuje
  • Pole tabs wewnątrz pola powtarzalnego, bezpośrednio lub w grupie bez id
  • Brakujące, niejednoznaczne lub nieprawidłowe zagnieżdżone odwołania custom/* albo odwołania cykliczne

Rozszerzenie JSON (rozszerzenia bloków w extensions/):

  • Brakujące name (blok docelowy)
  • Brakujący klucz blockstudio
  • Brakujący klucz blockstudio.extend

page.json (strony oparte na plikach):

  • Brakujące title
  • Brakujące slug
  • Nieprawidłowe wartości postStatus

db.php:

  • Brakująca tablica fields
  • Nieprawidłowe typy pól
  • Obsługiwane są zarówno starsze tablice, jak i Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field

rpc.php:

  • Nieprawidłowe metody HTTP
  • Nieprawidłowa wartość public (musi być true, false lub 'open')
  • Obsługiwane są zarówno starsze tablice, jak i zwracane obiekty z atrybutami

cron.php:

  • Brak schedule w skonfigurowanych zadaniach
  • Brak callback w skonfigurowanych zadaniach
  • Obsługuje zarówno starsze tablice, jak i zwracane obiekty z atrybutami

blockstudio.json:

  • Wartości logiczne w skróconej formie, takie jak "tailwind": true (należy używać zagnieżdżonego formatu obiektu {"enabled": true, "config": ""})

Konfiguracja

Rozszerzenie domyślnie wykrywa pliki Blockstudio w analizowanym projekcie. Jeśli projekt korzysta z bloków lub pól wielokrotnego użytku z biblioteki spoza katalogu głównego projektu, dodaj ścieżkę biblioteki do blockstudioScanRoots. Ścieżka jest skanowana pod kątem definicji zarówno block.json, jak i field.json, dzięki czemu zewnętrzne tagi bloków i ich pola niestandardowe można walidować razem.

YAML
parameters:
  blockstudioScanRoots:
    - vendor/acme/block-library/blockstudio

Aby ignorować pliki, użyj standardowej konfiguracji excludePaths w PHPStan.

Gotowe ustawienia analizy

Automatycznie wykrywane rozszerzenie pozostaje podstawą zapewniającą zgodność. Blockstudio 7.6 dodaje warstwy włączane opcjonalnie, bez zmieniania istniejących projektów:

Gotowe ustawienie Działanie
base.neon Analiza istniejących schematów, szablonów, hooków, ustawień i API.
theme.neon Podstawa oraz WordPress katalogi główne motywów, nagłówki stylów, zasoby Blockstudio, zakres selektorów, wartości domyślne pól i limity elementów powtarzalnych.
extreme-theme.neon Motyw oraz PHPStan max, niebezpieczne PHP, escapowanie wyjścia, Tailwind, JavaScript i kontrole API Interactivity.
wordpress-render.neon Ekstremalny motyw oraz dostarczana przez wywołującego sonda renderowania na żywo WordPress.

Instalacja blockstudio/phpstan włącza tylko podstawowe rozszerzenie. Dodaj warstwę włączaną opcjonalnie do istniejącej konfiguracji PHPStan:

YAML
includes:
  - vendor/blockstudio/phpstan/extreme-theme.neon

parameters:
  blockstudioThemeRoots:
    - .
  blockstudioThemeExcludePaths:
    - fixtures/**
  blockstudioThemeMaxFiles: 10000
  blockstudioExtremeJavaScript: true
  blockstudioExtremeTailwind: true

blockstudioThemeExcludePaths steruje skanerem motywów. Standardowe excludePaths w PHPStan niezależnie steruje analizą PHP.

Ustawienie phpstan.excludePaths kanonicznego polecenia w blockstudio.json (i jego opcja --exclude) konfiguruje obie warstwy. Względne wzorce są rozpatrywane względem każdego skonfigurowanego katalogu głównego, więc wpisy takie jak vendor/** ograniczają analizę PHPStan, a także skanowanie projektu przez Blockstudio.

Wzorzec wskazujący pojedynczy katalog, taki jak _dist/** lub node_modules/**, wyklucza ten katalog w każdym miejscu, w którym występuje, a nie tylko obok katalogu głównego motywu. Wzorzec zawierający ukośnik, taki jak assets/*/docs/**, pozostaje zakotwiczony w katalogu głównym. Wygenerowane zasoby bloków znajdują się w katalogu _dist wewnątrz każdego bloku, dlatego forma wskazująca pojedynczy katalog pozwala wykluczyć skompilowane pliki z analizy.

Kanoniczne polecenie

Pakiet instaluje vendor/bin/blockstudio-phpstan jako plik wykonywalny do analizy. Uruchamia on ustawienie base, chyba że projekt wybierze inne, więc sama instalacja pakietu nie włącza warstw motywu ani ekstremalnego motywu:

Powłoka
vendor/bin/blockstudio-phpstan --root . -- --no-progress

Gotowe ustawienia same zawierają rozszerzenie. Nie dodawaj phpstan/extension-installer do projektu, w którym uruchamiasz kanoniczne polecenie: przy obecnym instalatorze extension.neon zostanie załadowane dwukrotnie, a PHPStan zakończy działanie komunikatem „This file is included multiple times” przed rozpoczęciem analizy.

Domyślnie polecenie ustawia dla PHPStan limit pamięci 1G, dzięki czemu projekty WordPress zarządzane przez Composer nie dziedziczą typowego limitu CLI 128M. Aby go zmienić, podaj jawną opcję PHPStan po --, na przykład -- --memory-limit=512M --no-progress.

Wdrożenie analizy w istniejącym projekcie

Projekt, który nigdy nie był analizowany, zwykle zgłasza problemy przy pierwszym uruchomieniu. Zamiast obniżać poziom gotowych ustawień, wygeneruj bazę PHPStan i wskaż w phpstan.configuration konfigurację projektu, która ją uwzględnia. Nowy kod podlega wtedy pełnym wymaganiom gotowych ustawień, a zapisane wcześniej problemy nie przeszkadzają:

Powłoka
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
Neon
includes:
    - phpstan-baseline.neon

parameters:
    level: max
JSON
{
  "phpstan": {
    "configuration": "phpstan.neon"
  }
}

Zachowaj wiersz level dla ustawień base i theme. Kanoniczne polecenie ustawia dla nich poziom max tylko wtedy, gdy nie dołączono konfiguracji projektu; bez poziomu PHPStan kończy działanie komunikatem „No rules detected”. Ustawienie extreme-theme samo ustawia poziom max.

Ścieżki względne są rozpatrywane względem blockstudio.json. Kanoniczne polecenie i zarządzany hook zatwierdzania zmian uwzględniają ten plik, więc hook blokuje nowe problemy bez konieczności wcześniejszego usunięcia zaległości.

Domyślne wartości poleceń dla całego projektu umieszczaj w blockstudio.json:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "phpstan": {
    "preset": "extreme-theme",
    "roots": ["."],
    "excludePaths": ["fixtures/**"],
    "maxFiles": 10000
  }
}

Względne katalogi główne są rozpatrywane względem pliku, w którym je zadeklarowano. Jawne wartości CLI zastępują odpowiadające im wartości JSON. Podaj --blockstudio-json path/to/project.json, aby wskazać inne źródło konfiguracji. Błędne JSON, nieobsługiwane klucze phpstan, nieprawidłowe wartości i brak jawnego źródła powodują deterministyczny błąd z kodem wyjścia 2.

Wybierz inne gotowe ustawienie, dołącz konfigurację projektu, dodaj powtarzalne katalogi główne i wykluczenia albo poproś PHPStan o JSON:

Powłoka
vendor/bin/blockstudio-phpstan \
  --preset theme \
  --configuration phpstan.neon \
  --root . \
  --exclude 'fixtures/**' \
  --max-files 10000 \
  --error-format json \
  -- --no-progress

Wrapper tworzy połączoną konfigurację w systemowym katalogu tymczasowym i usuwa ją po zakończeniu. Nigdy nie zapisuje wygenerowanej konfiguracji, baz, hooków ani pamięci podręcznej w analizowanym projekcie. Wywołujący nadal mogą jawnie skonfigurować standardową pamięć podręczną PHPStan.

Umowa dotycząca kodów wyjścia:

  • 0, gdy analiza przejdzie pomyślnie
  • 1, gdy PHPStan zgłosi komunikaty diagnostyczne
  • 2 w przypadku nieprawidłowego użycia, konfiguracji lub wykonania procesu

Zarządzany hook zatwierdzania

Aby analiza ekstremalnego motywu blokowała zatwierdzanie zmian w repozytorium, włącz hook zarządzany przez Blockstudio w blockstudio.json:

JSON
{
  "$schema": "https://blockstudio.dev/schema/blockstudio",
  "phpstan": {
    "preset": "extreme-theme",
    "roots": ["."],
    "excludePaths": [],
    "maxFiles": 10000
  },
  "githooks": {
    "commit": true
  }
}

Zsynchronizuj ustawienie po zainstalowaniu zależności lub jego zmianie:

Powłoka
vendor/bin/blockstudio-githooks sync

Polecenie zapisuje wygenerowany hook pre-commit i rekord własności w katalogu wspólnym Git, ustawia core.hooksPath na katalog zarządzanego hooka i bezpiecznie łączy go z wcześniej skonfigurowanym hookiem pre-commit. Kolejne synchronizacje odświeżają tylko wygenerowany plik, dzięki czemu aktualizacje pakietu są idempotentne.

Ustaw commit na false, usuń to ustawienie albo usuń blockstudio.json, a następnie uruchom sync, aby przywrócić zapisaną ścieżkę hooka i usunąć tylko pliki zarządzane przez Blockstudio. Możesz też uruchomić:

Powłoka
vendor/bin/blockstudio-githooks remove

Pliki należące do użytkownika nigdy nie są nadpisywane ani usuwane. Jeśli ktoś zmieni core.hooksPath po włączeniu Blockstudio, usunięcie zachowa nowsze ustawienie. Wygenerowany hook obsługuje połączone kopie robocze Git i ścieżki zawierające spacje, ustalając aktywne repozytorium i katalog główny projektu w chwili zatwierdzania zmian. Uruchamia kanoniczne polecenie z tego katalogu głównego, więc ten sam obiekt phpstan steruje uruchomieniami interaktywnymi i zatwierdzaniem zmian bez powielania wygenerowanych argumentów.

Hook uruchamia wyłącznie vendor/bin/blockstudio-phpstan. Blockstudio nie uruchamia formatera, a hook nigdy nie przepisuje plików projektu. Brakujące zależności i błędy analizy blokują zatwierdzenie zmian, podając jasny komunikat o rozwiązaniu problemu.

Renderowanie na żywo WordPress

Warstwa renderowania na żywo wymaga jawnej konfiguracji. Wywołujący odpowiada za środowisko WordPress i przekazuje tablicę argv:

Powłoka
vendor/bin/blockstudio-phpstan \
  --preset wordpress-render \
  --render-command='["wp","eval-file","tools/render-probe.php"]' \
  --render-working-directory=. \
  --render-timeout=60 \
  --root .

Polecenie uruchamia się bez powłoki i musi wypisać jeden obiekt JSON:

JSON
{"ok":true}

Sonda może zgłosić konkretny błąd:

JSON
{
  "ok": false,
  "message": "Rendered block failed.",
  "file": "/absolute/path/to/block.json",
  "line": 12
}

Niezerowy kod wyjścia, przekroczenie limitu czasu, nieprawidłowe JSON i ok: false powodują blockstudio.wordpress.render.

blockstudio.javascript.domContract zgłasza selektor atrybutu [data-*], który skrypt przekazuje do querySelector(), querySelectorAll(), closest() lub matches(), gdy żaden analizowany znacznik nie ma tego atrybutu. Znaczniki obejmują wszystkie pliki PHP, Twig, Blade i HTML, a także wszystkie komponenty React .tsx i .jsx w analizowanych katalogach, z pominięciem wykluczonych ścieżek. Komponenty są parsowane: liczą się nazwy atrybutów JSX, podobnie jak klucze tekstowe obiektów literałowych, więc obiekt atrybutów rozłożony na elemencie spełnia warunek selektora, natomiast nazwy klas i inne wartości atrybutów nie.

Kontrole Interactivity API odczytują te same komponenty React. Przestrzeń nazw data-wp-interactive na elemencie JSX jest traktowana jako odwołanie do szablonu dla blockstudio.interactivity.orphan, a dyrektywy data-wp-* w jego obrębie są rozstrzygane względem najbliższej otaczającej przestrzeni nazw lub prefiksu namespace:: w wartości. Dyrektywy ze statyczną wartością tekstową, zapisane jako atrybut JSX lub klucz tekstowy obiektu atrybutów, muszą wskazywać istniejące procedury obsługi i ścieżki w magazynie (blockstudio.interactivity.handler, blockstudio.interactivity.binding), a kod magazynu nie może modyfikować atrybutów ani klas, z którymi jest powiązany (blockstudio.interactivity.derivedState). React escapuje wartości atrybutów, więc data-wp-context w komponencie nie jest zgłaszane, a wartości dynamiczne nie są sprawdzane. Przestrzenie nazw w bsui/ należą do dołączonych bloków UI, których magazyny są dostarczane z Blockstudio poza analizowanymi katalogami, więc nigdy nie są osierocone.

Identyfikatory diagnostyczne

Diagnostyka nowych gotowych ustawień zachowuje stabilne identyfikatory blockstudio.*:

  • Struktura motywu: blockstudio.theme.root.missing, blockstudio.theme.style.missing, blockstudio.theme.style.header, blockstudio.theme.scanLimit
  • Zasoby i pola: blockstudio.theme.asset.manualEnqueue, blockstudio.theme.asset.selectorScope, blockstudio.theme.asset.missing, blockstudio.field.default, blockstudio.field.repeaterBounds
  • PHP: blockstudio.php.forbiddenFunction, blockstudio.wordpress.rawDatabaseWrite, blockstudio.output.unescaped
  • Tailwind: blockstudio.tailwind.compilerMissing, blockstudio.tailwind.compile, blockstudio.tailwind.unknownUtility, blockstudio.tailwind.semanticToken
  • JavaScript: blockstudio.javascript.syntax, blockstudio.javascript.debugOutput, blockstudio.javascript.bannedApi, blockstudio.javascript.leakedGlobal, blockstudio.javascript.importSpecifier, blockstudio.javascript.rootGuard, blockstudio.javascript.initShape, blockstudio.javascript.domContract, blockstudio.javascript.listenerCleanup, blockstudio.javascript.reducedMotion
  • Interaktywność: blockstudio.interactivity.import, blockstudio.interactivity.moduleImport, blockstudio.interactivity.namespace, blockstudio.interactivity.scopedDom, blockstudio.interactivity.derivedState, blockstudio.interactivity.handler, blockstudio.interactivity.binding, blockstudio.interactivity.context, blockstudio.interactivity.orphan

Wydajność

Skaner obsługuje zwykłe, zmaterializowane katalogi, usuwa powtórzenia katalogów głównych, pomija drzewa zależności, kompilacji i pamięci podręcznej, przechowuje odczyty plików w pamięci i sortuje diagnostykę w deterministyczny sposób. Ogranicz zakres katalogów głównych, wyklucz drzewa z danymi testowymi i wygenerowanymi oraz ustaw limit plików dla dużych repozytoriów. JavaScript i Tailwind można wyłączać niezależnie. Renderowanie na żywo nigdy nie jest uruchamiane, chyba że wybrano odpowiednie gotowe ustawienie.

Diagnostyka motywu, JavaScript i Tailwind jest raportowana przez pamięć podręczną wyników PHPStan. Po zmianie wyłącznie pliku block.json lub skryptu ciepła pamięć podręczna może zwrócić poprzedni wynik. Aby pominąć pamięć podręczną przy weryfikowaniu takich zmian, podaj --debug po --.

Umowa projektu dla agentów programistycznych

Pakiet instaluje trzeci plik wykonywalny, vendor/bin/blockstudio-agents. Zapisuje on AGENTS.md opisujący projekt, w którym jest uruchamiany — informacje potrzebne agentowi programistycznemu, zanim cokolwiek zmieni: co tworzą autorzy projektu, które funkcje Blockstudio są włączone, co odrzuci analiza i jakie polecenia mają zastosowanie.

Powłoka
vendor/bin/blockstudio-agents
Text
Blockstudio contract created: /path/to/project/AGENTS.md

Żaden element danych wyjściowych nie pochodzi ze stałego szablonu. Każdy wiersz jest oparty na jednym z trzech źródeł:

  • Własne pliki projektu. Motyw z nagłówkiem style.css, blokami i stronami opartymi na plikach tworzy inny dokument niż wtyczka rejestrująca wyłącznie bloki. Liczby, katalogi, przestrzenie nazw bloków i języki szablonów to elementy faktycznie znalezione przez skaner, przy użyciu tych samych katalogów głównych i wykluczeń co podczas analizy.
  • blockstudio.json. Opisywane są tylko włączone funkcje, wraz ze skonfigurowanymi wartościami: prefiksy tagów bloków i przestrzenie nazw, według których są rozpoznawane, Tailwind, dołączone UI, reset zasobów edytora, ścieżka pamięci podręcznej, profil wydajności, statyczne wstępne renderowanie i jego dynamiczne ścieżki, wartości domyślne motywu, Content Sync oraz hook zatwierdzania zmian.
  • Wybrane phpstan.preset. Sekcja dotycząca poprawności jest odczytywana bezpośrednio z plików gotowych ustawień, warstwa po warstwie, dlatego zawiera dokładnie te reguły, które rejestruje dane ustawienie. Dla base opisuje reguły schematów, szablonów, hooków i ustawień. Dla extreme-theme opisuje również reguły struktury motywu, rygorystyczne flagi PHPStan, niebezpieczne PHP, escapowanie wyjścia, Tailwind i JavaScript. Gdy do gotowych ustawień zostanie dodana reguła, zmieni się także wygenerowany dokument.

Sekcja poleceń działa według tej samej zasady. wp bs prerender status pojawia się po włączeniu statycznego wstępnego renderowania, vendor/bin/blockstudio-githooks sync, gdy ustawiono githooks.commit, a wp bs db schemas, gdy projekt faktycznie zawiera db.php.

Opcja Działanie
--root <path> Katalog główny projektu (domyślnie: bieżący katalog)
--config <path> Ścieżka blockstudio.json (domyślnie: <root>/blockstudio.json)
--output <path> Ścieżka umowy (domyślnie: <root>/AGENTS.md)
--stdout Wypisuje umowę zamiast zapisywać ją do pliku
--check Kończy działanie z kodem 1, jeśli umowa na dysku jest nieaktualna
--force Zastępuje plik, do którego Blockstudio nie ma praw

--check sprawia, że umowa staje się kontrolą CI, podobnie jak hook zatwierdzania zmian sprawia, że kontrolą staje się analiza:

Powłoka
vendor/bin/blockstudio-agents --check

Własność pliku

Wygenerowany plik zawiera ten sam rodzaj znacznika co zarządzany hook zatwierdzania zmian i obowiązuje ta sama zasada: Blockstudio nigdy nie zastępuje pliku, którego nie utworzył. Jeśli plik AGENTS.md istniał przed uruchomieniem polecenia albo został ręcznie utworzony przez autora, polecenie odmówi działania z kodem wyjścia 2 i pozostawi go bez zmian, dopóki nie zostanie podane --force.

Ponowne generowanie jest bezpieczne. Plik kończy się sekcją notatek, a bajty między jej znacznikami są zachowywane przy każdym ponownym generowaniu:

Markdown
## Project notes

<!-- blockstudio:notes:start -->
Deploys run from the release branch only.
<!-- blockstudio:notes:end -->

Kody wyjścia to 0, gdy umowa zostanie zapisana, jest aktualna lub zostanie wypisana, 1, gdy --check wykryje nieaktualną umowę, oraz 2 w przypadku błędów użycia, konfiguracji lub systemu plików.

Kształty typów pól

Rozszerzenie mapuje każdy typ pola Blockstudio na konkretny typ PHP:

Typ pola Typ PHP
text, textarea, richtext, wysiwyg, code string
date, datetime, classes, html-tag, unit, gradient string
number, range int|float
toggle bool
select, radio, checkbox (pojedynczy) string|int
select, checkbox (wiele) list<string|int>
color array{value: string, opacity: float|null}
link array{url: string, title: string|null, target: string|null, opensInNewTab: bool|null}
icon array{set: string, subSet: string, icon: string}
files (pojedynczy) array{id: int, url: string, alt: string|null, mime_type: string|null}
files (wiele) list<array{id: int, url: string, ...}>
group Nazwane grupy używają prefiksów z podkreśleniem; grupy anonimowe są spłaszczane do zakresu nadrzędnego
repeater list<array{...child fields...}>
tabs Spłaszczane do zakresu nadrzędnego

Zaślepki API

Rozszerzenie zawiera zaślepki dla całego publicznego interfejsu API Blockstudio:

  • bs_render_block(), bs_block_values(), bs_get_group(), bs_get_scoped_class(), bs_db_form(), bs_is_editor(), bs_is_preview(), bs_is_buffering(), bs_strip_render_markers()
  • Db::get(), Db::create(), Db::list(), Db::get_record(), Db::update(), Db::delete()
  • Settings::get(), Settings::get_all()
  • Field_Registry::instance(), Field_Registry::all(), Field_Registry::get()
  • Build::blocks(), Build::extensions(), Build::get_build_dir()

Zapewniają autouzupełnianie i sprawdzanie typów bez konieczności posiadania lokalnie źródeł wtyczki Blockstudio.

Wymagania

  • PHP 8.2+
  • PHPStan 2.1.47+
  • phpstan/extension-installer (zalecane do automatycznego wykrywania)

Pakiet automatycznie instaluje dostawcę zgodności z BC Math. Natywne ext-bcmath jest więc opcjonalne, również w przypadku nowo wygenerowanych motywów, które włączają kontrole JavaScript za pomocą ustawienia motywu lub ekstremalnego motywu.