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
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:
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
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:
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:
{
"name": "mytheme/hero",
"attributes": [
{ "id": "heading", "type": "text" },
{ "id": "description", "type": "textarea" }
]
}
{
"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.
<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.
<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.
<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:
{
"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.
return [
'storage' => 'table',
'fields' => [
'email' => ['type' => 'string', 'required' => true],
'name' => ['type' => 'string'],
],
];
$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ń.
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.
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
idw 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/checkboxbezoptionslubpopulate- Zduplikowane identyfikatory pól
- Pole
tabswewnątrz pola powtarzalnego, bezpośrednio lub w grupie bezid - 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:
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
idw polach wartości, które go wymagają - Nieznane typy pól
- Właściwości pola, których dany typ pola nie akceptuje
- Pole
tabswewnątrz pola powtarzalnego, bezpośrednio lub w grupie bezid - 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,falselub'open') - Obsługiwane są zarówno starsze tablice, jak i zwracane obiekty z atrybutami
cron.php:
- Brak
schedulew skonfigurowanych zadaniach - Brak
callbackw 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.
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:
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:
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ą:
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
includes:
- phpstan-baseline.neon
parameters:
level: max
{
"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:
{
"$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:
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ślnie1, gdy PHPStan zgłosi komunikaty diagnostyczne2w 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:
{
"$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:
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ć:
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:
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:
{"ok":true}
Sonda może zgłosić konkretny błąd:
{
"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.
vendor/bin/blockstudio-agents
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. Dlabaseopisuje reguły schematów, szablonów, hooków i ustawień. Dlaextreme-themeopisuje 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:
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:
## 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.