İçeriğe geç

PHPStan ve Oluşturulmuş AGENTS.md ile Denetlenen Şablonlar

Bir Blockstudio bloğu, birbiriyle uyumlu olması gereken iki dosyadan oluşur. block.json alanları tanımlar, şablon da bunları $a['id'] olarak okur. Çalışma zamanında, şablonun yeniden adlandırılmış, hiç tanımlanmamış veya yazımı yanlış bir anahtarı okumasını engelleyen hiçbir şey yoktur. Şablon yalnızca boş bir dize oluşturur ve hata, canlı sayfada boş bir başlık fark edildiğinde ortaya çıkar. Çıktı kaçışı için de durum aynıdır: kaçış uygulanmamış bir echo, alan değeri biçimlendirme içerene kadar sorunsuz çalışır.

blockstudio/phpstan paketi bu iki sorunu da analiz aşamasına taşır. block.json dosyalarınızı okur, bunlardan $a türlerini çıkarır ve eşleşmeyen şablon okumalarını bildirir. İsteğe bağlı ön ayarları tema yapısı kurallarını, kaçış denetimini ve JavaScript ile Tailwind denetimlerini ekler. Aynı paket iki yardımcı araçla birlikte gelir: analizi çalıştıran yönetilen bir ön-commit kancası ve kodlama ajanları için projenizi açıklayan bir AGENTS.md oluşturan bir araç.

Bu kılavuzda küçük bir tema oluşturacak, şablonlarından birini bilerek bozacak, analiz çıktısını inceleyip düzeltecek, ardından commit denetimini ve ajan sözleşmesini yapılandıracağız.

Temayı kurma

Önce style.css başlığı, bir composer.json ve bir blok içeren tema klasörü oluşturun:

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

Paketi geliştirme bağımlılığı olarak yükleyin:

Kabuk
composer require --dev blockstudio/phpstan

szepeviktor/phpstan-wordpress üzerinden PHPStan ve WordPress taslaklarını getirir, ardından vendor/bin içine üç yürütülebilir dosya yükler: blockstudio-phpstan, blockstudio-githooks ve blockstudio-agents.

Ardından analize neyi çalıştıracağını belirtin. Proje genelindeki varsayılanlar blockstudio.json içindeki phpstan nesnesinde bulunur; böylece etkileşimli çalıştırmalar, CI ve commit kancası aynı ayarları kullanır:

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

extreme-theme, üç statik ön ayarın en katısıdır. Aşağıdaki tabloda her birinin neler eklediği açıklanır. excludePaths, Composer dosyalarının Blockstudio taramasına ve PHP analizine katılmasını önler.

Bir şablonu bilerek bozma

Hero bloğu tek bir alan tanımlar:

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

Şablon bu alanı doğru okur, ardından bloğun hiç tanımlamadığı bir subtitle alanını okur ve kaçış uygulamadan çıktılar:

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

Düzenleyicide ve ön yüzde bu, boş bir paragraf oluşturur ve hiçbir hata vermez. Bunun yerine analizi çalıştırın:

Kabuk
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

Komut, 1 koduyla çıkar. Tanı iletilerini en belirginden başlayarak inceleyelim:

  • blockstudio.field şablon kuralıdır. Şablonun yanındaki block.json öğesini bulur, alanlarını çözümler ve subtitle bunlardan biri değildir.
  • offsetAccess.notFound de aynı sonuca PHPStan üzerinden ulaşır; çünkü uzantı, block.json öğesinden türetilen somut array{heading: string} biçimini $a için sağlar. Her alan türü bir PHP türüne eşlenir: text bir string, toggle bir bool olur; tekrarlayıcı alan ise satır şekillerinden oluşan bir dizidir.
  • blockstudio.output.unescaped, extreme-theme katmanından gelir. Yankılanan öznitelik değerleri esc_html(), esc_attr(), esc_url() veya wp_kses_post() gibi bir kaçış işlevinden geçirilmelidir.
  • echo.nonString, bilinmeyen anahtardan kaynaklanır: mevcut olmayan bir ofsetin yankılanacak dize türü yoktur.
  • variable.undefined, PHPStan şablon dosyasını görüp onu içeren dosyada $a tanımlayan işlevi görmediği için ortaya çıkar. Çözüm bölümü bunu ele alır.

Düzeltme

subtitle gerçek bir alan mı, karar verin. Burada öyle; bu nedenle temanın katmanı her alanda zorunlu kıldığı bir default ile birlikte tanımlayın:

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": "" }
    ]
  }
}

Çıktıya kaçış uygulayın ve $a alanını uzantının çıkarsadığı şekle göre tanımlayın:

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>
Kabuk
vendor/bin/blockstudio-phpstan -- --no-progress
Text
 [OK] No errors

