Lewati ke konten

PHPStan

Ekstensi blockstudio/phpstan menghadirkan analisis statis untuk proyek Blockstudio. Ekstensi ini memvalidasi templat blok, file skema, jalur pengaturan, dan nama hook saat analisis, sehingga bug terdeteksi sebelum mencapai runtime.

Instalasi

Shell
composer require --dev blockstudio/phpstan

Pemeriksaan pengetikan templat dan tag blok yang diperluas pada 7.7 memerlukan blockstudio/phpstan 0.1.9 atau yang lebih baru serta PHPStan 2.1.47 atau yang lebih baru. Perbarui paket ini secara terpisah dari plugin:

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

Ekstensi ini ditemukan secara otomatis melalui penginstal ekstensi milik PHPStan. Tidak perlu konfigurasi manual.

Yang diperiksa

Akses field templat

Jika file PHP berada di samping block.json, ekstensi ini memvalidasi setiap akses $a['key'] berdasarkan atribut yang dideklarasikan untuk blok tersebut.

PHP
<?php

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

Ekstensi ini mengetahui bahwa Blockstudio mendefinisikan $a, $attributes, $b, $block, $c, $context, $content, $isEditor, $isPreview, serta variabel island sebelum menyertakan templat, sehingga pembacaan langsung seperti $a['title'] tidak dilaporkan sebagai kemungkinan belum terdefinisi, dan tipe $a ditentukan dari block.json di samping templat. Bentuk ini tetap dipertahankan saat penyempitan tipe, sehingga $a['label'] ?? '', isset( $a['cta']['target'] ), dan $a['cta']['title'] !== null mempertahankan tipe field yang dideklarasikan; templat yang menetapkan $a sendiri akan mempertahankan tipe yang ditetapkannya. Jangan tambahkan docblock /** @var array<string, mixed> $a */: docblock tersebut mengganti bentuk itu dengan larik terbuka.

Kunci field mengikuti aturan perataan runtime milik Blockstudio. Kontainer tabs dan group anonim tanpa id hanya untuk presentasi, sehingga field anaknya tetap berada dalam cakupan induk. Grup bernama menambahkan ID grup sebagai prefiks pada kunci anaknya:

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

Field khusus yang dapat digunakan kembali

