
Blockstudio 7.2 laiendab raamistikku korraga kahes suunas.

Esimene suund on **nähtavus ja töövoog** ühe projekti sees: uus haldusülevaade, andmebaasibrauser, haldusregistri brauser ja SCSS eellõigud jagatud Sass seadistuse jaoks.

Teine suund on **Blockstudio ümbritsev ökosüsteem**: registri CLI plokkide levitamiseks (nagu shadcn WordPress jaoks) ning laiendus PHPStan, mis toob mallidesse, plokimärgenditesse, `db.php`-i, `rpc.php`-i, `cron.php`-i ja seotud skeemifailidesse TypeScript-laadse tüübiturvalisuse.

Mõlema suuna eesmärk on sama: muuta suuremaid Blockstudio projekte lihtsamaks mõista, edasi arendada ja jagada.

## Halduskogemus

Kaks lisandust muudavad suuremas projektis wp-adminis navigeerimise lihtsamaks.

### Haldusülevaade

Blockstudio sisaldab nüüd haldusvaadet asukohas **Tööriistad > Blockstudio**. See annab ühe koha, kus vaadata, mida süsteem on failisüsteemist registreerinud.

Ülevaade sisaldab eraldi vahekaarte järgmise jaoks:

- Plokid
- Laiendused
- Väljad
- Lehed
- Skeemid

Ülevaate kõrval on haldusalas nüüd ka eraldi jaotis **Andmebaasid**. Seal loetletakse kõik registreeritud `Blockstudio\Db` skeemid ning saab vaadata kirjeid otse wp-adminis.

Kohandatud paneeliruudustiku loomise asemel kasutab vaade algupäraseid WordPress DataViews tabeleid. Nii püsib UI wp-adminiga kooskõlas ning lahendus on praktiline ka siis, kui projektis on kümneid või sadu registreeringuid.

Väikeses paigalduses suudad käitusaja oleku peas hoida. Suuremas koodibaasis see enam ei toimi. Hakkad esitama küsimusi, näiteks:

- Millised plokid on praegu tegelikult registreeritud?
- Millised laiendused sihivad `core/*`-i ja millised üksikuid plokke?
- Millised lehed on sünkroonitud ja milliste postitüüpidega need seotud on?
- Millised korduvkasutatavad väljad selles projektis olemas on?
- Millised skeemid on registreeritud ja millist salvestuslahendust need kasutavad?

Seni tuli vastuse leidmiseks kaustu uurida, JSON-faile avada ja PHP-i koodi läbi käia. Ülevaade koondab selle päris haldusvaatesse.

Iga vahekaart on mõeldud eri küsimustele vastamiseks:

- **Plokid** näitavad registreeritud plokitüüpe, renderdusrežiimi, API versiooni ja atribuutide arvu
- **Laiendused** näitavad, millistele plokkidele need sihivad, ning prioriteeti ja renderduse üksikasju
- **Väljad** annavad kiire ülevaate korduvkasutatavatest kohandatud väljadefinitsioonidest
- **Lehed** näitavad sünkroonitud failipõhiseid lehti koos postitüübi, oleku, mallimootori ja sünkroonimisolekuga
- **Skeemid** kuvavad registreeritud salvestusskeemid koos taustaprogrammi, väljade arvu ja võimekuse ulatusega

Andmebaasibrauser on teadlikult üldvaate algsest päringukoormusest eraldatud. Selle asemel, et laadimisel kõik read järjestada, tuvastab see alguses ainult saadaolevad skeemid ja hangib kirjed nõudmisel, kui avate andmebaasi vahekaardi. Nii jääb haldusliides kasutatavaks ka siis, kui projektis on `db.php` taga suuremad andmestikud.

See esimene versioon keskendub teadlikult skeemipõhistele registreeringutele. See pole seadete leht, vaid ülevaatamise leht.

Kui te seda üldse ei soovi, saate selle täielikult keelata:

```php
add_filter('blockstudio/admin/enabled', '__return_false');
```

### Haldusliidese registrite brauser

Üldvaate kõrval on teine vahekaart: **Registry**. See on brauser teemasse `blocks.json` seadistatud kaugplokiregistritele ning võimaldab teil plokke otse WordPress haldusliidesest importida, ilma et peaksite CLI puudutama.