Açıklamayı tam olarak çıkarılan şekle göre yazın. Standart komut, max düzeyinde PHPStan çalıştırır; bu düzeyde daha gevşek bir @var array<string, mixed> $a, varTag.nativeType hatasıyla reddedilir (“PHPDoc tag @var with type array<string, mixed> is not subtype of native type array{heading: string, subtitle: string}”). 7.6 sürümünde ayrıca her alanı mixed olarak genişletir; bu nedenle her esc_html() çağrısı argument.type bildirir. varTag.nativeType iletisi, çıkarılan şekli yazdırır; bu yüzden kopyalanacak açıklamayı bulmanın en hızlı yolu da budur.

Blockstudio 7.7, $a değişkenini blok şablonlarının içinde tanımlı kabul eder; böylece variable.undefined tanıları ortadan kalkar ve açıklama isteğe bağlı olur. 7.7 sürümünde, yukarıdaki bozuk şablon altı yerine dört hata bildirir; düzeltilmiş şablon ise @var satırı olmadan geçer.

Ön ayar seçme

Paketi yüklemek yalnızca temel uzantıyı etkinleştirir. Proje başka bir ön ayar seçmediğinde standart komut base çalıştırır; dolayısıyla bağımlılığı eklemek tek başına daha katı katmanları etkinleştirmez.