Referensi custom/* berbasis file diperluas sebelum kunci templat dan bentuk larik diperiksa. Ekstensi ini membaca field.json yang cocok dan menerapkan aturan idStructure, overrides, referensi bertingkat, grup, tab, dan repeater yang sama seperti 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" }
        }
      }
    ]
  }
}

Kunci templat yang dihasilkan adalah title dan hero_description. Kunci ini dikenali dalam PHP, Twig, Blade, tag blok, dan bentuk atribut yang disimpulkan.

Definisi berbasis file yang hilang, ambigu, tidak valid, atau siklik menghasilkan error blockstudio.customField.* tertentu. Pemeriksaan kunci yang bergantung padanya dilewati untuk blok tersebut agar satu definisi yang belum terselesaikan tidak memicu rentetan error field tak dikenal.

Definisi yang hanya didaftarkan saat runtime melalui filter blockstudio/fields PHP tidak dapat disimpulkan oleh analisis statis. Gunakan definisi field.json jika field tersebut harus menyumbangkan kunci templat yang diperiksa secara statis.

Akses templat Twig

Templat Twig dipindai secara otomatis. Tidak perlu anotasi.

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

Akses templat Blade

Templat Blade dipindai dengan cara yang sama.

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

Validasi tag blok

Tag blok divalidasi di tempat Blockstudio membacanya: tag <bs:> dan <block>, tag prefiks yang dikonfigurasi di blockTags.prefixes (seperti <acme-card>, yang diselesaikan menurut urutan namespace seperti saat runtime), serta tag alias, dalam templat blok PHP, Twig, dan Blade serta tata letak halaman. Sumber halaman di bawah pages/ (index.php, index.html, index.twig, index.blade.php) juga diperiksa, termasuk elemen HTML yang dipetakan proyek ke blok. Blok UI yang disertakan dalam paket akan dikenali jika ui.enabled aktif.

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 diterima jika blok mendeklarasikannya sebagai field (termasuk field khusus dan field yang diteruskan oleh field bertipe blok melalui idStructure-nya), atau jika Blockstudio meneruskannya ke elemen akar blok: data-*, aria-*, id, style, role, title, lang, dir, hidden, dan tabindex. Dalam templat, setiap atribut html-* diteruskan; dalam sumber halaman, prefiks html- hanya menyebut salah satu atribut yang diteruskan. Selain itu, semua atribut lain dilaporkan, terutama class yang tidak dideklarasikan, karena Blockstudio menyimpannya dan tidak pernah merendernya.

Runtime mendaftarkan pemetaan elemen dan alias tag dalam filter PHP yang tidak dapat dievaluasi oleh analisis statis, sehingga analisis membacanya dari blockstudio.json. scanPhp juga memeriksa tag di PHP proyek lainnya, seperti markup komponen dalam modul, tanpa melaporkan blok tak dikenal di sana:

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

Elemen dipetakan ke nama blok atau ke serangkaian aturan yang dicoba berurutan: aturan pertama yang atributnya dimiliki elemen akan digunakan, dan nama blok biasa selalu cocok. Elemen yang tidak dipetakan oleh proyek tetap menggunakan blok intinya dan tidak diperiksa. Diagnostik menggunakan blockstudio.blockTag.unknown, blockstudio.blockTag.attribute, dan blockstudio.blockTag.class.

Pengetikan rekaman basis data

Db::get() mengembalikan instans bertipe berdasarkan skema db.php. Bentuk rekaman disimpulkan secara otomatis.

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

Field wajib tidak dapat bernilai null. Field opsional adalah type|null. Field id (int) selalu tersedia. Pengetikan yang sama berlaku untuk sintaks builder Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field bawaan PHP.

Validasi jalur pengaturan

Jalur Settings::get() diperiksa berdasarkan skema pengaturan yang diketahui.

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

Validasi nama hook

Nama hook filter dan tindakan Blockstudio divalidasi.

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

Hook pengaturan dinamis seperti blockstudio/settings/tailwind/enabled selalu diizinkan. Hook non-blockstudio diabaikan.

Validasi skema

Ekstensi ini memvalidasi setiap file skema Blockstudio dalam proyek.

block.json:

  • Field name tidak ada
  • Field type tidak ada
  • id tidak ada pada field nilai yang memerlukannya
  • Jenis field tidak dikenal
  • Properti field yang tidak diterima oleh jenis field tersebut, seperti "translat" alih-alih "translate", dengan properti yang paling mendekati dan dikenal sebagai saran
  • select/radio/checkbox tanpa options atau populate
  • ID field duplikat
  • Field tabs di dalam repeater, secara langsung atau di dalam grup tanpa id
  • Deklarasi pluginDependencies tidak valid

Field kontainer seperti group dan tabs, serta referensi field custom/*, dapat menghilangkan id jika hanya memperluas atau membungkus field lain.

Properti field diperiksa berdasarkan properti yang schemas/block.json deklarasikan untuk setiap jenis field bawaan, ditambah properti yang diterima semua field. Properti khusus wrapper pada referensi custom/* dan jenis field bernamespace yang ditentukan proyek tidak termasuk dalam pemeriksaan ini. Validasi jenis field yang ada dan referensi kustom tetap berlaku. Identifier-nya adalah blockstudio.blockJson.property dan blockstudio.fieldJson.property.

Pemeriksaan ini mencakup nama properti, bukan hanya nilainya: minimized valid pada repeater, tetapi dilaporkan pada field teks. Perilaku plugin saat runtime tidak berubah. Jika proyek sengaja menambahkan metadatanya sendiri ke field bawaan, abaikan hanya temuan ini tanpa menonaktifkan pemeriksaan bentuk lainnya:

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

Field bawaan di dalam field.json yang dapat digunakan kembali tetap diperiksa, meskipun referensi custom/* memiliki opsi wrapper sendiri. File ekstensi berada di luar cakupan diagnostik nama properti ini; aturan set khusus ekstensi tetap berlaku.

field.json (field khusus yang dapat digunakan kembali):

  • name tidak ada
  • attributes tidak ada atau kosong
  • Objek atribut tidak valid atau type field tidak ada
  • id tidak ada pada field nilai yang memerlukannya
  • Jenis field tidak dikenal
  • Properti yang tidak diterima oleh jenis field tersebut
  • Field tabs di dalam repeater, secara langsung atau di dalam grup tanpa id
  • Referensi custom/* bertingkat tidak ada, ambigu, tidak valid, atau bersiklus

Ekstensi JSON (ekstensi blok dalam extensions/):

  • name (blok target) tidak ada
  • Kunci blockstudio tidak ada
  • Kunci blockstudio.extend tidak ada

page.json (halaman berbasis file):

  • title tidak ada
  • slug tidak ada
  • Nilai postStatus tidak valid

db.php:

  • Larik fields tidak ada
  • Tipe field tidak valid
  • Mendukung larik lama serta Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field

rpc.php:

  • Metode HTTP tidak valid
  • Nilai public salah (harus berupa true, false, atau 'open')
  • Mendukung larik lama serta nilai balik objek beratribut

cron.php:

  • schedule tidak ada pada tugas yang dikonfigurasi
  • callback tidak ada pada tugas yang dikonfigurasi
  • Mendukung array lama dan hasil objek beratribut

blockstudio.json:

  • Boolean singkat seperti "tailwind": true (harus menggunakan format objek bertingkat {"enabled": true, "config": ""})

Konfigurasi

Secara default, ekstensi menemukan file Blockstudio di proyek yang dianalisis. Jika proyek menggunakan blok atau bidang yang dapat digunakan kembali dari pustaka di luar akar proyek, tambahkan jalur pustaka ke blockstudioScanRoots. Jalur tersebut dipindai untuk definisi block.json dan field.json, sehingga tag blok eksternal dan bidang kustomnya dapat divalidasi bersama.

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

Untuk mengabaikan file, gunakan konfigurasi standar excludePaths milik PHPStan.

Preset analisis

Ekstensi yang ditemukan secara otomatis tetap menjadi dasar yang aman untuk kompatibilitas. Blockstudio 7.6 menambahkan lapisan opsional tanpa mengubah proyek yang sudah ada:

Preset Perilaku
base.neon Analisis skema, templat, hook, pengaturan, dan API yang sudah ada.
theme.neon Dasar ditambah akar tema WordPress, header gaya, aset Blockstudio, pembatasan cakupan pemilih, nilai default bidang, dan batas repeater.
extreme-theme.neon Tema ditambah PHPStan max, PHP yang tidak aman, escaping output, Tailwind, JavaScript, dan pemeriksaan Interactivity API.
wordpress-render.neon Tema ekstrem ditambah probe render WordPress langsung yang disediakan pemanggil.

Menginstal blockstudio/phpstan hanya mengaktifkan ekstensi dasar. Sertakan lapisan opsional dalam konfigurasi PHPStan yang sudah ada:

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

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

blockstudioThemeExcludePaths mengontrol pemindai tema. Konfigurasi standar excludePaths milik PHPStan secara terpisah mengontrol analisis PHP.

Pengaturan phpstan.excludePaths pada perintah kanonis di blockstudio.json (dan opsi --exclude-nya) mengonfigurasi kedua lapisan. Pola relatif diselesaikan terhadap setiap akar yang dikonfigurasi, sehingga entri seperti vendor/** membatasi analisis PHPStan sekaligus pemindaian proyek milik Blockstudio.

Pola yang menyebut satu direktori, seperti _dist/** atau node_modules/**, mengecualikan direktori tersebut di mana pun berada, bukan hanya di sebelah akar tema. Pola yang berisi garis miring, seperti assets/*/docs/**, tetap berpatokan pada akar. Aset blok yang dihasilkan berada dalam direktori _dist di dalam setiap blok, sehingga bentuk direktori tunggal digunakan untuk mencegah keluaran terkompilasi ikut dianalisis.

Perintah kanonis

Paket memasang vendor/bin/blockstudio-phpstan sebagai executable analisisnya. Perintah ini menjalankan preset base kecuali proyek memilih preset lain, sehingga menginstal paket tidak dengan sendirinya mengaktifkan lapisan tema atau tema ekstrem:

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

Preset sudah menyertakan ekstensi. Jangan tambahkan phpstan/extension-installer ke proyek yang menjalankan perintah kanonis: dengan penginstal terpasang, extension.neon dimuat dua kali dan PHPStan berhenti dengan pesan “This file is included multiple times” sebelum menganalisis apa pun.

Secara default, perintah menetapkan PHPStan ke batas memori 1G agar proyek WordPress yang dikelola oleh Composer tidak mewarisi batas CLI 128M yang umum. Berikan opsi PHPStan secara eksplisit setelah -- untuk menggantinya, misalnya -- --memory-limit=512M --no-progress.

Menerapkan analisis pada proyek yang sudah ada

Proyek yang belum pernah dianalisis biasanya akan melaporkan temuan pada proses pertama. Alih-alih menurunkan preset, buat baseline PHPStan dan arahkan phpstan.configuration ke konfigurasi proyek yang menyertakannya. Kode baru kemudian harus memenuhi preset penuh, sementara temuan yang tercatat tidak mengganggu:

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

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

Pertahankan baris level untuk preset base dan theme. Perintah kanonis hanya menetapkan level max untuk keduanya jika tidak ada konfigurasi proyek, dan tanpa level PHPStan perintah berhenti dengan “No rules detected”. Preset extreme-theme menetapkan level max sendiri.

Jalur relatif dihitung dari blockstudio.json. Perintah kanonis dan hook commit yang dikelola sama-sama mengambil file ini, sehingga hook mencegah temuan baru tanpa mengharuskan seluruh tunggakan dibereskan terlebih dahulu.

Simpan default perintah untuk seluruh proyek di blockstudio.json:

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

Akar relatif dihitung dari file yang mendeklarasikannya. Nilai CLI yang ditentukan secara eksplisit menggantikan nilai JSON yang sesuai. Berikan --blockstudio-json path/to/project.json untuk sumber konfigurasi alternatif. JSON yang salah format, kunci phpstan yang tidak didukung, nilai tidak valid, dan sumber eksplisit yang tidak ditemukan akan gagal secara deterministik dengan kode keluar 2.

Pilih preset lain, sertakan konfigurasi proyek, tambahkan akar dan pengecualian berulang, atau minta PHPStan untuk JSON:

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

Wrapper menyusun konfigurasi di direktori sementara sistem dan menghapusnya saat keluar. Wrapper tidak pernah menulis konfigurasi hasil generasi, baseline, hook, atau cache ke proyek yang dianalisis. Pemanggil tetap dapat mengonfigurasi cache normal milik PHPStan secara eksplisit.

Kontrak kode keluarnya adalah:

  • 0 jika analisis berhasil
  • 1 jika PHPStan melaporkan diagnostik
  • 2 untuk penggunaan, konfigurasi, atau eksekusi proses yang tidak valid

Hook commit terkelola

Untuk menjadikan analisis tema ekstrem sebagai gerbang commit repositori, aktifkan hook milik Blockstudio di blockstudio.json:

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

Sinkronkan setelah menginstal dependensi atau mengubah pengaturan:

Shell
vendor/bin/blockstudio-githooks sync

Perintah menulis hook pre-commit hasil generasi dan catatan kepemilikannya di dalam direktori umum Git, menetapkan core.hooksPath ke direktori hook yang dikelola, dan dengan aman merangkai hook pre-commit yang sebelumnya dikonfigurasi. Sinkronisasi berulang hanya memperbarui file hasil generasi, sehingga pemutakhiran paket bersifat idempoten.

Tetapkan commit ke false, hapus pengaturan itu, atau hapus blockstudio.json, lalu jalankan sync untuk memulihkan jalur hook yang tercatat dan hanya menghapus file milik Blockstudio. Anda juga dapat menjalankan:

Shell
vendor/bin/blockstudio-githooks remove

File milik pengguna tidak pernah ditimpa atau dihapus. Jika seseorang mengubah core.hooksPath setelah Blockstudio diaktifkan, pengaturan yang lebih baru itu akan dipertahankan saat penghapusan. Hook hasil generasi mendukung checkout Git tertaut dan jalur yang mengandung spasi dengan menentukan repositori aktif dan akar proyek saat commit. Hook menjalankan perintah kanonis dari akar tersebut, sehingga objek phpstan yang sama mengontrol proses interaktif dan commit tanpa argumen hasil generasi yang terduplikasi.

Hook hanya menjalankan vendor/bin/blockstudio-phpstan. Blockstudio tidak menjalankan pemformat kode, dan hook tidak pernah menulis ulang file proyek. Dependensi yang hilang dan kegagalan analisis akan memblokir commit dengan pesan kesalahan yang dapat ditindaklanjuti.

Render WordPress langsung

Lapisan langsung sengaja dibuat eksplisit. Pemanggil bertanggung jawab atas lingkungan WordPress dan menyediakan array argv:

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

Perintah berjalan tanpa shell dan harus mencetak satu objek JSON:

JSON
{"ok":true}

Probe dapat melaporkan kegagalan yang spesifik:

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

Keluar dengan kode bukan nol, waktu habis, JSON yang salah format, dan ok: false menghasilkan blockstudio.wordpress.render.

blockstudio.javascript.domContract melaporkan pemilih atribut [data-*] yang diteruskan skrip ke querySelector(), querySelectorAll(), closest(), atau matches() ketika tidak ada markup yang dianalisis yang memiliki atribut tersebut. Markup mencakup setiap file PHP, Twig, Blade, dan HTML serta setiap komponen React .tsx dan .jsx di dalam root yang dianalisis, dikurangi jalur yang dikecualikan. Komponen diurai: nama atribut JSX juga dihitung, begitu pula kunci string pada literal objek. Karena itu, objek atribut yang disebarkan ke elemen memenuhi pemilih, sedangkan nama class dan nilai atribut lainnya tidak.

Pemeriksaan Interactivity API membaca komponen React yang sama. Namespace data-wp-interactive pada elemen JSX dihitung sebagai referensi templat untuk blockstudio.interactivity.orphan, dan direktif data-wp-* di dalamnya ditautkan ke namespace terdekat yang melingkupinya, atau ke awalan namespace:: dalam nilainya. Direktif dengan nilai string statis, yang ditulis sebagai atribut JSX atau sebagai kunci string pada objek atribut, harus merujuk ke handler dan jalur store yang ada (blockstudio.interactivity.handler, blockstudio.interactivity.binding), dan kode store tidak boleh mengubah atribut serta class yang diikatnya (blockstudio.interactivity.derivedState). React melakukan escape pada nilai atribut, sehingga data-wp-context dalam komponen tidak dilaporkan, dan nilai dinamis tidak diperiksa. Namespace di bawah bsui/ termasuk dalam blok UI bawaan, yang store-nya disertakan bersama Blockstudio di luar root yang dianalisis sehingga tidak pernah menjadi orphan.

ID diagnostik

Diagnostik preset baru mempertahankan ID blockstudio.* yang stabil:

  • Struktur tema: blockstudio.theme.root.missing, blockstudio.theme.style.missing, blockstudio.theme.style.header, blockstudio.theme.scanLimit
  • Aset dan bidang: 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
  • Interaktivitas: 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

Performa

Pemindai menerima direktori biasa yang sudah tersedia, menghapus akar duplikat, melewati direktori dependensi/build/cache, menyimpan pembacaan file dalam memori, dan mengurutkan diagnostik secara deterministik. Gunakan akar yang sempit, kecualikan direktori fixture/hasil generasi, dan tetapkan batas jumlah file untuk repositori besar. JavaScript dan Tailwind dapat dinonaktifkan secara terpisah. Render langsung tidak berjalan kecuali presetnya dipilih.

Diagnostik tema, JavaScript, dan Tailwind dilaporkan melalui cache hasil milik PHPStan. Setelah hanya mengubah block.json atau skrip, cache hangat dapat melaporkan hasil sebelumnya. Berikan --debug setelah -- untuk melewati cache saat memverifikasi perubahan tersebut.

Kontrak proyek untuk agen coding

Paket memasang executable ketiga, vendor/bin/blockstudio-agents. Perintah ini menulis AGENTS.md yang menjelaskan proyek tempatnya dijalankan, yang dibutuhkan agen coding sebelum mengubah apa pun: apa yang dibuat proyek, fitur Blockstudio mana yang diaktifkan, apa yang akan ditolak oleh analisis, dan perintah yang berlaku.

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

Tidak ada bagian keluaran yang berupa templat tetap. Setiap baris berasal dari salah satu dari tiga sumber:

  • File milik proyek. Tema dengan header style.css, blok, dan halaman berbasis file menghasilkan dokumen yang berbeda dari plugin yang hanya mendaftarkan blok. Jumlah, direktori, namespace blok, dan bahasa templat mencerminkan temuan pemindai, dengan akar dan pengecualian yang sama seperti analisis.
  • blockstudio.json. Hanya fitur yang diaktifkan yang dijelaskan, beserta nilai konfigurasinya: prefiks tag blok dan namespace yang digunakan untuk mencarinya, Tailwind, UI yang disertakan, reset aset editor, jalur cache, profil performa, prerendering statis dan jalur dinamisnya, default tema, Content Sync, dan hook commit.
  • phpstan.preset yang dipilih. Bagian ketepatan dibaca langsung dari file preset, lapis demi lapis, sehingga hanya mencantumkan aturan yang didaftarkan preset tersebut. Pada base, bagian ini menjelaskan aturan skema, templat, hook, dan pengaturan. Pada extreme-theme, bagian ini juga menjelaskan aturan struktur tema, flag PHPStan yang ketat, PHP yang tidak aman, escaping output, Tailwind, dan JavaScript. Jika suatu preset mendapat aturan baru, dokumen yang dihasilkan juga akan berubah.

Bagian perintah mengikuti prinsip yang sama. wp bs prerender status muncul saat prerendering statis diaktifkan, vendor/bin/blockstudio-githooks sync saat githooks.commit ditetapkan, dan wp bs db schemas saat proyek benar-benar memiliki db.php.

Opsi Perilaku
--root <path> Akar proyek (default: direktori saat ini)
--config <path> Jalur blockstudio.json (default: <root>/blockstudio.json)
--output <path> Jalur kontrak (default: <root>/AGENTS.md)
--stdout Cetak kontrak alih-alih menulisnya
--check Keluar dengan 1 jika kontrak di disk sudah tidak mutakhir
--force Ganti file yang bukan milik Blockstudio

--check menjadikan kontrak sebagai gerbang CI, sama seperti hook commit menjadikan analisis sebagai gerbang:

Shell
vendor/bin/blockstudio-agents --check

Kepemilikan

File hasil generasi memiliki jenis penanda yang sama dengan hook commit yang dikelola, dan aturan yang sama berlaku: Blockstudio tidak pernah mengganti file yang tidak ditulisnya. File AGENTS.md yang sudah ada sebelum perintah ini, atau yang ditulis sendiri oleh penulis, akan ditolak dengan kode keluar 2 dan dibiarkan tanpa perubahan sampai --force diberikan.

Proses pembuatan ulang aman. File diakhiri dengan bagian catatan, dan byte di antara penandanya dipertahankan setiap kali dibuat ulang:

Markdown
## Project notes

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

Kode keluar adalah 0 saat kontrak ditulis, masih berlaku, atau dicetak, 1 saat --check menemukan kontrak yang sudah usang, dan 2 untuk kesalahan penggunaan, konfigurasi, atau sistem file.

Bentuk tipe bidang

Ekstensi memetakan setiap tipe bidang Blockstudio ke tipe konkret PHP:

Jenis field Jenis PHP
text, textarea, richtext, wysiwyg, code string
date, datetime, classes, html-tag, unit, gradient string
number, range int|float
toggle bool
select, radio, checkbox (tunggal) string|int
select, checkbox (jamak) 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 (tunggal) array{id: int, url: string, alt: string|null, mime_type: string|null}
files (jamak) list<array{id: int, url: string, ...}>
group Grup bernama menggunakan awalan garis bawah; grup anonim diratakan ke cakupan induk
repeater list<array{...child fields...}>
tabs Diratakan ke cakupan induk

Stub API

Ekstensi menyertakan stub untuk seluruh Blockstudio publik 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()

Stub ini menyediakan pelengkapan otomatis dan pemeriksaan tipe tanpa perlu sumber plugin Blockstudio di komputer Anda.

Persyaratan

  • PHP 8.2+
  • PHPStan 2.1.47+
  • phpstan/extension-installer (direkomendasikan untuk penemuan otomatis)

Paket memasang penyedia kompatibilitas BC Math secara otomatis. Karena itu, ext-bcmath native bersifat opsional, termasuk untuk tema baru hasil generasi yang mengaktifkan pemeriksaan JavaScript melalui preset tema atau tema ekstrem.