```json title="blocks.json"
{
  "directory": "blockstudio",
  "registries": {
    "ui": "https://blocks.example.com/registry.json",
    "private": {
      "url": "https://api.example.com/registry.json",
      "headers": {
        "Authorization": "Bearer ${REGISTRY_TOKEN}"
      }
    }
  }
}
```

Brauser hangib kõik seadistatud registrid, loetleb kõik saadaolevad plokid ja näitab, kas need on juba kohalikult installitud või importimiseks saadaval. Igal real on nupp Import, mis laadib plokifailid teie teemas seadistatud kataloogi. Juba installitud plokkide puhul kuvatakse selle asemel nupp Reimport.

Toetatud on autentimist nõudvad registrid objektivormingu kaudu, kasutades `headers`, sealhulgas `${ENV_VAR}` interpolatsiooni, et märgid ei satuks kunagi versioonihaldusse.

Nii muutub registrite sirvimine ja kasutamine haldusliidese esmaklassiliseks võimaluseks, mitte lihtsalt CLI töövooguks.

## Registry CLI

Registri teine pool on eraldiseisev CLI: `blockstudio/registry`.

See on shadcn-stiilis tööriist WordPress plokkide jaoks. npm paketti ega ehitussammu pole vaja. Käivitate käsu, ploki lähtekood kopeeritakse teie projekti ja see kuulub täielikult teile.

```bash
npx blockstudio init
npx blockstudio add ui/tabs
```

CLI töötab mis tahes tüüpi plokkidega: Blockstudio plokid, `@wordpress/create-block` väljund, tavalised PHP plokid. Registrit ei huvita, mis kaustas leidub. See loeb failide manifesti asukohast `registry.json` ja kopeerib täpselt need failid.

Plokkide autorid avaldavad `registry.json`-i mis tahes URL juures (GitHub toorsisu, S3 või kohandatud server), kus on loetletud saadaolevad plokid koos metaandmete, sõltuvuste ja faililoenditega. Kasutajad lisavad URL oma `blocks.json`-i ning hangivad plokke nime järgi.

CLI toetab järgmist:

- **Sõltuvuste lahendamine**: plokid saavad deklareerida sõltuvusi teistest plokkidest; need lahendatakse automaatselt ja tsüklite tuvastamisega
- **Mitme registri konfliktide lahendamine**: kui sama nimega plokk leidub mitmes registris, palub CLI teil ühe valida
- **Autentimist nõudvad registrid**: kandjamärgid, lihtautentimine ja kohandatud päised koos keskkonnamuutuja interpolatsiooniga
- **Interaktiivne TUI**: loodud Inkiga, sisaldab laadimisindikaatoreid, valikupäringuid ja edenemisnäidikuid
- **Mitteinteraktiivne režiim**: lipp `--yes` ning automaatne CI ja torude varurežiim
- **Otsing ja loendamine**: sirvige registreid käsurealt

Paketiga on kaasas 130 testi, mis katavad skeemid, sõltuvuste lahendamise, HTTP hankimise, failide kirjutamise, kõik käsuvood ja interaktiivse Inki UI.

