Lewati ke konten

Templat Terperiksa dengan PHPStan dan AGENTS.md yang Dihasilkan

Sebuah blok Blockstudio terdiri dari dua file yang harus selaras. block.json mendeklarasikan field, dan templat membacanya sebagai $a['id']. Tidak ada yang menghentikan templat saat runtime untuk membaca kunci yang namanya telah diubah, tidak pernah dideklarasikan, atau salah eja. Hasilnya hanya berupa string kosong, dan kesalahan baru diketahui saat seseorang melihat judul kosong di halaman aktif. Hal yang sama berlaku untuk escape output: echo yang tidak di-escape berfungsi dengan baik sampai nilai field berisi markup.

Paket blockstudio/phpstan memindahkan kedua masalah ke tahap analisis. Paket ini membaca file block.json Anda, menentukan tipe $a dari file tersebut, dan melaporkan pembacaan templat yang tidak cocok. Preset opsionalnya menambahkan aturan struktur tema, escaping, serta pemeriksaan JavaScript dan Tailwind. Paket yang sama menyediakan dua alat pendamping: hook pre-commit terkelola yang menjalankan analisis, dan generator yang menulis AGENTS.md untuk menjelaskan proyek Anda kepada agen pemrograman.

Panduan ini membuat tema kecil, sengaja merusak salah satu templatnya, membaca output analisis, memperbaikinya, lalu menyiapkan gerbang commit dan kontrak agen.

Menyiapkan tema

Mulailah dengan folder tema yang memiliki header style.css, sebuah composer.json, dan satu blok:

Kode
acme/
├── blockstudio/
│   └── hero/
│       ├── block.json
│       └── index.php
├── blockstudio.json
├── composer.json
└── style.css
CSS
/*
Theme Name: Acme
*/

Instal paket sebagai dependensi pengembangan:

Shell
composer require --dev blockstudio/phpstan

Paket ini menarik PHPStan dan stub WordPress dari szepeviktor/phpstan-wordpress, dan memasang tiga executable di vendor/bin: blockstudio-phpstan, blockstudio-githooks, dan blockstudio-agents.

Selanjutnya, tentukan apa yang harus dijalankan dalam analisis. Default seluruh proyek berada dalam objek phpstan di blockstudio.json, sehingga proses interaktif, CI, dan hook commit semuanya membaca pengaturan yang sama:

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

extreme-theme adalah preset statis paling ketat dari ketiganya. Tabel di bawah menjelaskan tambahan tiap preset. excludePaths mengecualikan file milik Composer sendiri dari pemindaian Blockstudio dan analisis PHP.

Sengaja merusak templat

Blok hero mendeklarasikan satu field:

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "apiVersion": 3,
  "name": "acme/hero",
  "title": "Hero",
  "blockstudio": {
    "attributes": [
      { "id": "heading", "type": "text", "label": "Heading", "default": "" }
    ]
  }
}

Templat membaca field itu dengan benar, lalu membaca subtitle yang tidak pernah dideklarasikan oleh blok dan mengeluarkannya tanpa escaping:

PHP
<section useBlockProps>
  <h1><?php echo esc_html( $a['heading'] ); ?></h1>
  <p><?php echo $a['subtitle']; ?></p>
</section>

Di editor dan frontend, ini merender paragraf kosong tanpa kesalahan. Jalankan analisis sebagai gantinya:

Shell
vendor/bin/blockstudio-phpstan -- --no-progress
Text
 ------ -------------------------------------------------------------------
  Line   blockstudio/hero/index.php
 ------ -------------------------------------------------------------------
  2      Variable $a might not be defined.
         🪪  variable.undefined
  3      Dynamic Blockstudio attributes must be escaped before output.
         🪪  blockstudio.output.unescaped
  3      Field "subtitle" does not exist in block.json (block: acme/hero).
         🪪  blockstudio.field
  3      Offset 'subtitle' does not exist on array{heading: string}.
         🪪  offsetAccess.notFound
  3      Parameter #1 (mixed) of echo cannot be converted to string.
         🪪  echo.nonString
  3      Variable $a might not be defined.
         🪪  variable.undefined
 ------ -------------------------------------------------------------------

 [ERROR] Found 6 errors

