PHPStan
blockstudio/phpstan uzantısı, Blockstudio projelerine statik analiz olanağı kazandırır. Blok şablonlarını, şema dosyalarını, ayar yollarını ve hook adlarını analiz sırasında doğrulayarak hataların çalışma zamanına ulaşmadan yakalanmasını sağlar.
Kurulum
composer require --dev blockstudio/phpstan
7.7 şablon türleri ve genişletilmiş blok etiketi denetimleri için blockstudio/phpstan 0.1.9 veya üstü ve PHPStan 2.1.47 veya üstü gerekir. Paketi eklentiden ayrı olarak güncelleyin:
composer require --dev blockstudio/phpstan:^0.1.9
Uzantı, PHPStan’nin uzantı yükleyicisi aracılığıyla otomatik olarak keşfedilir. Elle yapılandırma gerekmez.
Neleri denetler
Şablon alanına erişim
PHP dosyası bir block.json dosyasının yanında bulunduğunda uzantı, her $a['key'] erişimini bloğun tanımlı özniteliklerine göre doğrular.
<?php
echo $a['title']; // OK
echo $a['subtitle']; // OK
echo $a['typo']; // Error: Field "typo" does not exist in block.json
Uzantı, şablonu içeri aktarmadan önce Blockstudio öğesinin $a, $attributes, $b, $block, $c, $context, $content, $isEditor, $isPreview ve ada değişkenlerini tanımladığını bilir. Bu nedenle $a['title'] gibi doğrudan okumalar, tanımsız olma olasılığı nedeniyle raporlanmaz; $a ise şablonun yanındaki block.json dosyasından tür alır. Daraltma sırasında bu yapı korunur; dolayısıyla $a['label'] ?? '', isset( $a['cta']['target'] ) ve $a['cta']['title'] !== null tanımlı alan türlerini korur. $a öğesine değer atayan şablon da atadığı türü korur. Bir /** @var array<string, mixed> $a */ docblock’u eklemeyin: bu, yapıyı açık bir diziyle değiştirir.
Alan anahtarları Blockstudio’nin çalışma zamanındaki düzleştirme kurallarını izler. id olmadan kullanılan tabs ve anonim group kapsayıcılar yalnızca sunum amaçlıdır; bu nedenle alt alanları üst kapsamda kalır. Adlandırılmış bir grup, alt anahtarlarının başına grup kimliğini ekler:
echo $a['heading']; // Anonymous group child.
echo $a['cta_text']; // "text" inside the named "cta" group.
Yeniden kullanılabilir özel alanlar
Dosya tabanlı custom/* başvuruları, şablon anahtarları ve dizi yapıları denetlenmeden önce açımlanır. Uzantı eşleşen field.json dosyasını okur ve Blockstudio ile aynı idStructure, overrides, iç içe başvuru, grup, sekme ve tekrarlayıcı kurallarını uygular:
{
"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" }
}
}
]
}
}
Ortaya çıkan şablon anahtarları title ve hero_description olur. Bunlar PHP, Twig, Blade içinde, blok etiketlerinde ve çıkarımlanan öznitelik yapılarında tanınır.
Eksik, belirsiz, geçersiz veya döngüsel dosya tabanlı tanımlar belirli bir blockstudio.customField.* hatası oluşturur. Çözümlenmemiş tek bir tanımın ikinci bir sahte bilinmeyen alan hataları dalgasına yol açmaması için bu blokta bağımlı anahtar denetimleri atlanır.
Yalnızca çalışma zamanında blockstudio/fields PHP filtresi aracılığıyla kaydedilen tanımlar statik analizle çıkarımlanamaz. Alanın statik olarak denetlenen şablon anahtarlarına katkıda bulunması gerekiyorsa field.json tanımı kullanın.
Twig şablonuna erişim
Twig şablonları otomatik olarak taranır. Ek açıklama gerekmez.
<h1>{{ a.title }}</h1>
<p>{{ a.typo }}</p> {# Error: Field "typo" does not exist in block.json #}
Blade şablonuna erişim
Blade şablonları da aynı şekilde taranır.
<h1>{{ $a['title'] }}</h1>
<p>{{ $a['typo'] }}</p> {{-- Error --}}
Blok etiketi doğrulaması
Blok etiketleri, Blockstudio tarafından okundukları yerlerde doğrulanır: <bs:> ve <block> etiketleri; blockTags.prefixes içinde yapılandırılan önek etiketleri (ör. <acme-card>; çalışma zamanındaki gibi ad alanı sırasına göre çözümlenir); ve PHP, Twig ve Blade blok şablonlarındaki ve sayfa düzenlerindeki takma ad etiketleri. pages/ altındaki sayfa kaynakları (index.php, index.html, index.twig, index.blade.php) da denetlenir; buna projenin bloklara eşlediği HTML öğeleri de dahildir. ui.enabled etkin olduğunda paketlenmiş UI blokları tanınır.
<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) -->
Bir öznitelik, blok tarafından alan olarak tanımlanmışsa (özel alanlar ve blok türündeki bir alanın kendi idStructure kapsamında ilettiği alanlar dahil) veya Blockstudio bu özniteliği bloğun kök öğesine iletiyorsa kabul edilir: data-*, aria-*, id, style, role, title, lang, dir, hidden ve tabindex. Şablonlarda her html-* özniteliği aktarılır; sayfa kaynaklarında ise bir html- öneki yalnızca iletilen özniteliklerden birini belirtir. Bildirilmemiş bir class başta olmak üzere diğer her şey raporlanır; çünkü Blockstudio bunu saklar ve hiçbir zaman oluşturmaz.
Çalışma zamanı öğe eşlemelerini ve etiket takma adlarını PHP filtrelerinde kaydeder. Statik analiz bunları değerlendiremediği için analiz, bilgileri blockstudio.json dosyasından okur. scanPhp ayrıca modüllerdeki bileşen işaretlemesi gibi diğer proje PHP içindeki etiketleri de denetler ve burada bilinmeyen bloklar olduğunu bildirmez:
{
"phpstan": {
"blockTags": {
"elements": {
"section": "theme/section",
"h2": "theme/heading",
"div": [
{ "attribute": "width", "block": "theme/row" },
"theme/div"
]
},
"aliases": { "theme-button": "bsui/button" },
"scanPhp": true
}
}
}
Bir öğe, bir blok adına veya sırayla denenen kurallara eşlenir: özniteliği öğede bulunan ilk kural kazanır ve yalın bir blok adı her zaman eşleşir. Projenin eşlemediği öğeler kendi çekirdek bloklarını korur ve denetlenmez. Tanılama mesajlarında blockstudio.blockTag.unknown, blockstudio.blockTag.attribute ve blockstudio.blockTag.class kullanılır.
Veritabanı kayıt türleri
Db::get(), db.php şemasına göre türlendirilmiş bir örnek döndürür. Kayıt yapıları otomatik olarak çıkarımlanır.
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
Zorunlu alanlar null olamaz. İsteğe bağlı alanlar type|null. Bir id alanı (int) her zaman bulunur. Aynı tür denetimi PHP yerel Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field oluşturucu söz dizimi için de geçerlidir.
Ayar yolu doğrulama
Settings::get() yolları bilinen ayar şemasına göre denetlenir.
Settings::get('tailwind/enabled'); // OK, returns bool
Settings::get('tailwind/enabld'); // Error: Did you mean "tailwind/enabled"?
Kanca adı doğrulama
Blockstudio filtre ve eylem hook adları doğrulanır.
add_filter('blockstudio/render', $cb); // OK
add_filter('blockstudio/rendrr', $cb); // Error: Did you mean "blockstudio/render"?
blockstudio/settings/tailwind/enabled gibi dinamik ayar hook’larına her zaman izin verilir. Blockstudio dışındaki hook’lar yok sayılır.
Şema doğrulama
Uzantı projedeki her Blockstudio şema dosyasını doğrular.
block.json:
- Eksik
namealanı - Eksik
typealanı - Tek değer gerektiren alanlarda eksik
id - Bilinmeyen alan türleri
- Alan türünün kabul etmediği alan özellikleri; örneğin
"translate"yerine"translat"kullanılması ve öneri olarak en yakın bilinen özelliğin belirtilmesi optionsveyapopulateolmadanselect/radio/checkbox- Yinelenen alan kimlikleri
- Tekrarlayıcı içindeki bir
tabsalanı; doğrudan veyaidolmayan bir grup içinde - Geçersiz
pluginDependenciesbildirimleri
group ve tabs gibi kapsayıcı alanlar ile custom/* alan başvuruları, yalnızca diğer alanları açımlıyor veya sarıyorsa id öğesini içermeyebilir.
Alan özellikleri, her yerleşik alan türü için schemas/block.json tarafından bildirilen özelliklerle ve her alanın kabul ettiği özelliklerle karşılaştırılarak denetlenir. custom/* referanslarındaki sarmalayıcıya özgü özellikler ve projede tanımlanmış ad alanlı alan türleri bu denetimin dışındadır. Mevcut alan türü ve özel referans doğrulamaları geçerliliğini korur. Tanımlayıcılar blockstudio.blockJson.property ve blockstudio.fieldJson.property şeklindedir.
Bu denetim yalnızca değerleri değil, özellik adlarını da kontrol eder: minimized bir tekrarlayıcıda geçerlidir ancak bir metin alanında raporlanır. Eklentinin çalışma zamanı davranışı değişmez. Bir proje yerleşik alanlara bilerek kendi meta verilerini ekliyorsa, diğer yapı denetimlerini devre dışı bırakmadan yalnızca bu bulguları bastırın:
parameters:
ignoreErrors:
- identifier: blockstudio.blockJson.property
- identifier: blockstudio.fieldJson.property
Yeniden kullanılabilir bir field.json içindeki yerleşik alanlar, custom/* referansının kendine ait sarmalayıcı seçenekleri olsa bile denetlenmeye devam eder. Uzantı dosyaları bu özellik adı tanılamalarının kapsamı dışındadır; uzantıya özgü set kuralları geçerliliğini korur.
field.json (yeniden kullanılabilir özel alanlar):
nameeksikattributeseksik veya boş- Geçersiz öznitelik nesneleri veya alan
typeeksik - Gerektiren değer alanlarında
ideksik - Bilinmeyen alan türleri
- Alan türünün kabul etmediği alan özellikleri
- Doğrudan veya
idolmadan bir grubun içinde, tekrarlayıcıda bulunantabsalanı - İç içe
custom/*referansları eksik, belirsiz, geçersiz veya döngüsel
Uzantı JSON (extensions/ içindeki blok uzantıları):
nameeksik (hedef blok)blockstudioanahtarı eksikblockstudio.extendanahtarı eksik
page.json (dosya tabanlı sayfalar):
titleeksikslugeksik- Geçersiz
postStatusdeğerleri
db.php:
fieldsdizisi eksik- Geçersiz alan türleri
- Eski dizileri ve
Blockstudio\\Db\\Schema/Blockstudio\\Db\\Fieldbiçimlerini destekler
rpc.php:
- Geçersiz HTTP yöntemleri
- Yanlış
publicdeğeri (true,falseveya'open'olmalıdır) - Eski dizileri ve öznitelikli nesne dönüşlerini destekler
cron.php:
- Yapılandırılmış görevlerde
scheduleeksik - Yapılandırılmış görevlerde
callbackeksik - Hem eski dizi biçimini hem de öznitelikli nesne dönüşlerini destekler
blockstudio.json:
"tailwind": truegibi kısa boole değerleri (iç içe nesne biçimi{"enabled": true, "config": ""}kullanılmalıdır)
Yapılandırma
Uzantı, varsayılan olarak analiz edilen projedeki Blockstudio dosyalarını keşfeder.
Bir proje, proje kökü dışındaki bir kütüphaneden bloklar veya yeniden kullanılabilir
alanlar kullanıyorsa kütüphane yolunu blockstudioScanRoots içine ekleyin. Yol hem block.json hem de field.json tanımlarını tarar; böylece harici blok etiketleri ve özel alanları birlikte doğrulanabilir.
parameters:
blockstudioScanRoots:
- vendor/acme/block-library/blockstudio
Dosyaları yok saymak için PHPStan aracının standart excludePaths yapılandırmasını kullanın.
Analiz ön ayarları
Otomatik keşfedilen uzantı, uyumluluğu koruyan temel katman olarak kalır. Blockstudio 7.6, mevcut projeleri değiştirmeden isteğe bağlı katmanlar ekler:
| Ön ayar | Davranış |
|---|---|
base.neon |
Mevcut şema, şablon, kanca, ayarlar ve API analizi. |
theme.neon |
Temel katmana ek olarak WordPress tema kökleri, stil başlıkları, Blockstudio varlıkları, seçici kapsamı, alan varsayılanları ve yineleyici sınırları. |
extreme-theme.neon |
Tema katmanına ek olarak PHPStan max, güvenli olmayan PHP, çıktı kaçışlama, Tailwind, JavaScript ve Interactivity API kontrolleri. |
wordpress-render.neon |
Extreme theme katmanına ek olarak çağıranın sağladığı canlı WordPress render denetimi. |
blockstudio/phpstan kurulumu yalnızca temel uzantıyı etkinleştirir. Mevcut bir PHPStan yapılandırmasına isteğe bağlı bir katman ekleyin:
includes:
- vendor/blockstudio/phpstan/extreme-theme.neon
parameters:
blockstudioThemeRoots:
- .
blockstudioThemeExcludePaths:
- fixtures/**
blockstudioThemeMaxFiles: 10000
blockstudioExtremeJavaScript: true
blockstudioExtremeTailwind: true
blockstudioThemeExcludePaths tema tarayıcısını denetler.
PHPStan aracının standart excludePaths yapılandırması, PHP analizini bağımsız olarak denetler.
Kanıtsal komutun phpstan.excludePaths ayarı, blockstudio.json içindeki
(ve --exclude seçeneğiyle birlikte) her iki katmanı da yapılandırır. Göreli kalıplar
her yapılandırılmış köke göre çözümlenir; bu nedenle vendor/** gibi girdiler
hem PHPStan analizini hem de Blockstudio aracının proje taramasını sınırlar.
_dist/** veya node_modules/** gibi tek bir dizini belirten kalıp,
yalnızca tema kökünün yanındaki dizini değil, bulunduğu her yerdeki o dizini hariç tutar. assets/*/docs/** gibi eğik çizgi içeren bir kalıp köke sabitlenir. Oluşturulan blok varlıkları her bloğun içindeki _dist dizininde bulunur; bu nedenle derlenmiş çıktıyı analiz dışında tutmak için tek dizin biçimi kullanılır.
Kanıtsal komut
Paket, analiz yürütülebilir dosyası olarak vendor/bin/blockstudio-phpstan dosyasını kurar. Bir proje başka bir ön ayar seçmediği sürece base ön ayarını çalıştırır; dolayısıyla paketi kurmak tek başına tema veya extreme-theme katmanlarını etkinleştirmez:
vendor/bin/blockstudio-phpstan --root . -- --no-progress
Ön ayarlar uzantıyı kendileri içerir. Kanıtsal komutu çalıştıran bir projeye phpstan/extension-installer eklemeyin:
yükleyici mevcutken extension.neon iki kez yüklenir ve PHPStan, herhangi bir analiz yapmadan önce “This file is included multiple times” hatasıyla durur.
Komut, Composer tarafından yönetilen WordPress projelerinin tipik bir 128M CLI sınırını devralmaması için PHPStan değerini 1G bellek sınırına ayarlar. Bu sınırı geçersiz kılmak için -- sonrasında açık bir PHPStan seçeneği iletin; örneğin -- --memory-limit=512M --no-progress.
Mevcut bir projede analizi benimseme
Daha önce hiç analiz edilmemiş bir proje, ilk çalıştırmada genellikle bulgular bildirir. Ön ayarı düşürmek yerine bir PHPStan temel çizgisi oluşturun ve phpstan.configuration aracını bunu içeren bir proje yapılandırmasına yönlendirin. Böylece kaydedilen bulgular aradan çekilirken yeni kod tam ön ayar gerekliliklerine tabi olur:
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
includes:
- phpstan-baseline.neon
parameters:
level: max
{
"phpstan": {
"configuration": "phpstan.neon"
}
}
level satırını base ve theme hazır ayarları için koruyun. Kanonik komut, proje yapılandırması eklenmediğinde onlar için yalnızca max düzeyini ayarlar; PHPStan düzeyi olmadan “No rules detected” mesajıyla durur. extreme-theme hazır ayarı düzeyi kendi başına max olarak ayarlar.
Göreli yollar blockstudio.json konumuna göre çözümlenir. Kanıtsal komut ile yönetilen commit kancası dosyayı birlikte algılar; böylece kanca, birikmiş işlerin önce temizlenmesini gerektirmeden yeni bulguları engeller.
Projeye genel komut varsayılanlarını blockstudio.json içinde tutun:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["fixtures/**"],
"maxFiles": 10000
}
}
Göreli kökler, onları bildiren dosyaya göre çözümlenir. Açık CLI değerleri, karşılık gelen JSON değerlerinin yerini alır. Alternatif bir yapılandırma kaynağı için --blockstudio-json path/to/project.json iletin. Hatalı JSON, desteklenmeyen phpstan anahtarlar, geçersiz değerler ve eksik bir açık kaynak, çıkış kodu 2 ile tutarlı biçimde başarısız olur.
Başka bir ön ayar seçin, proje yapılandırması ekleyin, yinelenebilir kökler ve hariç tutmalar ekleyin ya da PHPStan aracından JSON isteyin:
vendor/bin/blockstudio-phpstan \
--preset theme \
--configuration phpstan.neon \
--root . \
--exclude 'fixtures/**' \
--max-files 10000 \
--error-format json \
-- --no-progress
Sarmalayıcı, yapılandırmayı sistemin geçici dizininde birleştirir ve çıkışta siler. Analiz edilen projeye oluşturulmuş yapılandırma, temel çizgiler, kancalar veya önbellekler yazmaz. Yine de çağıranlar PHPStan aracının normal önbelleğini açıkça yapılandırabilir.
Çıkış kodları şöyledir:
- Analiz başarılı olduğunda
0 - PHPStan tanılama bildirdiğinde
1 - Geçersiz kullanım, yapılandırma veya işlem yürütme durumunda
2
Yönetilen commit kancası
Extreme-theme analizini depo commit kapısı yapmak için blockstudio.json içindeki Blockstudio tarafından yönetilen kancayı etkinleştirin:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": [],
"maxFiles": 10000
},
"githooks": {
"commit": true
}
}
Bağımlılıkları kurduktan veya ayarı değiştirdikten sonra eşitleyin:
vendor/bin/blockstudio-githooks sync
Komut, oluşturduğu pre-commit kancasını ve sahiplik kaydını Git aracının ortak dizinine yazar, core.hooksPath değerini yönetilen kanca dizinine ayarlar ve önceden yapılandırılmış pre-commit kancasını güvenle zincirler. Yinelenen eşitlemeler yalnızca oluşturulan dosyayı yeniler; böylece paket yükseltmeleri yinelenebilir olur.
commit değerini false olarak ayarlayın, kaldırın veya blockstudio.json öğesini kaldırın; ardından kaydedilmiş kanca yolunu geri yüklemek ve yalnızca Blockstudio tarafından yönetilen dosyaları silmek için sync komutunu çalıştırın. Şunu da çalıştırabilirsiniz:
vendor/bin/blockstudio-githooks remove
Kullanıcıya ait dosyaların üzerine asla yazılmaz ve bunlar silinmez. Blockstudio etkinleştirildikten sonra biri core.hooksPath değerini değiştirirse kaldırma işlemi bu yeni ayarı korur. Oluşturulan kanca, etkin depoyu ve proje kökünü commit sırasında çözümleyerek bağlantılı Git çalışma kopyalarını ve boşluk içeren yolları destekler. Kanıtsal komutu bu kökten çalıştırır; böylece aynı phpstan nesnesi, yinelenen oluşturulmuş argümanlara gerek kalmadan etkileşimli çalıştırmaları ve commit’leri denetler.
Kanca yalnızca vendor/bin/blockstudio-phpstan komutunu çalıştırır. Blockstudio bir biçimlendirici çalıştırmaz ve kanca proje dosyalarını asla yeniden yazmaz. Eksik bağımlılıklar ve analiz hataları, açıklayıcı bir hatayla commit işlemini engeller.
Canlı WordPress işleme
Canlı katman özellikle açıkça yapılandırılır. Çağıran, WordPress ortamının sahibidir ve bir argv dizisi sağlar:
vendor/bin/blockstudio-phpstan \
--preset wordpress-render \
--render-command='["wp","eval-file","tools/render-probe.php"]' \
--render-working-directory=. \
--render-timeout=60 \
--root .
Komut bir kabuk kullanmadan çalışır ve tek bir JSON nesnesi yazdırmalıdır:
{"ok":true}
Bir denetim, belirli bir başarısızlığı bildirebilir:
{
"ok": false,
"message": "Rendered block failed.",
"file": "/absolute/path/to/block.json",
"line": 12
}
Sıfırdan farklı çıkış kodları, zaman aşımları, hatalı JSON ve ok: false, blockstudio.wordpress.render sonucunu üretir.
blockstudio.javascript.domContract, bir betiğin querySelector(), querySelectorAll(), closest() veya matches() öğesine ilettiği [data-*] öznitelik seçicisini, analiz edilen hiçbir işaretlemede bu öznitelik bulunmadığında raporlar. İşaretleme; analiz edilen köklerin altındaki tüm PHP, Twig, Blade ve HTML dosyaları ile tüm React .tsx ve .jsx bileşenlerinden, hariç tutulan yollar çıkarıldıktan sonra kalanlardır. Bileşenler ayrıştırılır: JSX öznitelik adları ve nesne değişmezlerindeki dize anahtarları sayılır. Bu nedenle, bir öğeye yayılan öznitelik nesnesi seçiciyi karşılar; sınıf adları ve diğer öznitelik değerleri karşılamaz.
Etkileşim API denetimleri aynı React bileşenlerini okur. Bir JSX öğesindeki data-wp-interactive ad alanı, blockstudio.interactivity.orphan için şablon referansı sayılır; içindeki data-wp-* yönergeleri en yakın kapsayıcı ad alanına veya değerdeki bir namespace:: önekine göre çözümlenir. JSX özniteliği olarak ya da öznitelik nesnesinin dize anahtarı olarak yazılan statik dize değerli yönergeler, mevcut depo işleyicilerini ve yollarını belirtmelidir (blockstudio.interactivity.handler, blockstudio.interactivity.binding); depo kodu da bağlandıkları öznitelikleri ve sınıfları değiştirmemelidir (blockstudio.interactivity.derivedState). React öznitelik değerlerinden kaçış yaptığı için, bir bileşendeki data-wp-context raporlanmaz ve dinamik değerler denetlenmez. bsui/ altındaki ad alanları, depoları analiz edilen köklerin dışında Blockstudio ile birlikte sunulan paketlenmiş UI bloklarına aittir; bu nedenle hiçbir zaman sahipsiz kalmazlar.
Tanılama tanımlayıcıları
Yeni ön ayar tanılamaları, kararlı blockstudio.* kimliklerini korur:
- Tema yapısı:
blockstudio.theme.root.missing,blockstudio.theme.style.missing,blockstudio.theme.style.header,blockstudio.theme.scanLimit - Varlıklar ve alanlar:
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 - Etkileşim:
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
Performans
Tarayıcı, diskte bulunan olağan dizinleri kabul eder, kökleri yinelenenlerden arındırır, bağımlılık/derleme/önbellek ağaçlarını atlar, dosya okumalarını bellekte önbelleğe alır ve tanılamaları tutarlı biçimde sıralar. Kökleri dar tutun, örnek ve oluşturulmuş ağaçları hariç tutun, büyük depolar için bir dosya sınırı belirleyin. JavaScript ve Tailwind bağımsız olarak devre dışı bırakılabilir. Canlı işleme, seçilen ön ayar gerektirmedikçe hiçbir zaman çalışmaz.
Tema, JavaScript ve Tailwind tanılamaları PHPStan aracının sonuç önbelleği üzerinden bildirilir. Yalnızca bir block.json veya betik değiştirildiğinde sıcak önbellek önceki sonucu bildirebilir. Bu tür değişiklikleri doğrularken önbelleği atlamak için -- sonrasında --debug iletin.
Kodlama ajanları için proje sözleşmesi
Paket, üçüncü bir yürütülebilir dosya olan vendor/bin/blockstudio-agents aracını kurar. Çalıştırıldığı projeyi açıklayan bir AGENTS.md yazar; bu, herhangi bir şeye dokunmadan önce kodlama ajanının ihtiyaç duyduğu bilgileri içerir: projenin neler ürettiğini, hangi Blockstudio özelliklerinin etkin olduğunu, analizin neleri reddedeceğini ve hangi komutların geçerli olduğunu.
vendor/bin/blockstudio-agents
Blockstudio contract created: /path/to/project/AGENTS.md
Çıktıdaki hiçbir şey sabit bir şablon değildir. Her satır üç kaynaktan birine dayanır:
- Projenin kendi dosyaları.
style.cssbaşlığı, blokları ve dosya tabanlı sayfaları olan bir tema; blokları kaydeden ve başka hiçbir şey yapmayan bir eklentiden farklı bir belge üretir. Sayılar, dizinler, blok ad alanları ve şablon dilleri, tarayıcının analizle aynı kökleri ve hariç tutmaları kullanarak gerçekten bulduklarıdır. blockstudio.json. Yalnızca etkin özellikler, yapılandırılmış değerleriyle açıklanır: blok etiketi önekleri ve çözümlendikleri ad alanları, Tailwind, paketlenmiş UI, düzenleyici varlıklarının sıfırlanması, önbellek yolu, performans profili, statik ön oluşturma ve dinamik yolları, tema varsayılanları, Content Sync ve commit kancası.- Seçilen
phpstan.preset. Doğruluk bölümü, ön ayar dosyalarından katman katman okunur; böylece ön ayarın kaydettiği kuralların tam listesi verilir.basedüzeyinde şema, şablon, kanca ve ayar kuralları açıklanır.extreme-themedüzeyinde ise tema yapısı kuralları, katı PHPStan bayrakları, güvenli olmayan PHP, çıktı kaçışlama, Tailwind ve JavaScript da açıklanır. Bir ön ayara yeni bir kural eklenirse oluşturulan belge de buna göre değişir.
Komutlar bölümü de aynı ilkeyi izler. Statik ön oluşturma etkin olduğunda wp bs prerender status, githooks.commit ayarlandığında vendor/bin/blockstudio-githooks sync ve projede gerçekten bir db.php varsa wp bs db schemas görünür.
| Seçenek | Davranış |
|---|---|
--root <path> |
Proje kökü (varsayılan: geçerli dizin) |
--config <path> |
blockstudio.json yolu (varsayılan: <root>/blockstudio.json) |
--output <path> |
Sözleşme yolu (varsayılan: <root>/AGENTS.md) |
--stdout |
Sözleşmeyi yazmak yerine yazdır |
--check |
Diskteki sözleşme güncel değilse 1 ile çık |
--force |
Blockstudio dosyasının sahip olmadığı bir dosyayı değiştir |
--check, commit kancasının analizi kapı olarak kullanması gibi sözleşmeyi de bir CI kapısı yapar:
vendor/bin/blockstudio-agents --check
Sahiplik
Oluşturulan dosyada, yönetilen commit kancasındakiyle aynı türden bir işaret bulunur ve aynı kural geçerlidir: Blockstudio, yazmadığı bir dosyanın yerini asla almaz.
Komuttan önce var olan veya yazarın elle oluşturduğu bir AGENTS.md dosyası, --force iletilene kadar çıkış kodu 2 ile reddedilir ve olduğu gibi bırakılır.
Yeniden oluşturmak güvenlidir. Dosya bir notlar bölgesiyle biter ve işaretleri arasındaki baytlar her yeniden oluşturmada korunur:
## Project notes
<!-- blockstudio:notes:start -->
Deploys run from the release branch only.
<!-- blockstudio:notes:end -->
Sözleşme yazıldığında, güncel olduğunda veya yazdırıldığında çıkış kodu 0; --check güncel olmayan bir sözleşme bulduğunda 1; kullanım, yapılandırma veya dosya sistemi hatalarında ise 2 olur.
Alan türü yapıları
Uzantı, her Blockstudio alan türünü somut bir PHP türüne eşler:
| Alan türü | PHP türü |
|---|---|
text, textarea, richtext, wysiwyg, code |
string |
date, datetime, classes, html-tag, unit, gradient |
string |
number, range |
int|float |
toggle |
bool |
select, radio, checkbox (tekil) |
string|int |
select, checkbox (çoğul) |
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 (tekil) |
array{id: int, url: string, alt: string|null, mime_type: string|null} |
files (çoğul) |
list<array{id: int, url: string, ...}> |
group |
Adlandırılmış gruplar alt çizgi önekleri kullanır; adsız gruplar üst kapsamda düzleştirilir |
repeater |
list<array{...child fields...}> |
tabs |
Üst kapsamda düzleştirilir |
API tanımlama dosyaları
Eklenti, Blockstudio genel API arayüzünün tamamı için tanım dosyaları içerir:
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()
Bunlar, Blockstudio eklentisinin kaynak kodunu makinenizde bulundurmanıza gerek kalmadan otomatik tamamlama ve tür denetimi sağlar.
Gereksinimler
- PHP 8.2+
- PHPStan 2.1.47+
phpstan/extension-installer(otomatik keşif için önerilir)
Paket, BC Math uyumluluk sağlayıcısını otomatik olarak kurar. Bu nedenle ext-bcmath, tema veya extreme ön ayarı üzerinden JavaScript kontrollerini etkinleştiren yeni oluşturulmuş temalar için bile isteğe bağlıdır.