Ön ayar Ekledikleri
base PHP, Twig ve Blade içinde şablon alanı erişimi, blok etiketi denetimleri, block.json, field.json ve page.json için şema doğrulaması, uzantı JSON, db.php ve rpc.php, cron.php, Settings::get() yolları ve blockstudio/* kanca adları.
theme Temel ayarlara tema kökleri ve style.css başlıkları, elle kuyruğa eklemek yerine block.json içinde bildirilen varlıkları, style.scss içinde %selector% kapsam belirlemeyi, alan varsayılanlarını ve tekrarlayıcı sınırlarını ekler.
extreme-theme Tema ayarlarına katı PHPStan bayraklarını, reddedilen kabuk ve eval() çağrılarını, ham $wpdb yazımlarını, çıktı kaçışını, Tailwind, JavaScript ve Interactivity API denetimlerini ekler.
wordpress-render Extreme tema ayarlarına komut olarak sağladığınız canlı işleme denetimini ekler.

Proje yapılandırması olmadığında standart komut, PHPStan düzeyinde max ile birlikte base ve theme öğelerini de çalıştırır; extreme-theme ise max ayarını yapar. Her ön ayar tanısının kararlı bir blockstudio.* tanımlayıcısı vardır; bunlar PHPStan başvurusunda listelenmiştir.

Tema ve Extreme katmanları PHP dosyalarının ötesine bakar. default eksik bir alan ve konsola kayıt yazan bir script.js olduğunda aynı komut şunları bildirir:

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

Bu denetimlerin sonuçları PHPStan’in sonuç önbelleği üzerinden bildirilir. Yalnızca bir block.json veya betik düzenlendikten sonra sıcak önbellek, eski durum için [OK] No errors bildirebilir. Önbelleği atlayan -- işleminden sonra --debug ile çalıştırın; PHP olmayan değişikliklerde başarılı bir çalıştırmaya güvenmeden önce bunu yapın:

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

Komut seçenekleri ve çıkış kodları

Komut satırı değerleri, tek bir çalıştırma için eşleşen blockstudio.json değerlerinin yerini alır. Yerine alma tam anlamıyla yerini alma demektir: herhangi bir --exclude iletmek, yapılandırılmış excludePaths değerini kaldırır; bu nedenle bir tane eklerken vendor/** değerini de yeniden belirtin:

Kabuk
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":[]}

-- sonrasındaki her şey PHPStan öğesine aktarılır. Kendi --memory-limit değerinizi iletmediğiniz sürece sarmalayıcı, PHPStan öğesinin bellek sınırını 1G değerine yükseltir ve yapılandırmasını sistemin geçici dizininde oluşturur; böylece projede oluşturulan bir dosya kalmaz. Analiz başarılı olursa 0, PHPStan tanı bildirirse 1, kullanım, yapılandırma veya yürütme hatalarında ise 2 koduyla çıkar.

phpstan/extension-installer eklemek yerine standart komut üzerinden çalıştırın. Ön ayarlar uzantıyı zaten içerir ve yükleyici mevcutken aynı extension.neon iki kez yüklenir: PHPStan, herhangi bir analiz yapmadan önce “This file is included multiple times” ile durur.

Mevcut bir projeye uygulama

İlk kez analiz edilen bir projede genellikle bulgular olur. Ön ayarı gevşetmek yerine bunları bir temel dosyasına kaydedin; böylece yeni kod tüm kurallara uymak zorunda kalır:

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

Temel dosyasını bir proje yapılandırmasından içe aktarın ve phpstan.configuration yolunu bu dosyaya ayarlayın:

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

Sonraki çalıştırma, kaydedilmiş bulgularla birlikte [OK] No errors bildirir; yeni bulgular ise başarısız olmaya devam eder. base veya theme ön ayarını kullanırken, phpstan.neon içindeki parameters altında level: max değerini de ayarlayın: proje yapılandırması yoksa bu düzeyi yalnızca standart komut ayarlar.

Analizle commit işlemlerini denetleme

blockstudio.json içinde "githooks": { "commit": true } varken, bağımlılıkları yükledikten sonra yönetilen kancayı bir kez eşitleyin:

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

Komut kancayı Git’in kendi dizinine yazar, core.hooksPath değişkenini bu yola ayarlar ve önceden yapılandırılmış ön-commit kancasını zincirleme çalıştırır. Kanca, proje kökünden yalnızca vendor/bin/blockstudio-phpstan -- --no-progress öğesini çalıştırır: biçimlendirici yoktur, dosyalar yeniden yazılmaz. Bozuk şablona daha önceki gibi commit etmeye çalışmak analiz aşamasında durur:

Text
 [ERROR] Found 3 errors

Blockstudio: commit blocked by theme analysis.

Önceki kanca yolunu geri yüklemek için commit değerini false olarak ayarlayıp sync komutunu yeniden çalıştırın ya da vendor/bin/blockstudio-githooks remove komutunu çalıştırın. Yalnızca Blockstudio tarafından yazılan dosyalar silinir.

Proje sözleşmesini oluşturma

Analiz, bir ajana neyi yanlış yaptığını sonradan söyler. Bir AGENTS.md ise bunu önceden bildirir: blokların ve sayfaların konumunu, alanların şablonlara nasıl ulaştığını, hangi özelliklerin etkin olduğunu ve seçili ön ayarın neleri reddedeceğini açıklar. blockstudio-agents bu belgeyi doğrudan projeden oluşturur:

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

Bu kılavuzdaki tema için oluşturulan dosya şöyle başlar:

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.

Her satır üç kaynaktan birinden gelir. Proje dosyaları proje türünü, sayıları, dizinleri, ad alanlarını ve şablon dillerini sağlar. Etkin özellikleri blockstudio.json sağlar; bu nedenle commit kancası “Enabled features” altında, vendor/bin/blockstudio-githooks sync ise “Commands” altında görünür; bunun nedeni yalnızca githooks.commit ayarının yapılmış olmasıdır. Seçili ön ayar, doğruluk bölümünü sağlar; bu bölüm ön ayar dosyalarından katman katman okunur:

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.

Güncel tutma

Yapılandırma değiştiğinde sözleşme güncelliğini yitirir. blockstudio.json içinde Tailwind etkinleştirildikten sonra denetim modu bunu fark eder:

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

1 koduyla çıkar; bu sayede analizle birlikte bir CI adımı olarak kullanılabilir. Yeniden oluşturma, “Tailwind CSS” özellik girdisini ve wp bs tailwind compile komutunu ekler.

Yeniden oluşturmada korunan notlar

Dosyanın sonunda bir notlar bölgesi bulunur. İşaretçilerinin arasındaki her şey her yeniden oluşturmada bayt bayt korunur; bu nedenle dosyalardan çıkarılamayan proje bilgileri buraya yazılmalıdır:

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

Oluşturucu, kendisinin yazmadığı bir dosyanın üzerine asla yazmaz. Elle yazılmış bir AGENTS.md dosyası için çalıştırıldığında işlemi reddeder ve 2 koduyla çıkar:

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

Elle yazılmış metni korumak için bir kopyasını alın, --force ile çalıştırın ve metni notlar bölgesine yapıştırın. Diğer seçenekler --root, --config, --output ve sözleşmeyi dosyaya yazmak yerine çıktısını veren --stdout seçenekleridir.

Blockstudio 7.7 sürümündeki değişiklikler

7.7 paketi, burada açıklanan komutları, ön ayarları ve çıkış kodlarını korur. Bu kılavuz hazırlanırken görülen iki fark şunlardır: düzeltme bölümünde anlatıldığı üzere $a artık açıklama gerektirmez; oluşturulan sözleşme de blok etiketi doğrulamasını daha geniş tanımlar ve sayfa kaynaklarında bloklara eşlenen HTML öğeleriyle bir etiketin iletebileceği genel öznitelikleri kapsar.

Sonraki adımlar

  • PHPStan başvurusu: her kural, hazır ayar parametresi, alan türü yapısı, canlı oluşturma denetimi ve tanılama tanımlayıcısı.
  • Yapay Zekâ Entegrasyonu: proje sözleşmenizi tamamlayan, kodlama ajanlarına yönelik dokümantasyon dizini.
  • Blockstudio ile vibecoding: bir Blockstudio projesinde kodlama ajanlarıyla çalışma.
  • Alan Kalıpları Rehberi: analizde anlaşılan şablon anahtarlarına sahip alan yapıları; gruplar ve tekrarlayıcılar da buna dahildir.