İçeriğe geç

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

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

Kabuk
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
<?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:

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

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

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.

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

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

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

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:

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

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.

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

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.

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

PHP
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 name alanı
  • Eksik type alanı
  • 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
  • options veya populate olmadan select/radio/checkbox
  • Yinelenen alan kimlikleri
  • Tekrarlayıcı içindeki bir tabs alanı; doğrudan veya id olmayan bir grup içinde
  • Geçersiz pluginDependencies bildirimleri

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:

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

  • name eksik
  • attributes eksik veya boş
  • Geçersiz öznitelik nesneleri veya alan type eksik
  • Gerektiren değer alanlarında id eksik
  • Bilinmeyen alan türleri
  • Alan türünün kabul etmediği alan özellikleri
  • Doğrudan veya id olmadan bir grubun içinde, tekrarlayıcıda bulunan tabs alanı
  • İç içe custom/* referansları eksik, belirsiz, geçersiz veya döngüsel

Uzantı JSON (extensions/ içindeki blok uzantıları):

  • name eksik (hedef blok)
  • blockstudio anahtarı eksik
  • blockstudio.extend anahtarı eksik

page.json (dosya tabanlı sayfalar):

  • title eksik
  • slug eksik
  • Geçersiz postStatus değerleri

db.php:

  • fields dizisi eksik
  • Geçersiz alan türleri
  • Eski dizileri ve Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field biçimlerini destekler

rpc.php:

  • Geçersiz HTTP yöntemleri
  • Yanlış public değeri (true, false veya 'open' olmalıdır)
  • Eski dizileri ve öznitelikli nesne dönüşlerini destekler

cron.php:

  • Yapılandırılmış görevlerde schedule eksik
  • Yapılandırılmış görevlerde callback eksik
  • Hem eski dizi biçimini hem de öznitelikli nesne dönüşlerini destekler

blockstudio.json:

  • "tailwind": true gibi 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.

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

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

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

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

parameters:
    level: max
JSON
{
  "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:

JSON
{
  "$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:

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

JSON
{
  "$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:

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

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

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

JSON
{"ok":true}

Bir denetim, belirli bir başarısızlığı bildirebilir:

JSON
{
  "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.

Kabuk
vendor/bin/blockstudio-agents
Text
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.css baş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. base düzeyinde şema, şablon, kanca ve ayar kuralları açıklanır. extreme-theme dü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:

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

Markdown
## 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.