Perintah berakhir dengan 1. Berikut diagnostik dari yang paling spesifik:

  • blockstudio.field adalah aturan templat. Aturan ini menemukan block.json di samping templat, mencocokkan field-nya, dan subtitle bukan salah satunya.
  • offsetAccess.notFound adalah PHPStan sendiri yang mencapai kesimpulan sama, karena ekstensi memberikan bentuk konkret $a berupa array{heading: string} yang diturunkan dari block.json. Setiap tipe field dipetakan ke tipe PHP: text adalah string, toggle adalah bool, repeater adalah larik berisi bentuk baris.
  • blockstudio.output.unescaped berasal dari lapisan extreme-theme. Nilai atribut yang dikeluarkan harus melewati fungsi escaping seperti esc_html(), esc_attr(), esc_url(), atau wp_kses_post().
  • echo.nonString mengikuti kunci yang tidak dikenal: offset yang tidak ada tidak memiliki tipe string untuk dikeluarkan.
  • variable.undefined muncul karena PHPStan melihat file templat, bukan fungsi render yang mendefinisikan $a sebelum menyertakannya. Bagian perbaikan membahasnya.

Perbaiki

Tentukan apakah subtitle adalah field sungguhan. Di sini ya, jadi deklarasikan dengan default karena lapisan tema mewajibkannya pada setiap field:

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "apiVersion": 3,
  "name": "acme/hero",
  "title": "Hero",
  "blockstudio": {
    "attributes": [
      { "id": "heading", "type": "text", "label": "Heading", "default": "" },
      { "id": "subtitle", "type": "textarea", "label": "Subtitle", "default": "" }
    ]
  }
}

Escape output, lalu deklarasikan $a dengan bentuk yang disimpulkan ekstensi:

PHP
<?php
/** @var array{heading: string, subtitle: string} $a */
?>
<section useBlockProps>
  <h1><?php echo esc_html( $a['heading'] ); ?></h1>
  <p><?php echo esc_html( $a['subtitle'] ); ?></p>
</section>
Shell
vendor/bin/blockstudio-phpstan -- --no-progress
Text
 [OK] No errors

Tulis anotasi dengan bentuk yang tepat. Perintah kanonis menjalankan PHPStan pada level max, yang menolak @var array<string, mixed> $a yang lebih longgar dengan varTag.nativeType (“PHPDoc tag @var dengan tipe array<string, mixed> bukan subtipe dari tipe native array{heading: string, subtitle: string}”). Pada 7.6, setiap field juga diperluas menjadi mixed, sehingga setiap pemanggilan esc_html() melaporkan argument.type. Pesan varTag.nativeType mencetak bentuk yang disimpulkan, jadi ini juga cara tercepat menemukan anotasi untuk disalin.

Blockstudio 7.7 menganggap $a didefinisikan di dalam templat blok, sehingga diagnostik variable.undefined hilang dan anotasi menjadi opsional. Pada 7.7, templat rusak di atas melaporkan empat kesalahan, bukan enam, dan templat yang diperbaiki lolos tanpa baris @var.

Memilih preset

Menginstal paket hanya mengaktifkan ekstensi dasar. Perintah kanonis menjalankan base kecuali proyek memilih preset lain, sehingga menambahkan dependensi tidak dengan sendirinya mengaktifkan lapisan yang lebih ketat.