Täielik dokumentatsioon: [blockstudio.dev/registry](https://blockstudio.dev/et/registry/).

## PHPStan laiendus

Teine suur lisandus on `blockstudio/phpstan`: PHPStan laiendus, mis annab Blockstudio kasutajatele sama tüübiturvalisuse, mida TypeScript arendajad ootavad.

```bash
composer require --dev blockstudio/phpstan
```

Laiendus loeb analüüsi ajal teie projekti tegelikke skeeme ja edastab saadud tüübid tagasi PHPStan-ile. Nüüd hõlmab see PHP malle, Twig, Blade, plokisilte, tüübistatud andmebaasikirjeid, seadete teid, hookide nimesid ja skeemide valideerimist järgmistes: `block.json`, `field.json`, laienduse JSON, `page.json`, `db.php`, `rpc.php`, `cron.php` ja `blockstudio.json`.

### Tüübikindlad plokimallid

Väljadel `$a` kontrollitakse juurdepääsu vastavust kõrvalasuvale `block.json`-ile:

```php title="blockstudio/hero/index.php"
<?php
/** @var array<string, mixed> $a */

echo $a['title'];     // OK
echo $a['cta']['href']; // OK
echo $a['typo'];      // ERROR: Field "typo" does not exist in block.json (block: hero). Did you mean "title"?
```

### Tüübikindlad andmebaasikirjed

`Db::get()` tagastab teie `db.php` skeemil põhineva tüübistatud eksemplari. Kirje struktuur koostatakse tegelike väljade põhjal:

```php title="db.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']; // PHPStan: string
echo $record['name'];  // PHPStan: string|null
echo $record['typo'];  // ERROR: Offset 'typo' does not exist on array{id: int, email: string, name: string|null}
```

### Skeemi valideerimine

Vigased skeemifailid tuvastatakse analüüsi ajal: `block.json`, `field.json`, laienduse JSON, `page.json`, `db.php`, `rpc.php`, `cron.php` ja `blockstudio.json`. Puuduvad nimed, valed väljatüübid, vigased definitsioonid ja aegunud lühivormis tõeväärtused (`"tailwind": true` pesastatud objekti asemel) antakse kõik teada koos täpse reanumbriga lähtefailis.

### Seadete tee valideerimine

`Settings::get()` kutseid kontrollitakse teadaoleva seadete skeemi alusel:

```php
Settings::get('tailwind/enabled');  // OK, returns bool
Settings::get('tailwind/enabld');   // ERROR: Settings path "tailwind/enabld" is not a known Blockstudio setting. Did you mean "tailwind/enabled"?
```

### Hooki nime valideerimine

Sama kehtib filtri- ja tegevuse hookide nimede kohta:

```php
add_filter('blockstudio/render', $cb);  // OK
add_filter('blockstudio/rendrr', $cb);  // ERROR: Unknown Blockstudio hook "blockstudio/rendrr". Did you mean "blockstudio/render"?
```

Laiendusega on kaasas ka kogu Blockstudio avaliku API stubid: `Db`, `Settings`, `Field_Registry`, `Build` ja globaalsed abifunktsioonid. Saate automaattäite ja tüübikontrolli kõigi Blockstudio APIde jaoks, ilma et teil oleks arendusmasinas plugina lähtekoodi vaja.

## Mugavused autoritele

Väljalaset täiendavad kaks väiksemat autoritööd hõlbustavat mugavust.

### Globaalsed SCSS eellaused

Blockstudio toetas juba SCSS kompileerimist, kuid üks tüütu takistus jäi: jagatud Sass seadistus.

Kui tahtsite kasutada ühiseid muutujaid, funktsioone või miksineid, tuli need importida igasse SCSS faili. See muutub kiiresti korduvaks, eriti suuremate disainisüsteemide või Sass tööriistakomplektide, näiteks Bootstrap puhul.

Versioon 7.2 lisab just selleks eellaadimise hooki:

```php
add_filter('blockstudio/assets/process/scss/prelude', function($prelude, $path, $scss) {
  return '@import "functions";' . "\n"
    . '@import "variables";' . "\n"
    . '@import "mixins";';
}, 10, 3);
```

Koos olemasoleva `blockstudio/assets/process/scss/import_paths` filtriga määratlete jagatud Sass pinna üks kord ja see on saadaval igas kompileeritud failis.

Ploki stiilifail saab keskenduda tegelikult vajalikele stiilidele:

```scss title="style.scss"
.hero {
  @include media-breakpoint-up(lg) {
    padding: 4rem;
  }
}
```

Igas ploki varas pole enam vaja importi korrata. See pole erirežiim nimega „Bootstrap tugi“, vaid üldine hook kogu projekti jagatud Sass jaoks, olgu need pärit Bootstrap-ist või teie enda sisemisest tööriistakomplektist.

### PHP-i loomulik ploki API määratlus

Versioon 7.2 lisab ka valikulise süntaksi, mis on PHP-i loomulik, täismahus ploki APIde jaoks. Massiivid jäävad vaikimisi kasutatavaks ja täielikult toetatuks. Midagi ei asendatud. Kui eelistate pesastatud seadistusmassiividele nimega argumente, loendeid ja atribuute, saate nüüd selle stiili valida.

`rpc.php` puhul tagastage atribuutidega meetoditega objekt:

```php title="rpc.php"
<?php
use Blockstudio\Attributes\Rpc;
use Blockstudio\Rpc\Access;
use Blockstudio\Rpc\Method;

return new class {
    #[Rpc(access: Access::Session)]
    public function subscribe(array $params): array {
        return ['success' => true];
    }

    #[Rpc(name: 'status', methods: [Method::Get, Method::Post])]
    public function getStatus(array $params): array {
        return ['status' => 'ok'];
    }
};
```

`cron.php` puhul töötab sama mõte ka koos `#[Cron]`-iga:

```php title="cron.php"
<?php
use Blockstudio\Attributes\Cron;
use Blockstudio\Cron\Schedule;

return new class {
    #[Cron(schedule: Schedule::Hourly)]
    public function heartbeat(): void {
    }
};
```

`db.php` jaoks on nüüd olemas väike koostajakiht:

```php title="db.php"
<?php
use Blockstudio\Db\Field;
use Blockstudio\Db\Schema;
use Blockstudio\Db\Storage;

return Schema::make(
    storage: Storage::Table,
    fields: [
        'email' => Field::string(required: true, format: 'email'),
        'active' => Field::boolean(default: false),
    ],
);
```

See loob suuremate koodibaaside jaoks parema tasakaalu. Soovi korral säilitate massiivivormingu lihtsuse, kuid kui plokil on juba rohkem kui mõni väli või lõpp-punkt, saate üle minna paremini avastatavale PHP liidesele.

## Miks need asjad koos välja tulevad

Haldusliidese üldvaade, registribrauser, registri CLI ja PHPStan laiendus vastavad kõik samale küsimusele: kuidas hoida Blockstudio projekti mõistetavana, kui see kasvab?

Haldustööriistad lahendavad selle projekti tasandil: ülevaade registreeritust, võimalus registreist plokke lisada ja vähem oletamist.

CLI lahendab selle ökosüsteemi tasandil: viis plokkide jagamiseks projektide ja tiimide vahel, ilma et neid peaks pakkima npm pakettidesse või ehitussüsteemidega võitlema.

Laiendus PHPStan lahendab selle koodi tasandil: tuvastab valed juurdepääsud väljadele, skeemide kirjavead ja vigased hookide tagasihelistused enne, kui need käivitamisel probleeme tekitavad.

Üldjoontes liigub versioon 7.2 selles suunas: vähem oletamist ja kordamist, parem ülevaade ning nüüd ka tegelik tüübiturvalisus.

## Veaparandused

- **Väljade Classes**: kasutaja sisestatud kohandatud klassinimed kadusid fookuse kaotamisel märkamatult, sest valideerija aktsepteeris ainult eelmääratud Tailwind/seadete loendis olevaid klasse. Nüüd aktsepteeritakse mis tahes mittetühja stringi.
- **Väljade Attributes**: atribuudi-paari eemaldamisel jäid salvestatud andmetesse alles `null` kirjed. Kasutati lodash `unset()` asemel funktsiooni `splice()`, mis eemaldab massiivi elemendid nulliks muutmise asemel.
- **CSS tihendaja**: TailwindPHP tihendaja eemaldas tühikud ümber `+` elementide `calc()` ja `clamp()` sees, tekitades vigaseid CSS-i väärtusi, näiteks `calc(1rem+0.5vw)`. Parandus tehti ülesvoolu versioonis TailwindPHP v1.3.1: tähemärgid käiakse läbi sügavust arvestades ning tühikud eemaldatakse sulgude sügavusel 0 ainult valijate kombinaatorite ümbert.
- **Ploki lisaja eelvaade**: `$isPreview` oli ploki lisaja eelvaates alati `false`, sest renderdamise vahemälu räsi võti ei sisaldanud renderdusrežiimi. Redaktori- ja eelvaaterenderdused salvestatakse nüüd eraldi vahemälukirjetesse.
- **InnerBlocksi pesastatud mall**: komponent `<InnerBlocks template="..."/>` jättis mallituplite, näiteks `['core/group', {}, [['core/paragraph']]]` puhul kolmanda elemendi (lapsed) välja, mistõttu konteinerplokid jäid tühjaks. Nüüd säilitatakse pesastatud lapsed.
