Preskoči na vsebino

PHPStan

Razširitev blockstudio/phpstan omogoča statično analizo projektov Blockstudio. Med analizo preverja predloge blokov, datoteke shem, poti nastavitev in imena hookov ter tako odkrije napake, preden se pojavijo med izvajanjem.

Namestitev

Lupina
composer require --dev blockstudio/phpstan

Za preverjanje tipov predlog in razširjene preglede oznak blokov v različici 7.7 potrebujete različico blockstudio/phpstan 0.1.9 ali novejšo ter PHPStan 2.1.47 ali novejšo. Paket posodobite ločeno od vtičnika:

Lupina
composer require --dev blockstudio/phpstan:^0.1.9

Razširitev samodejno zazna namestitveni program razširitev za PHPStan. Ročna konfiguracija ni potrebna.

Kaj preverja

Dostop do polj predloge

Ko je datoteka PHP poleg datoteke block.json, razširitev preveri vsak dostop $a['key'] glede na deklarirane atribute bloka.

PHP
<?php

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

Razširitev ve, da Blockstudio določa $a, $attributes, $b, $block, $c, $context, $content, $isEditor, $isPreview in spremenljivke otokov, še preden vključi predlogo, zato neposredni dostopi, kot je $a['title'], niso označeni kot morda nedefinirani, tip $a pa se določi iz block.json ob predlogi. Struktura se ohrani tudi po zožitvi tipa, zato $a['label'] ?? '', isset( $a['cta']['target'] ) in $a['cta']['title'] !== null ohranijo deklarirane tipe polj; predloga, ki sama dodeli vrednost $a, ohrani dodeljeni tip. Ne dodajajte docbloka /** @var array<string, mixed> $a */: ta strukturo nadomesti z odprto tabelo.

Ključi polj upoštevajo pravila izvajalnega okolja Blockstudio za sploščevanje. tabs in vsebniki group brez imena in brez id so namenjeni samo predstavitvi, zato njihova podrejena polja ostanejo v obsegu nadrejenega elementa. Imenovana skupina pred ključe svojih podrejenih polj doda ID skupine:

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

Ponovno uporabna polja po meri