Preset Tambahan
base Akses field templat di PHP, Twig, dan Blade, pemeriksaan tag blok, validasi skema untuk block.json, field.json, page.json, ekstensi JSON, db.php, rpc.php, dan jalur cron.php, Settings::get(), serta nama hook blockstudio/*.
theme Base ditambah root tema dan header style.css, aset yang dideklarasikan di block.json alih-alih dimasukkan ke antrean secara manual, cakupan %selector% di style.scss, default field, dan batas repeater.
extreme-theme Tema ditambah flag PHPStan yang ketat, pemanggilan shell dan eval() yang ditolak, penulisan $wpdb mentah, escaping output, Tailwind, JavaScript, dan pemeriksaan API Interactivity.
wordpress-render Tema ekstrem ditambah probe render langsung yang Anda sediakan sebagai perintah.

Jika konfigurasi proyek tidak disertakan, perintah kanonis juga menjalankan base dan theme pada level PHPStan max; extreme-theme mengatur max itu sendiri. Setiap diagnostik preset memiliki pengenal blockstudio.* yang stabil, tercantum dalam referensi PHPStan.

Lapisan tema dan ekstrem memeriksa file PHP. Jika sebuah field tidak memiliki default dan sebuah script.js mencatat ke konsol, perintah yang sama melaporkan:

Text
 ------ -----------------------------------------------------------
  Line   blockstudio/hero/block.json
 ------ -----------------------------------------------------------
  1      Blockstudio field "subtitle" must define a default value.
         🪪  blockstudio.field.default
 ------ -----------------------------------------------------------

 ------ ------------------------------------------------------------
  Line   blockstudio/hero/script.js
 ------ ------------------------------------------------------------
  2      Remove debug output "console.log" from shipped JavaScript.
         🪪  blockstudio.javascript.debugOutput
 ------ ------------------------------------------------------------

Pemeriksaan ini dilaporkan melalui cache hasil milik PHPStan. Setelah hanya mengedit block.json atau skrip, cache hangat dapat melaporkan [OK] No errors untuk keadaan lama. Berikan --debug setelah -- untuk melewati cache sebelum memercayai hasil hijau pada perubahan non-PHP:

Shell
vendor/bin/blockstudio-phpstan -- --no-progress --debug

Opsi perintah dan kode keluar

Nilai baris perintah menggantikan nilai blockstudio.json yang sesuai untuk satu kali proses. Penggantian berarti benar-benar mengganti: memberikan --exclude apa pun akan menghapus excludePaths yang dikonfigurasi, jadi ulangi vendor/** saat menambahkan satu:

Shell
vendor/bin/blockstudio-phpstan \
  --preset theme \
  --root . \
  --exclude 'vendor/**' \
  --exclude 'fixtures/**' \
  --error-format json \
  -- --no-progress
Text
{"totals":{"errors":0,"file_errors":0},"files":{},"errors":[]}

Semua yang muncul setelah -- diteruskan ke PHPStan. Pembungkus meningkatkan batas memori PHPStan menjadi 1G kecuali Anda memberikan --memory-limit sendiri, dan menyusun konfigurasinya di direktori sementara sistem, sehingga tidak ada file hasil pembuatan yang masuk ke proyek. Perintah keluar dengan 0 jika analisis lolos, 1 jika PHPStan melaporkan diagnostik, dan 2 untuk kesalahan penggunaan, konfigurasi, atau eksekusi.

Jalankan melalui perintah kanonis alih-alih menambahkan phpstan/extension-installer. Preset sudah menyertakan ekstensi, dan saat installer tersedia, extension.neon yang sama dimuat dua kali: PHPStan berhenti dengan pesan “This file is included multiple times” sebelum analisis dimulai.

Menerapkannya pada proyek yang sudah ada

Proyek yang dianalisis untuk pertama kali biasanya memiliki temuan. Alih-alih melonggarkan preset, catat temuan tersebut dalam baseline agar kode baru tetap mengikuti aturan penuh:

Shell
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
Text
 [OK] Baseline generated with 3 errors.

Sertakan baseline dari konfigurasi proyek dan arahkan phpstan.configuration ke sana:

Neon
includes:
    - phpstan-baseline.neon
JSON
{
  "phpstan": {
    "preset": "extreme-theme",
    "roots": ["."],
    "excludePaths": ["vendor/**"],
    "configuration": "phpstan.neon"
  }
}

Proses berikutnya melaporkan [OK] No errors dengan temuan yang tercatat tetap diperhitungkan, dan temuan baru masih menyebabkan kegagalan. Untuk preset base atau theme, atur juga level: max di bawah parameters dalam phpstan.neon: perintah kanonis hanya mengatur level itu sendiri jika konfigurasi proyek tidak disertakan.

Menjadikan analisis syarat commit

Dengan "githooks": { "commit": true } di blockstudio.json, sinkronkan hook terkelola sekali setelah dependensi diinstal:

Shell
vendor/bin/blockstudio-githooks sync
Text
Blockstudio commit hook enabled: /path/to/acme/.git/blockstudio/hooks/pre-commit

Perintah ini menulis hook di dalam direktori milik Git sendiri, mengarahkan core.hooksPath ke sana, dan merangkai hook pre-commit apa pun yang telah dikonfigurasi sebelumnya. Hook menjalankan vendor/bin/blockstudio-phpstan -- --no-progress dari root proyek saja: tanpa pemformat, tanpa penulisan ulang. Commit pada templat rusak sebelumnya akan berhenti saat analisis:

Text
 [ERROR] Found 3 errors

Blockstudio: commit blocked by theme analysis.

Atur commit ke false dan jalankan sync lagi, atau jalankan vendor/bin/blockstudio-githooks remove untuk memulihkan jalur hook sebelumnya. Hanya file yang ditulis oleh Blockstudio yang dihapus.

Membuat kontrak proyek

Analisis memberi tahu agen apa yang salah setelah kejadian. AGENTS.md memberi tahu sebelumnya: lokasi blok dan halaman, cara field diteruskan ke templat, fitur yang diaktifkan, serta hal yang akan ditolak oleh preset terpilih. blockstudio-agents membuat dokumen tersebut dari proyek itu sendiri:

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

Untuk tema dalam panduan ini, file yang dihasilkan dimulai dengan:

Markdown
# Blockstudio contract for Acme

## Project

- Kind: WordPress theme `Acme`.
- Analysed root: `.`.
- Configuration: `blockstudio.json`.
- Analysis preset: `extreme-theme`.
- Excluded from discovery and analysis: `vendor/**`.

## What this project contains

- Blocks: 1 in `blockstudio`.
- Block namespaces: `acme`.
- Block templates are written in PHP.

Setiap baris berasal dari salah satu dari tiga sumber. File proyek menyediakan jenis proyek, jumlah, direktori, namespace, dan bahasa templat. blockstudio.json menyediakan fitur yang diaktifkan, sehingga hook commit muncul di bawah “Enabled features” dan vendor/bin/blockstudio-githooks sync di bawah “Commands” hanya karena githooks.commit telah diatur. Preset terpilih menyediakan bagian kebenaran, yang dibaca dari lapisan file preset satu per satu:

Markdown
The `theme` layer adds:

- Every analysed root must exist and carry a `style.css` with a `Theme Name` header.
- Block assets are declared in `block.json`; block code must not call `wp_enqueue_script()` or `wp_enqueue_style()`.
- A block `style.scss` must scope its rules through `%selector%`, and assets referenced by `block.json` must exist.
- Every field must define a `default`, and repeaters must declare non-negative `min` and `max` bounds.

Menjaganya tetap mutakhir

Kontrak menjadi usang saat konfigurasi berubah. Setelah mengaktifkan Tailwind di blockstudio.json, mode pemeriksaan akan mendeteksi perubahan:

Shell
vendor/bin/blockstudio-agents --check
Text
Blockstudio contract is out of date: /path/to/acme/AGENTS.md
Run blockstudio-agents to regenerate it.

Perintah keluar dengan 1, sehingga dapat digunakan sebagai langkah CI bersama analisis. Membuat ulang dokumen akan menambahkan entri fitur “Tailwind CSS” dan perintah wp bs tailwind compile.

Catatan yang dipertahankan saat pembuatan ulang

File diakhiri dengan area catatan. Apa pun yang berada di antara penandanya dipertahankan byte demi byte setiap kali dibuat ulang, sehingga pengetahuan proyek yang tidak dapat disimpulkan dari file dapat ditaruh di sana:

Markdown
## Project notes

Everything above is generated. Text between the markers below is preserved when this file is regenerated.

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

Generator tidak pernah mengganti file yang tidak ditulisnya. Jika dijalankan pada AGENTS.md yang ditulis manual, generator akan menolak dan keluar dengan 2:

Text
Blockstudio: Refusing to overwrite the user-owned file at /path/to/acme/AGENTS.md. Pass --force to replace it.

Untuk mempertahankan teks yang ditulis manual, salin ke tempat lain, jalankan dengan --force, lalu tempelkan ke area catatan. Opsi lainnya adalah --root, --config, --output, dan --stdout, yang mencetak kontrak alih-alih menuliskannya.

Perubahan pada Blockstudio 7.7

Paket 7.7 mempertahankan perintah, preset, dan kode keluar yang dijelaskan di sini. Ada dua perbedaan yang terlihat saat menyusun panduan ini dengannya: $a tidak lagi memerlukan anotasi, seperti dijelaskan di bagian perbaikan, dan kontrak yang dihasilkan menjelaskan validasi tag blok secara lebih luas, mencakup elemen HTML yang dipetakan ke blok dalam sumber halaman serta atribut global yang dapat diteruskan oleh sebuah tag.

Langkah berikutnya

  • PHPStan referensi: setiap aturan, parameter prasetel, tipe dan bentuk field, probe render langsung, serta pengenal diagnostik.
  • Integrasi AI: indeks dokumentasi untuk agen coding yang melengkapi kontrak proyek Anda.
  • Vibecoding dengan Blockstudio: bekerja dengan agen coding pada proyek Blockstudio.
  • Buku Resep Pola Field: struktur field yang kunci templatenya dipahami analisis, termasuk grup dan repeater.