PHPStan
Η επέκταση blockstudio/phpstan προσθέτει στατική ανάλυση σε έργα Blockstudio. Επικυρώνει πρότυπα block, αρχεία σχήματος, διαδρομές ρυθμίσεων και ονόματα hook κατά την ανάλυση, εντοπίζοντας σφάλματα πριν εμφανιστούν κατά την εκτέλεση.
Εγκατάσταση
composer require --dev blockstudio/phpstan
Η τυποποίηση προτύπων της έκδοσης 7.7 και οι διευρυμένοι έλεγχοι ετικετών block απαιτούν blockstudio/phpstan 0.1.9 ή νεότερο και PHPStan 2.1.47 ή νεότερο. Ενημερώστε το πακέτο ξεχωριστά από το πρόσθετο:
composer require --dev blockstudio/phpstan:^0.1.9
Η επέκταση εντοπίζεται αυτόματα μέσω του προγράμματος εγκατάστασης επεκτάσεων του PHPStan. Δεν χρειάζεται μη αυτόματη διαμόρφωση.
Τι ελέγχει
Πρόσβαση σε πεδία προτύπων
Όταν ένα αρχείο PHP βρίσκεται δίπλα σε ένα block.json, η επέκταση επικυρώνει κάθε πρόσβαση $a['key'] με βάση τα δηλωμένα γνωρίσματα του block.
<?php
echo $a['title']; // OK
echo $a['subtitle']; // OK
echo $a['typo']; // Error: Field "typo" does not exist in block.json
Η επέκταση γνωρίζει ότι το Blockstudio ορίζει τα $a, $attributes, $b, $block, $c, $context, $content, $isEditor, $isPreview και τις μεταβλητές island πριν συμπεριλάβει ένα πρότυπο. Έτσι, οι άμεσες αναγνώσεις όπως το $a['title'] δεν αναφέρονται ως πιθανώς μη ορισμένες, ενώ ο τύπος του $a προκύπτει από το block.json δίπλα στο πρότυπο. Η δομή διατηρείται κατά τη στένωση τύπου, οπότε τα $a['label'] ?? '', isset( $a['cta']['target'] ) και $a['cta']['title'] !== null διατηρούν τους δηλωμένους τύπους πεδίων· ένα πρότυπο που αναθέτει τιμή στο ίδιο το $a διατηρεί τον τύπο που του ανατέθηκε. Μην προσθέτετε docblock /** @var array<string, mixed> $a */: αντικαθιστά αυτή τη δομή με έναν ανοικτό πίνακα.
Τα κλειδιά πεδίων ακολουθούν τους κανόνες ισοπέδωσης χρόνου εκτέλεσης του Blockstudio. Τα tabs και τα ανώνυμα δοχεία group χωρίς id είναι μόνο για παρουσίαση, επομένως τα θυγατρικά τους πεδία παραμένουν στο γονικό εύρος. Μια ονομασμένη ομάδα προσθέτει το ID της ομάδας ως πρόθεμα στα θυγατρικά κλειδιά:
echo $a['heading']; // Anonymous group child.
echo $a['cta_text']; // "text" inside the named "cta" group.
Επαναχρησιμοποιήσιμα προσαρμοσμένα πεδία
Οι αναφορές custom/* που βασίζονται σε αρχεία αναπτύσσονται πριν ελεγχθούν τα κλειδιά προτύπων και οι δομές πινάκων. Η επέκταση διαβάζει το αντίστοιχο field.json και εφαρμόζει τους ίδιους κανόνες για idStructure, overrides, ένθετες αναφορές, ομάδες, καρτέλες και επαναλήπτες όπως το Blockstudio:
{
"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" }
}
}
]
}
}
Τα κλειδιά προτύπων που προκύπτουν είναι title και hero_description. Αναγνωρίζονται στα PHP, Twig, Blade, στις ετικέτες block και στα συναγόμενα σχήματα γνωρισμάτων.
Αν ένας ορισμός που βασίζεται σε αρχείο λείπει, είναι ασαφής, μη έγκυρος ή κυκλικός, εμφανίζεται συγκεκριμένο σφάλμα blockstudio.customField.*. Οι έλεγχοι εξαρτώμενων κλειδιών παραλείπονται για αυτό το block, ώστε ένας ανεπίλυτος ορισμός να μην προκαλεί δεύτερο κύμα σφαλμάτων για άγνωστα πεδία.
Οι ορισμοί που καταχωρίζονται μόνο κατά τον χρόνο εκτέλεσης μέσω του φίλτρου blockstudio/fields PHP δεν μπορούν να συναχθούν με στατική ανάλυση. Χρησιμοποιήστε έναν ορισμό field.json όταν το πεδίο πρέπει να συνεισφέρει κλειδιά προτύπων που ελέγχονται στατικά.
Πρόσβαση σε πρότυπα Twig
Τα πρότυπα Twig σαρώνονται αυτόματα. Δεν χρειάζεται σχολιασμός.
<h1>{{ a.title }}</h1>
<p>{{ a.typo }}</p> {# Error: Field "typo" does not exist in block.json #}
Πρόσβαση σε πρότυπα Blade
Τα πρότυπα Blade σαρώνονται με τον ίδιο τρόπο.
<h1>{{ $a['title'] }}</h1>
<p>{{ $a['typo'] }}</p> {{-- Error --}}
Επικύρωση ετικετών block
Οι ετικέτες block επικυρώνονται στα σημεία όπου τις διαβάζει το Blockstudio: στις ετικέτες <bs:> και <block>, στις ετικέτες προθεμάτων που έχουν διαμορφωθεί στο blockTags.prefixes (όπως το <acme-card>, με επίλυση κατά σειρά χώρου ονομάτων όπως κατά τον χρόνο εκτέλεσης) και στις ετικέτες ψευδωνύμων, στα πρότυπα block PHP, Twig και Blade, καθώς και στις διατάξεις σελίδων. Ελέγχονται επίσης οι πηγές σελίδων κάτω από το pages/ (index.php, index.html, index.twig, index.blade.php), συμπεριλαμβανομένων των στοιχείων HTML που το έργο αντιστοιχίζει σε block. Τα ενσωματωμένα block UI είναι γνωστά όταν είναι ενεργοποιημένο το ui.enabled.
<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) -->
Ένα γνώρισμα γίνεται δεκτό όταν το block το δηλώνει ως πεδίο (συμπεριλαμβανομένων προσαρμοσμένων πεδίων και πεδίων που ένα πεδίο τυποποιημένο ως block προωθεί κάτω από το idStructure του) ή όταν το Blockstudio το προωθεί στο ριζικό στοιχείο του block: τα data-*, aria-*, id, style, role, title, lang, dir, hidden και tabindex. Στα πρότυπα, κάθε γνώρισμα html-* περνάει αυτούσιο· στις πηγές σελίδων, ένα πρόθεμα html- δηλώνει μόνο ένα από τα προωθούμενα γνωρίσματα. Κάθε άλλο γνώρισμα, ιδίως ένα αδήλωτο class, αναφέρεται ως σφάλμα, επειδή το Blockstudio το αποθηκεύει και δεν το αποδίδει ποτέ.
Κατά τον χρόνο εκτέλεσης, τα φίλτρα PHP καταχωρίζουν αντιστοιχίσεις στοιχείων και ψευδώνυμα ετικετών, κάτι που δεν μπορεί να αξιολογήσει η στατική ανάλυση. Γι’ αυτό, η ανάλυση τα διαβάζει από το blockstudio.json. Το scanPhp ελέγχει επίσης ετικέτες σε άλλα PHP του έργου, όπως τη σήμανση συστατικών σε λειτουργικές μονάδες, χωρίς να αναφέρει άγνωστα block εκεί:
{
"phpstan": {
"blockTags": {
"elements": {
"section": "theme/section",
"h2": "theme/heading",
"div": [
{ "attribute": "width", "block": "theme/row" },
"theme/div"
]
},
"aliases": { "theme-button": "bsui/button" },
"scanPhp": true
}
}
}
Ένα στοιχείο αντιστοιχίζεται σε όνομα block ή σε κανόνες που δοκιμάζονται με τη σειρά: κερδίζει ο πρώτος κανόνας του οποίου το γνώρισμα φέρει το στοιχείο, ενώ ένα απλό όνομα block αντιστοιχίζεται πάντα. Τα στοιχεία που δεν αντιστοιχίζονται από το έργο διατηρούν το βασικό τους block και δεν ελέγχονται. Τα διαγνωστικά χρησιμοποιούν τα blockstudio.blockTag.unknown, blockstudio.blockTag.attribute και blockstudio.blockTag.class.
Τυποποίηση εγγραφών βάσης δεδομένων
Το Db::get() επιστρέφει μια τυποποιημένη παρουσία με βάση το σχήμα db.php. Οι δομές των εγγραφών συνάγονται αυτόματα.
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
Τα υποχρεωτικά πεδία δεν δέχονται null. Τα προαιρετικά πεδία έχουν τον τύπο type|null. Ένα πεδίο id (int) υπάρχει πάντα. Η ίδια τυποποίηση ισχύει και για τη σύνταξη του builder Blockstudio\\Db\\Schema / Blockstudio\\Db\\Field που βασίζεται στο PHP.
Επικύρωση διαδρομών ρυθμίσεων
Οι διαδρομές Settings::get() ελέγχονται με βάση το γνωστό σχήμα ρυθμίσεων.
Settings::get('tailwind/enabled'); // OK, returns bool
Settings::get('tailwind/enabld'); // Error: Did you mean "tailwind/enabled"?
Επικύρωση ονομάτων hook
Τα ονόματα φίλτρων και action hook του Blockstudio επικυρώνονται.
add_filter('blockstudio/render', $cb); // OK
add_filter('blockstudio/rendrr', $cb); // Error: Did you mean "blockstudio/render"?
Τα δυναμικά hook ρυθμίσεων, όπως το blockstudio/settings/tailwind/enabled, επιτρέπονται πάντα. Τα hook εκτός του blockstudio αγνοούνται.
Επικύρωση σχήματος
Η επέκταση επικυρώνει κάθε αρχείο σχήματος Blockstudio του έργου.
block.json:
- Λείπει το πεδίο
name - Λείπει το πεδίο
type - Λείπει το
idσε πεδία τιμών που το απαιτούν - Άγνωστοι τύποι πεδίων
- Ιδιότητες πεδίων που δεν γίνονται δεκτές από τον τύπο πεδίου, όπως το
"translat"αντί για το"translate", με πρόταση για την πλησιέστερη γνωστή ιδιότητα select/radio/checkboxχωρίςoptionsήpopulate- Διπλότυπα αναγνωριστικά πεδίων
- Πεδίο
tabsμέσα σε επαναλήπτη, απευθείας ή μέσα σε ομάδα χωρίςid - Μη έγκυρες δηλώσεις
pluginDependencies
Τα πεδία δοχείων, όπως τα group και tabs, καθώς και οι αναφορές πεδίων custom/*, μπορούν να παραλείπουν το id όταν απλώς αναπτύσσουν ή περιβάλλουν άλλα πεδία.
Οι ιδιότητες των πεδίων ελέγχονται σε σύγκριση με τις ιδιότητες που δηλώνει το schemas/block.json για κάθε ενσωματωμένο τύπο πεδίου, καθώς και με τις ιδιότητες που δέχεται κάθε πεδίο. Οι ιδιότητες ειδικές για τα περιβλήματα στις αναφορές custom/* και οι τύποι πεδίων με ονόματα χώρου που ορίζονται από το έργο δεν περιλαμβάνονται σε αυτόν τον έλεγχο. Εξακολουθούν να ισχύουν οι υπάρχοντες έλεγχοι επικύρωσης τύπων πεδίων και προσαρμοσμένων αναφορών. Τα αναγνωριστικά είναι τα blockstudio.blockJson.property και blockstudio.fieldJson.property.
Αυτός ο έλεγχος εξετάζει τα ονόματα των ιδιοτήτων, όχι μόνο τις τιμές τους: το minimized είναι έγκυρο σε ένα επαναλαμβανόμενο πεδίο, αλλά επισημαίνεται σε ένα πεδίο κειμένου. Η συμπεριφορά του plugin κατά την εκτέλεση παραμένει αμετάβλητη. Αν ένα έργο προσθέτει σκόπιμα δικά του μεταδεδομένα σε ενσωματωμένα πεδία, καταργήστε μόνο αυτά τα ευρήματα, χωρίς να απενεργοποιήσετε άλλους ελέγχους δομής:
parameters:
ignoreErrors:
- identifier: blockstudio.blockJson.property
- identifier: blockstudio.fieldJson.property
Τα ενσωματωμένα πεδία μέσα σε ένα επαναχρησιμοποιήσιμο field.json εξακολουθούν να ελέγχονται, ακόμη κι όταν μια αναφορά custom/* έχει δικές της επιλογές περιβλήματος. Τα αρχεία επεκτάσεων δεν εμπίπτουν στο πεδίο εφαρμογής αυτών των διαγνωστικών για τα ονόματα ιδιοτήτων· οι κανόνες set που αφορούν συγκεκριμένες επεκτάσεις εξακολουθούν να ισχύουν.
field.json (προσαρμοσμένα επαναχρησιμοποιήσιμα πεδία):
- Απουσία
name - Απουσία ή κενό
attributes - Μη έγκυρα αντικείμενα ιδιοτήτων ή απουσία πεδίου
type - Απουσία
idσε πεδία τιμών που το απαιτούν - Άγνωστοι τύποι πεδίων
- Ιδιότητες που δεν δέχεται ο τύπος πεδίου
- Πεδίο
tabsμέσα σε επαναλαμβανόμενο πεδίο, απευθείας ή μέσα σε ομάδα χωρίςid - Απουσία, αμφισημία, μη εγκυρότητα ή κυκλικότητα στις ένθετες αναφορές
custom/*
Επέκταση JSON (επεκτάσεις block στο extensions/):
- Λείπει το
name(block-στόχος) - Λείπει το κλειδί
blockstudio - Λείπει το κλειδί
blockstudio.extend
page.json (σελίδες βάσει αρχείων):
- Λείπει το
title - Λείπει το
slug - Μη έγκυρες τιμές
postStatus
db.php:
- Λείπει ο πίνακας
fields - Μη έγκυροι τύποι πεδίων
- Υποστηρίζονται τόσο πίνακες παλαιού τύπου όσο και
Blockstudio\\Db\\Schema/Blockstudio\\Db\\Field
rpc.php:
- Μη έγκυρες μέθοδοι HTTP
- Εσφαλμένη τιμή
public(πρέπει να είναιtrue,falseή'open') - Υποστηρίζονται τόσο πίνακες παλαιού τύπου όσο και επιστροφές αντικειμένων με γνωρίσματα
cron.php:
- Λείπει το
scheduleστις διαμορφωμένες εργασίες - Λείπει το
callbackστις διαμορφωμένες εργασίες - Υποστηρίζονται τόσο πίνακες παλαιού τύπου όσο και επιστροφές αντικειμένων με γνωρίσματα
blockstudio.json:
- Συντομογραφίες boolean όπως
"tailwind": true(πρέπει να χρησιμοποιείται η ένθετη μορφή αντικειμένου{"enabled": true, "config": ""})
Διαμόρφωση
Η επέκταση εντοπίζει από προεπιλογή αρχεία Blockstudio στο έργο που αναλύεται.
Όταν ένα έργο χρησιμοποιεί μπλοκ ή επαναχρησιμοποιήσιμα πεδία από βιβλιοθήκη εκτός της ρίζας
του έργου, προσθέστε τη διαδρομή της βιβλιοθήκης στο blockstudioScanRoots. Η διαδρομή
σαρώνεται τόσο για ορισμούς block.json όσο και για field.json, ώστε οι εξωτερικές ετικέτες μπλοκ
και τα προσαρμοσμένα πεδία τους να μπορούν να επικυρωθούν μαζί.
parameters:
blockstudioScanRoots:
- vendor/acme/block-library/blockstudio
Για να αγνοήσετε αρχεία, χρησιμοποιήστε την τυπική διαμόρφωση excludePaths του PHPStan.
Προκαθορισμένες ρυθμίσεις ανάλυσης
Η επέκταση που εντοπίζεται αυτόματα παραμένει η βάση για ασφαλή συμβατότητα. Το Blockstudio 7.6 προσθέτει προαιρετικά επίπεδα χωρίς να αλλάζει τα υπάρχοντα έργα:
| Προκαθορισμένη ρύθμιση | Συμπεριφορά |
|---|---|
base.neon |
Ανάλυση υπάρχοντος σχήματος, προτύπων, hooks, ρυθμίσεων και API. |
theme.neon |
Η βάση συν ρίζες θέματος WordPress, κεφαλίδες στυλ, στοιχεία Blockstudio, περιορισμό εμβέλειας επιλογέα, προεπιλεγμένες τιμές πεδίων και όρια επαναλήπτη. |
extreme-theme.neon |
Το θέμα συν PHPStan max, μη ασφαλές PHP, διαφυγή εξόδου, Tailwind, JavaScript και ελέγχους API διαδραστικότητας. |
wordpress-render.neon |
Το ακραίο θέμα συν ζωντανό ανιχνευτή απόδοσης WordPress που παρέχεται από τον καλούντα. |
Η εγκατάσταση του blockstudio/phpstan ενεργοποιεί μόνο τη βασική επέκταση. Συμπεριλάβετε ένα
προαιρετικό επίπεδο σε υπάρχουσα διαμόρφωση PHPStan:
includes:
- vendor/blockstudio/phpstan/extreme-theme.neon
parameters:
blockstudioThemeRoots:
- .
blockstudioThemeExcludePaths:
- fixtures/**
blockstudioThemeMaxFiles: 10000
blockstudioExtremeJavaScript: true
blockstudioExtremeTailwind: true
Το blockstudioThemeExcludePaths ελέγχει τον σαρωτή θεμάτων.
Η τυπική διαμόρφωση excludePaths του PHPStan ελέγχει ανεξάρτητα την ανάλυση PHP.
Η ρύθμιση phpstan.excludePaths της κανονικής εντολής στο blockstudio.json
(και η επιλογή --exclude της) διαμορφώνει και τα δύο επίπεδα. Τα σχετικά μοτίβα επιλύονται
σε σχέση με κάθε ρυθμισμένη ρίζα, επομένως καταχωρίσεις όπως vendor/** περιορίζουν τόσο την ανάλυση PHPStan
όσο και τη σάρωση έργου του Blockstudio.
Ένα μοτίβο που ορίζει έναν μεμονωμένο κατάλογο, όπως το _dist/** ή το node_modules/**,
εξαιρεί αυτόν τον κατάλογο όπου κι αν βρίσκεται, όχι μόνο δίπλα στη ρίζα του θέματος. Ένα
μοτίβο που περιέχει κάθετο, όπως το assets/*/docs/**, παραμένει αγκυρωμένο στη
ρίζα. Τα παραγόμενα στοιχεία μπλοκ βρίσκονται σε κατάλογο _dist μέσα σε κάθε μπλοκ, επομένως
η μορφή μεμονωμένου καταλόγου είναι αυτή που κρατά το μεταγλωττισμένο αποτέλεσμα εκτός ανάλυσης.
Κανονική εντολή
Το πακέτο εγκαθιστά το vendor/bin/blockstudio-phpstan ως εκτελέσιμο ανάλυσης.
Εκτελεί την προκαθορισμένη ρύθμιση base, εκτός αν το έργο επιλέξει κάποια άλλη, επομένως
η εγκατάσταση του πακέτου δεν ενεργοποιεί από μόνη της τα επίπεδα θέματος ή ακραίου θέματος:
vendor/bin/blockstudio-phpstan --root . -- --no-progress
Οι προκαθορισμένες ρυθμίσεις περιλαμβάνουν οι ίδιες την επέκταση. Μην προσθέτετε
το phpstan/extension-installer σε έργο που εκτελεί την κανονική εντολή:
με τον εγκαταστάτη παρόντα, το extension.neon φορτώνεται δύο φορές και το PHPStan σταματά
με το «This file is included multiple times» πριν από οποιαδήποτε ανάλυση.
Η εντολή ορίζει από προεπιλογή για το PHPStan ένα όριο μνήμης 1G, ώστε τα έργα WordPress που διαχειρίζεται το Composer
να μην κληρονομούν το συνηθισμένο όριο CLI του 128M. Περάστε μια ρητή επιλογή PHPStan μετά το -- για να το παρακάμψετε, όπως
το -- --memory-limit=512M --no-progress.
Υιοθέτηση της ανάλυσης σε υπάρχον έργο
Ένα έργο που δεν έχει αναλυθεί ποτέ συνήθως εμφανίζει ευρήματα στην πρώτη
εκτέλεση. Αντί να υποβαθμίσετε την προκαθορισμένη ρύθμιση, δημιουργήστε μια γραμμή βάσης PHPStan και ορίστε το phpstan.configuration σε διαμόρφωση έργου που την περιλαμβάνει. Ο νέος κώδικας
θα υπόκειται έτσι στην πλήρη προκαθορισμένη ρύθμιση, ενώ τα καταγεγραμμένα ευρήματα δεν θα παρεμβάλλονται:
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
includes:
- phpstan-baseline.neon
parameters:
level: max
{
"phpstan": {
"configuration": "phpstan.neon"
}
}
Διατηρήστε τη γραμμή level για τις προκαθορισμένες ρυθμίσεις base και theme. Η κανονική εντολή
ορίζει για αυτές το επίπεδο max μόνο όταν δεν περιλαμβάνεται διαμόρφωση έργου, και
χωρίς επίπεδο το PHPStan σταματά με το «No rules detected». Η προκαθορισμένη ρύθμιση extreme-theme
ορίζει μόνη της το επίπεδο max.
Οι σχετικές διαδρομές επιλύονται από το blockstudio.json. Τόσο η κανονική εντολή όσο και το
διαχειριζόμενο hook commit εντοπίζουν το αρχείο, οπότε το hook αποτρέπει νέα ευρήματα χωρίς
να απαιτείται πρώτα να διορθωθούν τα υπάρχοντα.
Διατηρήστε τις προεπιλογές εντολών για όλο το έργο στο blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["fixtures/**"],
"maxFiles": 10000
}
}
Οι σχετικές ρίζες επιλύονται από το αρχείο που τις δηλώνει. Οι ρητές τιμές CLI
αντικαθιστούν τις αντίστοιχες τιμές JSON. Περάστε το
--blockstudio-json path/to/project.json για εναλλακτική πηγή διαμόρφωσης.
Οι κακοσχηματισμένες JSON, τα μη υποστηριζόμενα κλειδιά phpstan, οι μη έγκυρες τιμές και η
έλλειψη ρητής πηγής προκαλούν με ντετερμινιστικό τρόπο αποτυχία με κωδικό εξόδου 2.
Επιλέξτε άλλη προκαθορισμένη ρύθμιση, συμπεριλάβετε διαμόρφωση έργου, προσθέστε επαναλαμβανόμενες ρίζες και εξαιρέσεις ή ζητήστε από το PHPStan JSON:
vendor/bin/blockstudio-phpstan \
--preset theme \
--configuration phpstan.neon \
--root . \
--exclude 'fixtures/**' \
--max-files 10000 \
--error-format json \
-- --no-progress
Το περιτύλιγμα συνθέτει τη διαμόρφωση στον προσωρινό κατάλογο του συστήματος και τον διαγράφει κατά την έξοδο. Δεν γράφει παραγόμενη διαμόρφωση, γραμμές βάσης, hooks ή κρυφές μνήμες στο έργο που αναλύεται. Οι καλούντες μπορούν και πάλι να διαμορφώσουν ρητά τη συνήθη κρυφή μνήμη του PHPStan.
Η σύμβαση κωδικών εξόδου είναι:
0όταν η ανάλυση ολοκληρωθεί επιτυχώς1όταν το PHPStan αναφέρει διαγνωστικά μηνύματα2για μη έγκυρη χρήση, διαμόρφωση ή εκτέλεση διεργασίας
Διαχειριζόμενο άγκιστρο commit
Για να κάνετε την ανάλυση ακραίου θέματος κριτήριο αποδοχής commit στο αποθετήριο, ενεργοποιήστε το hook που διαχειρίζεται το Blockstudio στο blockstudio.json:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": [],
"maxFiles": 10000
},
"githooks": {
"commit": true
}
}
Συγχρονίστε το μετά την εγκατάσταση εξαρτήσεων ή την αλλαγή της ρύθμισης:
vendor/bin/blockstudio-githooks sync
Η εντολή γράφει το παραγόμενο hook pre-commit και την εγγραφή ιδιοκτησίας μέσα
στον κοινό κατάλογο του Git, ορίζει το core.hooksPath στον κατάλογο του διαχειριζόμενου hook
και συνδέει με ασφάλεια το προηγουμένως διαμορφωμένο hook pre-commit. Οι επαναλαμβανόμενοι συγχρονισμοί
ανανεώνουν μόνο το παραγόμενο αρχείο, ώστε οι αναβαθμίσεις πακέτου να είναι idempotent.
Ορίστε το commit σε false, αφαιρέστε το ή αφαιρέστε το blockstudio.json και, στη συνέχεια, εκτελέστε
το sync για να επαναφέρετε την καταγεγραμμένη διαδρομή hook και να διαγράψετε μόνο αρχεία
που ανήκουν στο Blockstudio. Μπορείτε επίσης να εκτελέσετε:
vendor/bin/blockstudio-githooks remove
Τα αρχεία που ανήκουν στον χρήστη δεν αντικαθίστανται ούτε διαγράφονται ποτέ. Αν κάποιος αλλάξει
το core.hooksPath αφού ενεργοποιηθεί το Blockstudio, κατά την αφαίρεση διατηρείται η νεότερη
ρύθμιση. Το παραγόμενο hook υποστηρίζει συνδεδεμένα αντίγραφα εργασίας Git και διαδρομές που περιέχουν
κενά, επιλύοντας το ενεργό αποθετήριο και τη ρίζα του έργου κατά το commit. Εκτελεί
την κανονική εντολή από αυτή τη ρίζα, ώστε το ίδιο αντικείμενο phpstan να ελέγχει
τις διαδραστικές εκτελέσεις και τα commit χωρίς διπλότυπα ορίσματα που παράγονται αυτόματα.
Το hook εκτελεί μόνο το vendor/bin/blockstudio-phpstan. Το Blockstudio δεν εκτελεί
μορφοποιητή και το hook δεν ξαναγράφει ποτέ αρχεία του έργου. Οι ελλείπουσες εξαρτήσεις και οι αποτυχίες
ανάλυσης μπλοκάρουν το commit με σαφές μήνυμα σφάλματος.
Ζωντανή απόδοση WordPress
Το ζωντανό επίπεδο απαιτεί ρητή ενεργοποίηση. Ο καλών έχει την ευθύνη για το περιβάλλον WordPress και παρέχει έναν πίνακα argv:
vendor/bin/blockstudio-phpstan \
--preset wordpress-render \
--render-command='["wp","eval-file","tools/render-probe.php"]' \
--render-working-directory=. \
--render-timeout=60 \
--root .
Η εντολή εκτελείται χωρίς κέλυφος και πρέπει να εμφανίσει ένα αντικείμενο JSON:
{"ok":true}
Ένας ανιχνευτής μπορεί να αναφέρει ένα στοχευμένο σφάλμα:
{
"ok": false,
"message": "Rendered block failed.",
"file": "/absolute/path/to/block.json",
"line": 12
}
Έξοδοι με μη μηδενική τιμή, λήξεις χρονικού ορίου, κακοσχηματισμένο JSON και ok: false παράγουν
blockstudio.wordpress.render.
Το blockstudio.javascript.domContract αναφέρει έναν επιλογέα ιδιότητας [data-*] που ένα σενάριο περνά στο querySelector(), στο querySelectorAll(), στο closest() ή στο matches(), όταν καμία επισημασμένη σήμανση δεν φέρει αυτή την ιδιότητα. Σήμανση είναι κάθε αρχείο PHP, Twig, Blade και HTML, καθώς και κάθε στοιχείο React .tsx και .jsx μέσα στις ρίζες που αναλύονται, εξαιρουμένων των διαδρομών που έχουν εξαιρεθεί. Τα στοιχεία αναλύονται: τα ονόματα ιδιοτήτων JSX λαμβάνονται υπόψη, όπως και τα κλειδιά συμβολοσειρών σε κυριολεκτικά αντικείμενα. Επομένως, ένα αντικείμενο ιδιοτήτων που εφαρμόζεται σε ένα στοιχείο μέσω διασποράς ικανοποιεί τον επιλογέα, ενώ τα ονόματα κλάσεων και οι άλλες τιμές ιδιοτήτων όχι.
Οι έλεγχοι του Interactivity API διαβάζουν τα ίδια στοιχεία React. Ένας χώρος ονομάτων data-wp-interactive σε στοιχείο JSX θεωρείται αναφορά προτύπου για το blockstudio.interactivity.orphan, ενώ οι οδηγίες data-wp-* μέσα σε αυτό επιλύονται με βάση τον πλησιέστερο γονικό χώρο ονομάτων ή ένα πρόθεμα namespace:: στην τιμή. Οι οδηγίες με στατική τιμή συμβολοσειράς, γραμμένες ως ιδιότητα JSX ή ως κλειδί συμβολοσειράς ενός αντικειμένου ιδιοτήτων, πρέπει να αντιστοιχούν σε υπάρχοντες χειριστές και διαδρομές του store (blockstudio.interactivity.handler, blockstudio.interactivity.binding), ενώ ο κώδικας του store δεν πρέπει να τροποποιεί τις ιδιότητες και τις κλάσεις με τις οποίες συνδέεται (blockstudio.interactivity.derivedState). Το React διαφεύγει τις τιμές ιδιοτήτων, επομένως το data-wp-context σε στοιχείο δεν αναφέρεται, ενώ οι δυναμικές τιμές δεν ελέγχονται. Οι χώροι ονομάτων κάτω από το bsui/ ανήκουν στα ενσωματωμένα μπλοκ UI, των οποίων τα stores διατίθενται μαζί με το Blockstudio έξω από τις ρίζες που αναλύονται, επομένως δεν είναι ποτέ ορφανά.
Αναγνωριστικά διαγνωστικών μηνυμάτων
Τα νέα διαγνωστικά μηνύματα των προκαθορισμένων ρυθμίσεων διατηρούν σταθερά αναγνωριστικά blockstudio.*:
- Δομή θέματος:
blockstudio.theme.root.missing,blockstudio.theme.style.missing,blockstudio.theme.style.header,blockstudio.theme.scanLimit - Στοιχεία και πεδία:
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 - Διαδραστικότητα:
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
Απόδοση
Ο σαρωτής δέχεται συνήθεις καταλόγους, αποφεύγει διπλότυπες ρίζες, παραλείπει δέντρα εξαρτήσεων/δομής/κρυφής μνήμης, αποθηκεύει τις αναγνώσεις αρχείων στην κύρια μνήμη και ταξινομεί ντετερμινιστικά τα διαγνωστικά μηνύματα. Διατηρήστε τις ρίζες περιορισμένες, εξαιρέστε δέντρα δοκιμών και παραγόμενων αρχείων και ορίστε όριο αρχείων για μεγάλα αποθετήρια. Τα JavaScript και Tailwind μπορούν να απενεργοποιηθούν ανεξάρτητα. Η ζωντανή απόδοση εκτελείται μόνο αν επιλεγεί η αντίστοιχη προκαθορισμένη ρύθμιση.
Τα διαγνωστικά μηνύματα θέματος, JavaScript και Tailwind αναφέρονται μέσω της κρυφής μνήμης αποτελεσμάτων του PHPStan.
Μετά την αλλαγή μόνο ενός block.json ή ενός script, μια θερμή
κρυφή μνήμη μπορεί να αναφέρει το προηγούμενο αποτέλεσμα. Περάστε το
--debug μετά το -- για να παρακάμψετε την κρυφή μνήμη κατά την επαλήθευση τέτοιων αλλαγών.
Σύμβαση έργου για πράκτορες προγραμματισμού
Το πακέτο εγκαθιστά ένα τρίτο εκτελέσιμο, το vendor/bin/blockstudio-agents. Αυτό
γράφει ένα AGENTS.md που περιγράφει το έργο μέσα στο οποίο εκτελείται και παρέχει ό,τι χρειάζεται ένας
πράκτορας προγραμματισμού πριν πειράξει οτιδήποτε: τι δημιουργεί το έργο, ποιες
λειτουργίες Blockstudio είναι ενεργοποιημένες, τι θα απορρίψει η ανάλυση και ποιες εντολές
ισχύουν.
vendor/bin/blockstudio-agents
Blockstudio contract created: /path/to/project/AGENTS.md
Τίποτα στην έξοδο δεν προέρχεται από σταθερό πρότυπο. Κάθε γραμμή προκύπτει από μία από τρεις πηγές:
- Τα αρχεία του ίδιου του έργου. Ένα θέμα με κεφαλίδα
style.css, μπλοκ και σελίδες που βασίζονται σε αρχεία παράγει διαφορετικό έγγραφο από ένα πρόσθετο που καταχωρίζει μόνο μπλοκ. Οι μετρήσεις, οι κατάλογοι, οι χώροι ονομάτων των μπλοκ και οι γλώσσες προτύπων είναι όσα εντόπισε πραγματικά ο σαρωτής, με τις ίδιες ρίζες και εξαιρέσεις όπως στην ανάλυση. blockstudio.json. Περιγράφονται μόνο οι ενεργοποιημένες λειτουργίες, μαζί με τις διαμορφωμένες τιμές τους: προθέματα ετικετών μπλοκ και οι χώροι ονομάτων μέσω των οποίων επιλύονται, Tailwind, το ενσωματωμένο UI, η επαναφορά στοιχείων του επεξεργαστή, η διαδρομή κρυφής μνήμης, το προφίλ απόδοσης, η στατική προαπόδοση και οι δυναμικές διαδρομές της, οι προεπιλογές θέματος, το Content Sync και το hook commit.- Η επιλεγμένη προκαθορισμένη ρύθμιση
phpstan.preset. Η ενότητα ορθότητας διαβάζεται από τα ίδια τα αρχεία προκαθορισμένων ρυθμίσεων, επίπεδο προς επίπεδο, ώστε να παρατίθενται ακριβώς οι κανόνες που καταχωρίζει η ρύθμιση. Στοbaseπεριγράφονται οι κανόνες σχήματος, προτύπων, hook και ρυθμίσεων. Στοextreme-themeπεριγράφονται επίσης οι κανόνες δομής θέματος, οι αυστηρές σημαίες PHPStan, το μη ασφαλές PHP, η διαφυγή εξόδου, το Tailwind και το JavaScript. Όταν προστίθεται κανόνας σε μια προκαθορισμένη ρύθμιση, ενημερώνεται και το παραγόμενο έγγραφο.
Η ενότητα εντολών ακολουθεί την ίδια αρχή. Το wp bs prerender status
εμφανίζεται όταν είναι ενεργή η στατική προαπόδοση, το vendor/bin/blockstudio-githooks sync όταν έχει οριστεί το githooks.commit και το wp bs db schemas όταν το έργο
έχει πράγματι db.php.
| Επιλογή | Συμπεριφορά |
|---|---|
--root <path> |
Ρίζα έργου (προεπιλογή: τρέχων κατάλογος) |
--config <path> |
Διαδρομή blockstudio.json (προεπιλογή: <root>/blockstudio.json) |
--output <path> |
Διαδρομή σύμβασης (προεπιλογή: <root>/AGENTS.md) |
--stdout |
Εκτύπωση της σύμβασης αντί για εγγραφή της |
--check |
Έξοδος με 1 όταν η σύμβαση στον δίσκο δεν είναι ενημερωμένη |
--force |
Αντικατάσταση αρχείου που δεν ανήκει στο Blockstudio |
Το --check κάνει τη σύμβαση πύλη CI, όπως το hook commit κάνει το ίδιο για
την ανάλυση:
vendor/bin/blockstudio-agents --check
Ιδιοκτησία
Το παραγόμενο αρχείο φέρει τον ίδιο τύπο δείκτη με το διαχειριζόμενο hook commit,
και ισχύει ο ίδιος κανόνας: το Blockstudio δεν αντικαθιστά ποτέ αρχείο που δεν έχει γράψει.
Ένα AGENTS.md που προϋπήρχε της εντολής ή γράφτηκε χειροκίνητα από συντάκτη απορρίπτεται με κωδικό εξόδου 2 και μένει ανέπαφο μέχρι να περαστεί το --force.
Η αναδημιουργία είναι ασφαλής. Το αρχείο τελειώνει με μια περιοχή σημειώσεων και τα byte ανάμεσα στους δείκτες της διατηρούνται σε κάθε αναδημιουργία:
## Project notes
<!-- blockstudio:notes:start -->
Deploys run from the release branch only.
<!-- blockstudio:notes:end -->
Οι κωδικοί εξόδου είναι 0 όταν γράφεται, είναι ενημερωμένη ή εκτυπώνεται η σύμβαση, 1 όταν
το --check εντοπίζει παρωχημένη σύμβαση και 2 για σφάλματα χρήσης, διαμόρφωσης ή
συστήματος αρχείων.
Μορφές τύπων πεδίων
Η επέκταση αντιστοιχίζει κάθε τύπο πεδίου Blockstudio σε συγκεκριμένο τύπο PHP:
| Τύπος πεδίου | Τύπος PHP |
|---|---|
text, textarea, richtext, wysiwyg, code |
string |
date, datetime, classes, html-tag, unit, gradient |
string |
number, range |
int|float |
toggle |
bool |
select, radio, checkbox (μονό) |
string|int |
select, checkbox (πολλαπλό) |
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 (μονό) |
array{id: int, url: string, alt: string|null, mime_type: string|null} |
files (πολλαπλό) |
list<array{id: int, url: string, ...}> |
group |
Οι ομάδες με όνομα χρησιμοποιούν προθέματα κάτω παύλας· οι ανώνυμες ομάδες ισοπεδώνονται στην γονική εμβέλεια |
repeater |
list<array{...child fields...}> |
tabs |
Ισοπεδώνεται στην γονική εμβέλεια |
Stubs API
Η επέκταση περιλαμβάνει stubs για ολόκληρο το δημόσιο API του Blockstudio:
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()
Αυτά παρέχουν αυτόματη συμπλήρωση και έλεγχο τύπων χωρίς να χρειάζεται ο πηγαίος κώδικας του πρόσθετου Blockstudio στον υπολογιστή σας.
Απαιτήσεις
- PHP 8.2+
- PHPStan 2.1.47+
phpstan/extension-installer(συνιστάται για αυτόματο εντοπισμό)
Το πακέτο εγκαθιστά αυτόματα τον πάροχο συμβατότητας BC Math. Επομένως, το εγγενές
ext-bcmath είναι προαιρετικό, ακόμη και για νέα θέματα που δημιουργούνται με ενεργοποιημένους
ελέγχους JavaScript μέσω της προκαθορισμένης ρύθμισης θέματος ή ακραίου θέματος.