Sklici na datoteke custom/* se razširijo pred preverjanjem ključev predlog in struktur tabel. Razširitev prebere ustrezni field.json in uporabi enaka pravila idStructure, overrides, ugnezdenih sklicev, skupin, zavihkov in ponavljalnikov kot 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" }
        }
      }
    ]
  }
}

Rezultantni ključi predloge so title in hero_description. Prepoznani so v PHP, Twig, Blade, oznakah blokov in izpeljanih strukturah atributov.

Manjkajoče, dvoumne, neveljavne ali ciklične definicije, vezane na datoteke, povzročijo posebno napako blockstudio.customField.*. Preverjanje odvisnih ključev za ta blok se preskoči, da ena nerazrešena definicija ne sproži dodatnega niza lažnih napak zaradi neznanih polj.

Definicij, registriranih samo med izvajanjem prek filtra blockstudio/fields PHP, statična analiza ne more izpeljati. Kadar mora polje prispevati ključe predloge, ki jih je mogoče statično preveriti, uporabite definicijo field.json.

Dostop do predloge Twig

Predloge Twig se pregledajo samodejno. Opomba ni potrebna.

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

Dostop do predloge Blade

Predloge Blade se pregledajo na enak način.

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

Preverjanje oznak blokov

Oznake blokov se preverijo na mestih, kjer jih bere Blockstudio: oznake <bs:> in <block>, oznake s predpono, nastavljeno v blockTags.prefixes (na primer <acme-card>, razrešeno po vrstnem redu imenskih prostorov kot med izvajanjem), ter oznake vzdevkov v predlogah blokov PHP, Twig in Blade ter v postavitvah strani. Preverjajo se tudi viri strani pod pages/ (index.php, index.html, index.twig, index.blade.php), vključno z elementi HTML, ki jih projekt preslika v bloke. Vgrajeni bloki UI so prepoznani, ko je ui.enabled vklopljen.

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) -->

Atribut je sprejet, če ga blok deklarira kot polje (vključno s polji po meri in polji, ki jih polje tipa bloka posreduje pod svojim idStructure) ali če ga Blockstudio posreduje korenskemu elementu bloka: data-*, aria-*, id, style, role, title, lang, dir, hidden in tabindex. V predlogah se posreduje vsak atribut html-*; v virih strani pa predpona html- poimenuje samo enega od posredovanih atributov. Vse drugo, zlasti nedeklariran class, je prijavljeno, ker ga Blockstudio shrani in nikoli ne izriše.

Izvajalno okolje registrira preslikave elementov in vzdevke oznak v filtrih PHP, ki jih statična analiza ne more ovrednotiti, zato jih analiza prebere iz blockstudio.json. scanPhp preverja tudi oznake v drugih projektnih datotekah PHP, kot je označevalni jezik komponent v modulih, ne da bi tam prijavljal neznane bloke:

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 se preslika v ime bloka ali v nabor pravil, ki se preverijo po vrsti: zmaga prvo pravilo, katerega atribut nosi element, navadno ime bloka pa se vedno ujema. Elementi, ki jih projekt ne preslika, ohranijo svoj osnovni blok in se ne preverjajo. Diagnostična sporočila uporabljajo blockstudio.blockTag.unknown, blockstudio.blockTag.attribute in blockstudio.blockTag.class.

Tipizacija zapisov zbirke podatkov

Db::get() vrne tipiziran primerek na podlagi sheme db.php. Strukture zapisov se izpeljejo samodejno.

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

Obvezna polja ne morejo biti null. Izbirna polja so type|null. Polje id (int) je vedno prisotno. Enako tipiziranje velja za sintakso graditelja Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field, izvorno za PHP.

Preverjanje poti nastavitev

Poti Settings::get() se preverijo glede na znano shemo nastavitev.

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

Preverjanje imen kavljev

Preverijo se imena filtrov Blockstudio in akcijskih hookov.

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

Dinamični hooki nastavitev, kot je blockstudio/settings/tailwind/enabled, so vedno dovoljeni. Hooki, ki niso del blockstudio, so prezrti.

Preverjanje shem

Razširitev preveri vse datoteke shem Blockstudio v projektu.

block.json:

  • Manjkajoče polje name
  • Manjkajoče polje type
  • Manjkajoči id pri vrednostnih poljih, ki ga zahtevajo
  • Neznane vrste polj
  • Lastnosti polja, ki jih njegova vrsta ne sprejema, na primer "translat" namesto "translate", s predlogom najbližje znane lastnosti
  • select/radio/checkbox brez options ali populate
  • Podvojeni ID-ji polj
  • Polje tabs znotraj ponavljalnika, neposredno ali v skupini brez id
  • Neveljavne deklaracije pluginDependencies

Vsebniška polja, kot sta group in tabs, ter sklici na polja custom/* lahko izpustijo id, če samo razširjajo ali ovijajo druga polja.

Lastnosti polj se preverjajo glede na lastnosti, ki jih schemas/block.json določa za vsako vgrajeno vrsto polja, in glede na lastnosti, ki jih sprejema vsako polje. Lastnosti, specifične za ovojne reference custom/*, in imenski tipi polj, določeni v projektu, niso vključeni v to preverjanje. Obstoječe preverjanje vrst polj in lastnih referenc še vedno velja. Identifikatorja sta blockstudio.blockJson.property in blockstudio.fieldJson.property.

To preverjanje zajema imena lastnosti, ne le njihovih vrednosti: minimized je veljavna pri ponavljalniku, pri besedilnem polju pa se zanjo izpiše opozorilo. Izvajanje vtičnika ostaja nespremenjeno. Če projekt namenoma dodaja lastne metapodatke vgrajenim poljem, onemogočite samo ta opozorila, ne da bi izklopili druga preverjanja oblike:

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

Vgrajena polja v vnovično uporabnem field.json se še vedno preverjajo, tudi če ima referenca custom/* lastne možnosti ovoja. Razširitvene datoteke ne spadajo v obseg te diagnostike imen lastnosti; pravila set, specifična za razširitve, še vedno veljajo.

field.json (polja po meri za večkratno uporabo):

  • Manjka name
  • Manjka attributes ali je prazno
  • Neveljavni objekti atributov ali manjka polje type
  • Manjka id pri vrednostnih poljih, ki ga zahtevajo
  • Neznane vrste polj
  • Lastnosti polja, ki jih ta vrsta polja ne sprejema
  • Polje tabs v ponavljalniku, neposredno ali v skupini brez id
  • Manjkajoče, dvoumne, neveljavne ali ciklične ugnezdene reference custom/*

Razširitev JSON (razširitve blokov v extensions/):

  • Manjka name (ciljni blok)
  • Manjka ključ blockstudio
  • Manjka ključ blockstudio.extend

page.json (strani na podlagi datotek):

  • Manjka title
  • Manjka slug
  • Neveljavne vrednosti postStatus

db.php:

  • Manjka polje fields
  • Neveljavne vrste polj
  • Podprte so starejše tabele ter Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field

rpc.php:

  • Neveljavne metode HTTP
  • Napačna vrednost public (mora biti true, false ali 'open')
  • Podprte so starejše tabele in vrnjeni objekti z atributi

cron.php:

  • Manjka schedule pri konfiguriranih opravilih
  • Manjka callback pri konfiguriranih opravilih
  • Podpira tako starejša polja kot vrnjene objekte z atributi

blockstudio.json:

  • Logične vrednosti v skrajšani obliki, kot je "tailwind": true (uporabiti morate ugnezdeno obliko objekta {"enabled": true, "config": ""})

Konfiguracija

Razširitev privzeto odkrije datoteke Blockstudio v analiziranem projektu. Če projekt uporablja bloke ali polja za večkratno uporabo iz knjižnice zunaj korenske mape projekta, dodajte pot do knjižnice v blockstudioScanRoots. Po poti se poiščejo definicije block.json in field.json, tako da je mogoče preveriti zunanje oznake blokov in njihova polja po meri.

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

Če želite prezreti datoteke, uporabite standardno konfiguracijo excludePaths za PHPStan.

Prednastavitve analize

Samodejno odkrita razširitev ostaja združljiva osnova. Blockstudio 7.6 dodaja izbirne plasti, ne da bi spreminjal obstoječe projekte:

Prednastavitev Delovanje
base.neon Analiza obstoječe sheme, predlog, kavljev, nastavitev in API.
theme.neon Osnova ter korenske mape teme WordPress, glave slogov, sredstva Blockstudio, omejevanje obsega izbirnikov, privzete vrednosti polj in omejitve ponavljalnikov.
extreme-theme.neon Tema ter PHPStan max, nevarni PHP, ubežanje izhoda, Tailwind, JavaScript in preverjanja Interactivity API.
wordpress-render.neon Skrajna tema ter preverjanje izrisa v živo WordPress, ki ga poda klicatelj.

Namestitev blockstudio/phpstan omogoči samo osnovno razširitev. V obstoječo konfiguracijo PHPStan vključite izbirno plast:

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

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

blockstudioThemeExcludePaths upravlja pregledovalnik tem. Standardna konfiguracija excludePaths za PHPStan neodvisno upravlja analizo PHP.

Nastavitev phpstan.excludePaths v blockstudio.json za kanonični ukaz (in njegova možnost --exclude) konfigurira obe plasti. Relativni vzorci se razrešijo glede na vsako konfigurirano korensko mapo, zato vnosi, kot je vendor/**, omejijo tako analizo PHPStan kot pregled projekta s strani Blockstudio.

Vzorec, ki poimenuje eno mapo, na primer _dist/** ali node_modules/**, izključi to mapo, kjer koli se pojavi, ne le ob korenski mapi teme. Vzorec s poševnico, kot je assets/*/docs/**, ostane vezan na korensko mapo. Ustvarjena sredstva blokov so v mapi _dist znotraj vsakega bloka, zato oblika z imenom ene mape poskrbi, da prevedeni izhod ni vključen v analizo.

Kanonični ukaz

Paket namesti vendor/bin/blockstudio-phpstan kot izvršno datoteko za analizo. Če projekt ne izbere druge, uporabi prednastavitev base, zato sama namestitev paketa ne omogoči plasti teme ali skrajne teme:

Lupina
vendor/bin/blockstudio-phpstan --root . -- --no-progress

Prednastavitve že vključujejo razširitev. Projektu, ki izvaja kanonični ukaz, ne dodajajte phpstan/extension-installer: če je prisoten namestitveni program, se extension.neon naloži dvakrat in PHPStan se ustavi z napako »This file is included multiple times«, še preden se začne analiza.

Ukaz privzeto nastavi omejitev pomnilnika PHPStan na 1G, da projekti WordPress, ki jih upravlja Composer, ne podedujejo običajne omejitve CLI za 128M. Če jo želite preglasiti, za -- podajte izrecno možnost PHPStan, na primer -- --memory-limit=512M --no-progress.

Uvajanje analize v obstoječem projektu

Prvi zagon projekta, ki še ni bil analiziran, običajno razkrije težave. Namesto da znižate raven prednastavitve, ustvarite osnovno datoteko PHPStan in poskrbite, da phpstan.configuration kaže na konfiguracijo projekta, ki jo vključuje. Za novo kodo nato velja celotna prednastavitev, zabeležene težave pa ne ovirajo dela:

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

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

Ohranite vrstico level za prednastavitvi base in theme. Kanonični ukaz jima nastavi raven max samo, če konfiguracija projekta ni vključena; brez ravni PHPStan se ustavi z napako »No rules detected«. Prednastavitev extreme-theme pa raven max nastavi sama.

Relativne poti se razrešijo glede na blockstudio.json. Kanonični ukaz in upravljani kavelj za potrditev sprememb oba zaznata datoteko, zato kavelj preverja nove ugotovitve, ne da bi bilo treba najprej odpraviti vse obstoječe.

Privzete nastavitve ukaza za celoten projekt hranite v blockstudio.json:

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

Relativne korenske mape se razrešijo glede na datoteko, v kateri so navedene. Izrecne vrednosti CLI nadomestijo ustrezne vrednosti JSON. Za drug vir konfiguracije podajte --blockstudio-json path/to/project.json. Napačno oblikovan JSON, nepodprti ključi phpstan, neveljavne vrednosti in manjkajoči izrecni vir povzročijo predvidljivo napako z izhodno kodo 2.

Izberite drugo prednastavitev, vključite konfiguracijo projekta, dodajte ponovljive korenske mape in izključitve ali pa prosite PHPStan za JSON:

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

Ovoj sestavi konfiguracijo v začasni sistemski mapi in jo ob izhodu izbriše. V analizirani projekt nikoli ne zapisuje ustvarjenih konfiguracij, osnovnih datotek, kavljev ali predpomnilnikov. Klicatelji lahko kljub temu izrecno konfigurirajo običajni predpomnilnik za PHPStan.

Dogovor o izhodnih kodah:

  • 0, ko je analiza uspešna
  • 1, ko PHPStan prijavi diagnostiko
  • 2 za neveljavno uporabo, konfiguracijo ali izvajanje procesa

Upravljan potrditveni kavelj

Če želite, da analiza skrajne teme postane pogoj za potrditev sprememb v repozitoriju, omogočite kavelj v lasti Blockstudio v blockstudio.json:

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

Po namestitvi odvisnosti ali spremembi nastavitve ga sinhronizirajte:

Lupina
vendor/bin/blockstudio-githooks sync

Ukaz zapiše ustvarjeni kavelj za predpotrditev in zapis o lastništvu v skupno mapo Git, nastavi core.hooksPath na mapo upravljanega kavlja in varno veriží predhodno konfigurirani kavelj za predpotrditev. Ponavljajoča se sinhronizacija osveži samo ustvarjeno datoteko, zato so nadgradnje paketa idempotentne.

Nastavite commit na false, odstranite ga ali odstranite blockstudio.json, nato za obnovitev zabeležene poti kavlja in brisanje samo datotek v lasti Blockstudio zaženite sync. Zaženete lahko tudi:

Lupina
vendor/bin/blockstudio-githooks remove

Datoteke v lasti uporabnika niso nikoli prepisane ali izbrisane. Če kdo spremeni core.hooksPath po tem, ko je bil omogočen Blockstudio, odstranitev ohrani novejšo nastavitev. Ustvarjeni kavelj podpira povezane delovne kopije Git in poti s presledki, saj ob času potrditve sprememb razreši aktivni repozitorij in korensko mapo projekta. Kanonični ukaz zažene iz te korenske mape, zato isti objekt phpstan upravlja tako interaktivne zagone kot potrditve sprememb, brez podvajanja ustvarjenih argumentov.

Kavelj zažene samo vendor/bin/blockstudio-phpstan. Blockstudio ne zažene oblikovalnika kode, kavelj pa nikoli ne prepisuje projektnih datotek. Manjkajoče odvisnosti in napake pri analizi preprečijo potrditev sprememb ter prikažejo jasno navodilo za odpravo težave.

Izris WordPress v živo

Plast za izris v živo je namenoma izrecna. Klicatelj upravlja okolje WordPress in poda polje argv:

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

Ukaz se izvede brez lupine in mora izpisati en objekt JSON:

JSON
{"ok":true}

Preizkus lahko sporoči natančno določeno napako:

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

Neuspešni zaključki, časovne omejitve, napačno oblikovan JSON in ok: false povzročijo blockstudio.wordpress.render.

blockstudio.javascript.domContract poroča o izbirniku atributa [data-*], ki ga skript posreduje funkciji querySelector(), querySelectorAll(), closest() ali matches(), kadar tak atribut ni prisoten v nobeni analizirani oznaki. Oznake so vse datoteke PHP, Twig, Blade in HTML ter vse komponente React .tsx in .jsx v analiziranih korenih, razen izključenih poti. Komponente se razčlenijo: upoštevajo se imena atributov JSX in tudi besedilni ključi objektnih literalov, zato objekt atributov, razširjen na element, izpolni pogoj izbirnika, imena razredov in druge vrednosti atributov pa ne.

Preverjanja Interactivity API berejo iste komponente React. Imenski prostor data-wp-interactive na elementu JSX šteje kot referenca na predlogo za blockstudio.interactivity.orphan, direktive data-wp-* v njem pa se razrešijo glede na najbližji nadrejeni imenski prostor ali predpono namespace:: v vrednosti. Direktive s statično besedilno vrednostjo, zapisane kot atribut JSX ali kot besedilni ključ objekta atributov, morajo poimenovati obstoječe upravljalnike in poti v shrambi (blockstudio.interactivity.handler, blockstudio.interactivity.binding), koda shrambe pa ne sme spreminjati atributov in razredov, na katere so vezane (blockstudio.interactivity.derivedState). React ubeži vrednosti atributov, zato data-wp-context v komponenti ni prijavljen, dinamične vrednosti pa se ne preverjajo. Imenski prostori pod bsui/ pripadajo priloženim blokom UI, katerih shrambe so vključene v Blockstudio zunaj analiziranih korenov, zato niso nikoli osirotele.

Diagnostični identifikatorji

Nova diagnostika prednastavitev ohranja stabilne ID-je blockstudio.*:

  • Struktura teme: blockstudio.theme.root.missing, blockstudio.theme.style.missing, blockstudio.theme.style.header, blockstudio.theme.scanLimit
  • Sredstva in polja: 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
  • Interaktivnost: 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

Zmogljivost

Pregledovalnik sprejema običajne materializirane mape, odstranjuje podvojene korenske mape, preskakuje drevesa odvisnosti, gradenj in predpomnilnika, predpomni branje datotek v pomnilniku ter deterministično razvršča diagnostiko. Korenske mape naj bodo ozke, izključite testne in ustvarjene datoteke ter za velike repozitorije nastavite omejitev števila datotek. JavaScript in Tailwind lahko izklopite neodvisno. Izris v živo se izvede le, če je izbrana ustrezna prednastavitev.

Diagnostika za teme, JavaScript in Tailwind se poroča prek predpomnilnika rezultatov za PHPStan. Če spremenite samo block.json ali skript, lahko ogreti predpomnilnik vrne prejšnji rezultat. Za obvoz predpomnilnika pri preverjanju takih sprememb za -- podajte --debug.

Pogodba projekta za agente za programiranje

Paket namesti še tretjo izvršno datoteko, vendor/bin/blockstudio-agents. Ta zapiše AGENTS.md, ki opisuje projekt, v katerem se izvaja, kar agent za programiranje potrebuje, preden se česa loti: kaj projekt ustvarja, katere funkcije Blockstudio so omogočene, kaj bo analiza zavrnila in kateri ukazi veljajo.

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

Nič v izhodu ni določeno s fiksno predlogo. Vsaka vrstica izhaja iz enega od treh virov:

  • Lastne datoteke projekta. Tema z glavo style.css, bloki in stranmi iz datotek ustvari drugačen dokument kot vtičnik, ki registrira samo bloke. Število elementov, imeniki, imenski prostori blokov in jeziki predlog so tisto, kar je pregledovalnik dejansko našel ob uporabi istih korenskih map in izključitev kot pri analizi.
  • blockstudio.json. Opisane so samo omogočene funkcije in njihove konfigurirane vrednosti: predpone oznak blokov in imenski prostori, v katerih se razrešijo, Tailwind, priloženi UI, ponastavitev sredstev urejevalnika, pot predpomnilnika, profil zmogljivosti, statično vnaprejšnje izrisovanje in njegove dinamične poti, privzete nastavitve teme, Content Sync in kavelj za potrditev sprememb.
  • Izbrana prednastavitev phpstan.preset. Razdelek o pravilnosti se bere neposredno iz datotek prednastavitev, plast za plastjo, zato natančno našteje pravila, ki jih prednastavitev registrira. Pri base opiše pravila za shemo, predloge, kavlje in nastavitve. Pri extreme-theme opiše tudi pravila za strukturo teme, stroge zastavice PHPStan, nevarni PHP, ubežanje izhoda, Tailwind in JavaScript. Če prednastavitev pridobi novo pravilo, se temu ustrezno spremeni tudi ustvarjeni dokument.

Razdelek z ukazi sledi istemu načelu. wp bs prerender status se pojavi, ko je omogočeno statično vnaprejšnje izrisovanje, vendor/bin/blockstudio-githooks sync, ko je nastavljeno githooks.commit, in wp bs db schemas, ko projekt dejansko vsebuje db.php.

Možnost Delovanje
--root <path> Korenska mapa projekta (privzeto: trenutna mapa)
--config <path> Pot do blockstudio.json (privzeto: <root>/blockstudio.json)
--output <path> Pot do pogodbe (privzeto: <root>/AGENTS.md)
--stdout Izpiše pogodbo namesto njenega zapisa
--check Izhod 1, če pogodba na disku ni aktualna
--force Zamenja datoteko, ki je Blockstudio nima v lasti

--check omogoča, da je pogodba pogoj v CI, enako kot kavelj za potrditev sprememb omogoča analizo:

Lupina
vendor/bin/blockstudio-agents --check

Lastništvo

Ustvarjena datoteka vsebuje enako vrsto označevalnika kot upravljani kavelj za potrditev sprememb in zanjo velja isto pravilo: Blockstudio nikoli ne zamenja datoteke, ki je ni ustvaril. Datoteko AGENTS.md, ki je obstajala že pred ukazom ali jo je avtor ustvaril ročno, zavrne z izhodno kodo 2 in je ne spreminja, dokler ne podate --force.

Ponovno ustvarjanje je varno. Datoteka se konča z območjem za opombe, bajti med njegovimi označevalniki pa se ohranijo pri vsakem ponovnem ustvarjanju:

Markdown
## Project notes

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

Izhodne kode so 0, ko je pogodba zapisana, aktualna ali izpisana; 1, ko --check zazna zastarelo pogodbo; in 2 za napake pri uporabi, konfiguraciji ali datotečnem sistemu.

Oblike tipov polj

Razširitev vsak tip polja Blockstudio preslika v konkreten tip PHP:

Vrsta polja Vrsta PHP
text, textarea, richtext, wysiwyg, code string
date, datetime, classes, html-tag, unit, gradient string
number, range int|float
toggle bool
select, radio, checkbox (ena vrednost) string|int
select, checkbox (več vrednosti) 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 (ena vrednost) array{id: int, url: string, alt: string|null, mime_type: string|null}
files (več vrednosti) list<array{id: int, url: string, ...}>
group Poimenovane skupine uporabljajo predpono podčrtaja; nepoimenovane skupine se sploščijo v nadrejeni obseg
repeater list<array{...child fields...}>
tabs Sploščeno v nadrejeni obseg

Začasne deklaracije API

Razširitev vključuje začasne deklaracije za celoten javni Blockstudio API:

  • 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()

Omogočajo samodokončanje in preverjanje tipov, ne da bi potrebovali izvorno kodo vtičnika Blockstudio na svojem računalniku.

Zahteve

  • PHP 8.2+
  • PHPStan 2.1.47+
  • phpstan/extension-installer (priporočeno za samodejno odkrivanje)

Paket samodejno namesti ponudnika združljivosti za BC Math. Izvorna ext-bcmath zato ni obvezna, niti pri novo ustvarjenih temah, ki prek prednastavitve teme ali skrajne prednastavitve omogočajo preverjanja JavaScript.