Ελεγμένα πρότυπα με PHPStan και παραγόμενο AGENTS.md
Ένα block Blockstudio αποτελείται από δύο αρχεία που πρέπει να συμφωνούν. Το block.json δηλώνει τα πεδία και το πρότυπο τα διαβάζει ως $a['id']. Τίποτα κατά τον χρόνο εκτέλεσης δεν εμποδίζει το πρότυπο να διαβάσει ένα κλειδί που μετονομάστηκε, δεν δηλώθηκε ποτέ ή γράφτηκε λάθος. Απλώς αποδίδεται κενή συμβολοσειρά και το λάθος γίνεται αντιληπτό όταν κάποιος παρατηρήσει μια κενή επικεφαλίδα σε δημοσιευμένη σελίδα. Το ίδιο ισχύει για τη διαφυγή εξόδου: ένα μη διαφυγμένο echo λειτουργεί άψογα μέχρι η τιμή ενός πεδίου να περιέχει σήμανση.
Το πακέτο blockstudio/phpstan μεταφέρει και τα δύο προβλήματα στη φάση ανάλυσης. Διαβάζει τα αρχεία block.json, τυποποιεί τα $a από αυτά και αναφέρει αναγνώσεις προτύπων που δεν αντιστοιχούν. Οι προαιρετικές ρυθμίσεις προσθέτουν κανόνες δομής θέματος, διαφυγή εξόδου και ελέγχους JavaScript και Tailwind. Το ίδιο πακέτο περιλαμβάνει δύο συνοδευτικά εργαλεία: ένα διαχειριζόμενο hook προ-commit που εκτελεί την ανάλυση και μια γεννήτρια που δημιουργεί ένα AGENTS.md με πληροφορίες για το έργο σας, για τους coding agents.
Αυτός ο οδηγός δημιουργεί ένα μικρό θέμα, χαλάει επίτηδες ένα από τα πρότυπά του, εξετάζει την έξοδο της ανάλυσης, το διορθώνει και έπειτα ρυθμίζει την πύλη commit και το συμβόλαιο agent.
Ρύθμιση του θέματος
Ξεκινήστε με έναν φάκελο θέματος που περιέχει μια κεφαλίδα style.css, ένα composer.json και ένα block:
acme/
├── blockstudio/
│ └── hero/
│ ├── block.json
│ └── index.php
├── blockstudio.json
├── composer.json
└── style.css
/*
Theme Name: Acme
*/
Εγκαταστήστε το πακέτο ως εξάρτηση ανάπτυξης:
composer require --dev blockstudio/phpstan
Εγκαθιστά τα stubs των WordPress από το szepeviktor/phpstan-wordpress και το PHPStan, καθώς και τρία εκτελέσιμα στο vendor/bin: blockstudio-phpstan, blockstudio-githooks και blockstudio-agents.
Έπειτα ορίστε τι θα εκτελεί η ανάλυση. Οι προεπιλεγμένες ρυθμίσεις για όλο το έργο βρίσκονται στο αντικείμενο phpstan του blockstudio.json, ώστε οι διαδραστικές εκτελέσεις, το CI και το hook commit να χρησιμοποιούν τις ίδιες ρυθμίσεις:
{
"$schema": "https://blockstudio.dev/schema/blockstudio",
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["vendor/**"]
},
"githooks": {
"commit": true
}
}
Το extreme-theme είναι η αυστηρότερη από τις τρεις στατικές προεπιλογές. Ο παρακάτω πίνακας εξηγεί τι προσθέτει καθεμία. Το excludePaths κρατά τα ίδια τα αρχεία του Composer εκτός της σάρωσης Blockstudio και της ανάλυσης PHP.
Σπάστε επίτηδες ένα πρότυπο
Το hero block δηλώνει ένα μόνο πεδίο:
{
"$schema": "https://blockstudio.dev/schema/block",
"apiVersion": 3,
"name": "acme/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{ "id": "heading", "type": "text", "label": "Heading", "default": "" }
]
}
}
Το πρότυπο διαβάζει σωστά αυτό το πεδίο, έπειτα διαβάζει ένα subtitle που το block δεν δήλωσε ποτέ και το εμφανίζει χωρίς διαφυγή:
<section useBlockProps>
<h1><?php echo esc_html( $a['heading'] ); ?></h1>
<p><?php echo $a['subtitle']; ?></p>
</section>
Στον επεξεργαστή και στο frontend, αυτό αποδίδει μια κενή παράγραφο χωρίς σφάλμα. Εκτελέστε την ανάλυση:
vendor/bin/blockstudio-phpstan -- --no-progress
------ -------------------------------------------------------------------
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
Η εντολή τερματίζεται με 1. Ακολουθεί η ανάγνωση των διαγνωστικών, από το πιο συγκεκριμένο προς το γενικότερο:
- Το
blockstudio.fieldείναι ο κανόνας προτύπων. Εντόπισε τοblock.jsonδίπλα στο πρότυπο, προσδιόρισε τα πεδία του και διαπίστωσε ότι τοsubtitleδεν είναι ένα από αυτά. - Το
offsetAccess.notFoundκαταλήγει στο ίδιο συμπέρασμα, επειδή η επέκταση δίνει στο$aτη συγκεκριμένη δομήarray{heading: string}που προκύπτει από τοblock.json. Κάθε τύπος πεδίου αντιστοιχεί σε τύπο PHP: τοtextείναιstring, τοtoggleείναιboolκαι ένα repeater είναι πίνακας με δομές γραμμών. Το PHPStan καταλήγει στο ίδιο συμπέρασμα. - Το
blockstudio.output.unescapedπροέρχεται από το επίπεδοextreme-theme. Οι τιμές γνωρισμάτων που εμφανίζονται πρέπει να περνούν από συνάρτηση διαφυγής όπως ηesc_html(), ηesc_attr(), ηesc_url()ή ηwp_kses_post(). - Το
echo.nonStringπροκύπτει από το άγνωστο κλειδί: ένα offset που δεν υπάρχει δεν έχει τύπο συμβολοσειράς για εμφάνιση. - Το
variable.undefinedεμφανίζεται επειδή το PHPStan βλέπει ένα αρχείο προτύπου και όχι τη συνάρτηση απόδοσης που ορίζει το$aπριν το συμπεριλάβει. Η ενότητα επιδιόρθωσης καλύπτει αυτό το ζήτημα.
Διόρθωση
Αποφασίστε αν το subtitle είναι πραγματικό πεδίο. Εδώ είναι, οπότε δηλώστε το με default, καθώς το επίπεδο θέματος απαιτεί ένα σε κάθε πεδίο:
{
"$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": "" }
]
}
}
Διαφύγετε την έξοδο και δηλώστε το $a με τη δομή που συνάγει η επέκταση:
<?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>
vendor/bin/blockstudio-phpstan -- --no-progress
[OK] No errors
Γράψτε τη δήλωση τύπου με την ακριβή δομή. Η κανονική εντολή εκτελεί το PHPStan στο επίπεδο max, όπου ένα πιο χαλαρό @var array<string, mixed> $a απορρίπτεται με varTag.nativeType («Η ετικέτα PHPDoc @var με τύπο array<string, mixed> δεν είναι υποτύπος του εγγενούς τύπου array{heading: string, subtitle: string}»). Στην έκδοση 7.6 διευρύνεται επίσης κάθε πεδίο σε mixed, οπότε κάθε κλήση esc_html() αναφέρει argument.type. Το μήνυμα varTag.nativeType εμφανίζει τη δομή που συνάγεται, επομένως είναι και ο γρηγορότερος τρόπος να βρείτε τη δήλωση που πρέπει να αντιγράψετε.
Το Blockstudio 7.7 θεωρεί ότι το $a είναι ορισμένο μέσα στα πρότυπα block, οπότε τα διαγνωστικά variable.undefined εξαφανίζονται και η δήλωση τύπου γίνεται προαιρετική. Στην έκδοση 7.7, το παραπάνω ελαττωματικό πρότυπο αναφέρει τέσσερα σφάλματα αντί για έξι, ενώ το διορθωμένο περνά χωρίς τη γραμμή @var.
Επιλογή προεπιλογής
Η εγκατάσταση του πακέτου ενεργοποιεί μόνο τη βασική επέκταση. Η κανονική εντολή εκτελεί το base, εκτός αν το έργο επιλέξει άλλη προεπιλογή, επομένως η προσθήκη της εξάρτησης δεν ενεργοποιεί από μόνη της τα αυστηρότερα επίπεδα.
| Προεπιλογή | Προσθέτει |
|---|---|
base |
Πρόσβαση σε πεδία προτύπων στα PHP, Twig και Blade, έλεγχοι ετικετών block, επικύρωση σχήματος για block.json, field.json, page.json, επέκταση JSON, db.php, rpc.php και cron.php, διαδρομές Settings::get() και ονόματα hook blockstudio/*. |
theme |
Βασική προεπιλογή μαζί με ρίζες θέματος και κεφαλίδες style.css, στοιχεία ενεργητικού δηλωμένα στο block.json αντί να προστίθενται χειροκίνητα στην ουρά, εμβέλεια %selector% στο style.scss, προεπιλεγμένες τιμές πεδίων και όρια repeater. |
extreme-theme |
Θέμα μαζί με αυστηρές σημαίες PHPStan, απαγόρευση κλήσεων shell και eval(), απευθείας εγγραφές $wpdb, διαφυγή εξόδου, Tailwind, JavaScript και ελέγχους API Interactivity. |
wordpress-render |
Ακραίο θέμα μαζί με ζωντανή δοκιμή απόδοσης που παρέχετε ως εντολή. |
Όταν δεν περιλαμβάνεται διαμόρφωση έργου, η κανονική εντολή εκτελεί επίσης τα base και theme στο επίπεδο PHPStan max· το extreme-theme ορίζει το ίδιο το max. Κάθε διαγνωστικό προεπιλογής έχει σταθερό αναγνωριστικό blockstudio.*, που παρατίθεται στην αναφορά PHPStan.
Τα επίπεδα θέματος και extreme εξετάζουν και αρχεία PHP. Με ένα πεδίο χωρίς το default του και ένα script.js που γράφει στην κονσόλα, η ίδια εντολή αναφέρει:
------ -----------------------------------------------------------
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
------ ------------------------------------------------------------
Αυτοί οι έλεγχοι αναφέρονται μέσω της προσωρινής μνήμης αποτελεσμάτων του PHPStan. Μετά την επεξεργασία μόνο ενός block.json ή ενός script, μια ενημερωμένη προσωρινή μνήμη μπορεί να αναφέρει [OK] No errors για την παλιά κατάσταση. Περάστε το --debug μετά το --, παρακάμπτοντας την προσωρινή μνήμη, πριν βασιστείτε σε επιτυχημένη εκτέλεση για αλλαγές που δεν αφορούν το PHP:
vendor/bin/blockstudio-phpstan -- --no-progress --debug
Επιλογές εντολής και κωδικοί εξόδου
Οι τιμές γραμμής εντολών αντικαθιστούν τις αντίστοιχες τιμές blockstudio.json για μία εκτέλεση. Αντικατάσταση σημαίνει αντικατάσταση: αν περάσετε οποιοδήποτε --exclude, απορρίπτεται το διαμορφωμένο excludePaths, οπότε επαναλάβετε το vendor/** όταν προσθέτετε ένα:
vendor/bin/blockstudio-phpstan \
--preset theme \
--root . \
--exclude 'vendor/**' \
--exclude 'fixtures/**' \
--error-format json \
-- --no-progress
{"totals":{"errors":0,"file_errors":0},"files":{},"errors":[]}
Ό,τι ακολουθεί το -- περνά στο PHPStan. Το wrapper αυξάνει το όριο μνήμης του PHPStan σε 1G, εκτός αν περάσετε δικό σας --memory-limit, και συνθέτει τη διαμόρφωσή του στον προσωρινό κατάλογο συστήματος, ώστε να μη δημιουργείται κανένα αρχείο στο έργο. Τερματίζεται με 0 όταν η ανάλυση περάσει, με 1 όταν το PHPStan αναφέρει διαγνωστικά και με 2 σε περίπτωση σφάλματος χρήσης, διαμόρφωσης ή εκτέλεσης.
Εκτελέστε το μέσω της κανονικής εντολής αντί να προσθέσετε phpstan/extension-installer. Οι προεπιλογές περιλαμβάνουν ήδη την επέκταση και, όταν υπάρχει ο εγκαταστάτης, το ίδιο extension.neon φορτώνεται δύο φορές: το PHPStan σταματά με το μήνυμα «Αυτό το αρχείο περιλαμβάνεται πολλές φορές» πριν από οποιαδήποτε ανάλυση.
Υιοθέτηση σε υπάρχον έργο
Ένα έργο που αναλύεται για πρώτη φορά συνήθως έχει ευρήματα. Αντί να χαμηλώσετε την προεπιλογή, καταγράψτε τα σε μια βάση αναφοράς, ώστε ο πλήρης έλεγχος να εφαρμόζεται στον νέο κώδικα:
vendor/bin/blockstudio-phpstan -- --no-progress --generate-baseline=phpstan-baseline.neon
[OK] Baseline generated with 3 errors.
Συμπεριλάβετε τη βάση αναφοράς σε μια διαμόρφωση έργου και ορίστε το phpstan.configuration να δείχνει σε αυτή:
includes:
- phpstan-baseline.neon
{
"phpstan": {
"preset": "extreme-theme",
"roots": ["."],
"excludePaths": ["vendor/**"],
"configuration": "phpstan.neon"
}
}
Η επόμενη εκτέλεση αναφέρει το [OK] No errors με τα καταγεγραμμένα ευρήματα στη θέση τους, ενώ οτιδήποτε νέο εξακολουθεί να προκαλεί αποτυχία. Με την προεπιλογή base ή theme, ορίστε επίσης το level: max στο parameters του phpstan.neon: η κανονική εντολή ορίζει αυτό το επίπεδο μόνη της μόνο όταν δεν περιλαμβάνεται διαμόρφωση έργου.
Έλεγχος των commit μέσω της ανάλυσης
Με το "githooks": { "commit": true } στο blockstudio.json, συγχρονίστε το διαχειριζόμενο hook μία φορά μετά την εγκατάσταση των εξαρτήσεων:
vendor/bin/blockstudio-githooks sync
Blockstudio commit hook enabled: /path/to/acme/.git/blockstudio/hooks/pre-commit
Η εντολή γράφει το hook στον δικό του κατάλογο του Git, ορίζει το core.hooksPath ώστε να δείχνει σε αυτό και συνδέει διαδοχικά όποιο hook προ-commit είχε ρυθμιστεί προηγουμένως. Το hook εκτελεί το vendor/bin/blockstudio-phpstan -- --no-progress από τη ρίζα του έργου και τίποτε άλλο: ούτε μορφοποίηση ούτε επανεγγραφές. Το commit του ελαττωματικού προτύπου από πριν σταματά στην ανάλυση:
[ERROR] Found 3 errors
Blockstudio: commit blocked by theme analysis.
Ορίστε το commit σε false και εκτελέστε ξανά το sync ή εκτελέστε το vendor/bin/blockstudio-githooks remove για να επαναφέρετε την προηγούμενη διαδρομή hook. Διαγράφονται μόνο τα αρχεία που έγραψε το Blockstudio.
Δημιουργία του συμβολαίου έργου
Η ανάλυση λέει σε έναν agent εκ των υστέρων τι έκανε λάθος. Ένα AGENTS.md τον ενημερώνει εκ των προτέρων: πού βρίσκονται τα block και οι σελίδες, πώς φτάνουν τα πεδία στα πρότυπα, ποιες λειτουργίες είναι ενεργοποιημένες και τι θα απορρίψει η επιλεγμένη προεπιλογή. Το blockstudio-agents δημιουργεί αυτό το έγγραφο από το ίδιο το έργο:
vendor/bin/blockstudio-agents
Blockstudio contract created: /path/to/acme/AGENTS.md
Για το θέμα αυτού του οδηγού, το παραγόμενο αρχείο αρχίζει ως εξής:
# 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.
Κάθε γραμμή προέρχεται από μία από τρεις πηγές. Τα αρχεία του έργου παρέχουν τον τύπο έργου, τους αριθμούς, τους καταλόγους, τους χώρους ονομάτων και τις γλώσσες προτύπων. Το blockstudio.json παρέχει τις ενεργοποιημένες λειτουργίες, οπότε το hook commit εμφανίζεται στην ενότητα «Ενεργοποιημένες λειτουργίες» και το vendor/bin/blockstudio-githooks sync στην ενότητα «Εντολές» μόνο επειδή έχει οριστεί το githooks.commit. Η επιλεγμένη προεπιλογή παρέχει την ενότητα ορθότητας, η οποία διαβάζεται από τα αρχεία επιπέδων της προεπιλογής, ένα επίπεδο τη φορά:
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.
Διατήρηση της επικαιρότητάς του
Το συμβόλαιο παλιώνει όταν αλλάζει η διαμόρφωση. Αφού ενεργοποιήσετε το Tailwind στο blockstudio.json, η λειτουργία ελέγχου το εντοπίζει:
vendor/bin/blockstudio-agents --check
Blockstudio contract is out of date: /path/to/acme/AGENTS.md
Run blockstudio-agents to regenerate it.
Η εντολή τερματίζεται με 1, οπότε μπορεί να χρησιμοποιηθεί ως βήμα CI δίπλα στην ανάλυση. Η αναδημιουργία προσθέτει μια καταχώριση λειτουργίας «Tailwind CSS» και την εντολή wp bs tailwind compile.
Σημειώσεις που διατηρούνται μετά την αναδημιουργία
Το αρχείο τελειώνει με μια περιοχή σημειώσεων. Οτιδήποτε βρίσκεται ανάμεσα στους δείκτες της διατηρείται byte προς byte σε κάθε αναδημιουργία, οπότε εκεί ανήκουν οι γνώσεις για το έργο που δεν μπορούν να συναχθούν από τα αρχεία:
## 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 -->
Η γεννήτρια δεν αντικαθιστά ποτέ αρχείο που δεν δημιούργησε η ίδια. Αν εκτελεστεί με ένα χειρόγραφο AGENTS.md, αρνείται και τερματίζεται με 2:
Blockstudio: Refusing to overwrite the user-owned file at /path/to/acme/AGENTS.md. Pass --force to replace it.
Για να διατηρήσετε χειρόγραφο κείμενο, αντιγράψτε το προσωρινά αλλού, εκτελέστε με --force και επικολλήστε το στην περιοχή σημειώσεων. Οι άλλες επιλογές είναι --root, --config, --output και --stdout, που εμφανίζει το συμβόλαιο αντί να το γράψει.
Τι αλλάζει στο Blockstudio 7.7
Το πακέτο 7.7 διατηρεί τις εντολές, τις προεπιλογές και τους κωδικούς εξόδου που περιγράφονται εδώ. Κατά τη σύνταξη αυτού του οδηγού με αυτή την έκδοση προέκυψαν δύο διαφορές: το $a δεν χρειάζεται πλέον δήλωση τύπου, όπως περιγράφεται στην ενότητα διόρθωσης, ενώ το παραγόμενο συμβόλαιο περιγράφει ευρύτερα την επικύρωση ετικετών block, καλύπτοντας στοιχεία HTML που αντιστοιχίζονται σε block στις πηγές σελίδων και τα καθολικά γνωρίσματα που μπορεί να προωθεί μια ετικέτα.
Επόμενα βήματα
- PHPStan αναφορά: κάθε κανόνας, παράμετρος προκαθορισμένης ρύθμισης, τύπος πεδίου, σχήμα, ζωντανή δοκιμή απόδοσης και αναγνωριστικό διαγνωστικού ελέγχου.
- Ενσωμάτωση AI: το ευρετήριο τεκμηρίωσης για προγραμματιστικούς agents, που συμπληρώνει τη σύμβαση του έργου σας.
- Vibecoding με Blockstudio: συνεργασία με προγραμματιστικούς agents σε ένα έργο Blockstudio.
- Βιβλιοθήκη μοτίβων πεδίων: δομές πεδίων των οποίων τα κλειδιά προτύπων κατανοεί η ανάλυση, συμπεριλαμβανομένων ομάδων και επαναληπτών.