
Blockstudio 7.2 laajentaa kehystä samanaikaisesti kahteen suuntaan.

Ensimmäinen suunta on **näkyvyys ja työnkulku** yksittäisen projektin sisällä: uusi ylläpidon yleisnäkymä, tietokantaselain, ylläpidon rekisteriselain sekä SCSS-alustukset yhteistä Sass-määritystä varten.

Toinen suunta on **Blockstudion ympärille rakentuva ekosysteemi**: lohkojen jakeluun tarkoitettu rekisteri CLI (kuten shadcn WordPresslle) sekä PHPStan-laajennus, joka tuo TypeScript-tyylisen tyyppiturvallisuuden malleihin, lohkotageihin, `db.php`iin, `rpc.php`iin, `cron.php`iin ja niitä ympäröiviin skeematiedostoihin.

Molempien suuntien tavoitteena on sama: helpottaa suurempien Blockstudio-projektien ymmärtämistä, kehittämistä ja jakamista.

## Ylläpidon käyttökokemus

Kaksi lisäystä helpottaa suuremmassa projektissa navigointia wp-adminissa.

### Ylläpidon yleisnäkymä

Blockstudio sisältää nyt ylläpitonäytön kohdassa **Työkalut > Blockstudio**. Sen avulla voit tarkastella yhdessä paikassa, mitä järjestelmä on rekisteröinyt tiedostojärjestelmästä.

Yleisnäkymässä on omat välilehdet seuraaville:

- Lohkot
- Laajennukset
- Kentät
- Sivut
- Skeemat

Yleisnäkymän lisäksi ylläpitoalueella on nyt oma **Tietokannat**-osio. Se listaa kaikki rekisteröidyt `Blockstudio\Db`-skeemat ja antaa tarkastella varsinaisia tietueita suoraan wp-adminissa.

Mukautetun paneeliruudukon rakentamisen sijaan näytössä käytetään natiiveja WordPressn DataViews-taulukoita. Näin UI pysyy wp-adminin mukaisena ja toimii hyvin myös silloin, kun projektissa on kymmeniä tai satoja rekisteröintejä.

Pienessä asennuksessa ajonaikaisen tilan voi pitää mielessään. Suuremmassa koodikannassa se ei enää onnistu. Alat kysyä esimerkiksi:

- Mitkä lohkot on tällä hetkellä rekisteröity?
- Mitkä laajennukset kohdistuvat kohteeseen `core/*` ja mitkä yksittäisiin lohkoihin?
- Mitkä sivut on synkronoitu, ja mihin artikkelityyppeihin ne kuuluvat?
- Mitä uudelleenkäytettäviä kenttiä tässä projektissa on?
- Mitkä skeemat on rekisteröity, ja mitä tallennuksen taustajärjestelmää ne käyttävät?

Tähän asti vastauksen selvittäminen on vaatinut kansioiden selaamista, JSON-tiedostojen avaamista ja PHPn vaiheittaista läpikäyntiä. Yleisnäkymä kokoaa nämä tiedot varsinaiseksi ylläpitonäkymäksi.

Jokainen välilehti on suunniteltu vastaamaan eri kysymyksiin:

- **Lohkot** näyttävät rekisteröidyt lohkotyypit, renderöintitilan, API-version ja attribuuttien määrän
- **Laajennukset** näyttävät kohdelohkot sekä prioriteetin ja renderöintitiedot
- **Kentät** tarjoavat nopean luettelon uudelleenkäytettävistä mukautetuista kenttämäärittelyistä
- **Sivut** näyttävät synkronoidut tiedostopohjaiset sivut sekä artikkelityypin, tilan, mallimoottorin ja synkronointitilan
- **Skeemat** näyttävät rekisteröidyt tallennusskeemat sekä taustajärjestelmän, kenttien määrän ja käyttöoikeusalueen

Tietokantaselain pidetään tarkoituksella erillään alkuperäisestä yleiskatsauksen lataustietosisällöstä. Sen sijaan, että jokainen rivi sarjoitettaisiin sivun latautuessa, aluksi lokalisoidaan vain käytettävissä olevat skeemat ja tietueet haetaan tarvittaessa, kun avaat tietokantavälilehden. Näin hallintanäkymä pysyy hyödyllisenä myös silloin, kun projektissa on suurempia tietojoukkoja kohteen `db.php` takana.

Tämä ensimmäinen versio keskittyy tarkoituksella skeemaan perustuviin rekisteröinteihin. Se ei ole asetussivu. Se on tarkastelusivu.

Jos et halua sitä lainkaan, poista se kokonaan käytöstä:

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

### Hallintapaneelin rekisteriselain

Yleiskatsauksen vieressä on toinen välilehti: **Rekisteri**. Se on selain teemasi `blocks.json`-tiedostossa määritetyille etälohkojen rekistereille, ja sen avulla voit tuoda lohkoja suoraan WordPressn hallintanäkymään koskematta CLI:een.

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

Selain hakee jokaisen määritetyn rekisterin, luettelee kaikki saatavilla olevat lohkot ja näyttää, onko lohko jo asennettu paikallisesti vai voiko sen tuoda. Jokaisella rivillä on Tuo-painike, joka lataa lohkotiedostot teemasi määritettyyn hakemistoon. Jo asennetuissa lohkoissa painikkeena on sen sijaan Tuo uudelleen.

Tunnistautumista edellyttäviä rekistereitä tuetaan objektimuodossa, jossa käytetään `headers`-määritystä, sekä `${ENV_VAR}`-interpolointia, jotta tunnisteet eivät koskaan päädy versionhallintaan.

Näin rekisterien selaamisesta ja käytöstä tulee olennainen osa hallintakokemusta, eikä kyse ole vain CLI-työnkulusta.

## Rekisterin CLI

Rekisterikokonaisuuden toinen puoli on itsenäinen CLI: `blockstudio/registry`.

Se on shadcn-tyylinen työkalu WordPress-lohkoille. Ei npm-pakettia eikä koontivaihetta. Suoritat komennon, lohkon lähdekoodi kopioidaan projektiisi, ja se on kokonaan sinun hallinnassasi.

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

CLI toimii minkä tahansa lohkotyypin kanssa: Blockstudio-lohkot, `@wordpress/create-block`-tuloste, tavalliset PHP-lohkot. Rekisteri ei välitä siitä, mitä kansio sisältää. Se lukee tiedostoluettelon kohteesta `registry.json` ja kopioi täsmälleen siinä luetellut tiedostot.

Lohkojen tekijät julkaisevat `registry.json`n missä tahansa URLssä (GitHub raakasisältö, S3 tai mukautettu palvelin), ja se luettelee saatavilla olevat lohkot metatietoineen, riippuvuuksineen ja tiedostoluetteloineen. Käyttäjät lisäävät URLn kohteeseen `blocks.json` ja hakevat lohkoja nimellä.

CLI tukee seuraavia ominaisuuksia:

- **Riippuvuuksien ratkaisu**: lohkot voivat ilmoittaa riippuvuuksia muista lohkoista, ja ne ratkaistaan automaattisesti syklit tunnistaen
- **Usean rekisterin ristiriitojen käsittely**: kun sama lohkonimi löytyy useasta rekisteristä, CLI kehottaa valitsemaan yhden
- **Tunnistautumista edellyttävät rekisterit**: bearer-tunnisteet, perustunnistautuminen ja mukautetut otsakkeet ympäristömuuttujien interpoloinnilla
- **Interaktiivinen TUI**: toteutettu Inkillä, mukana latausilmaisimet, valintakehotteet ja edistymisilmaisimet
- **Ei-interaktiivinen tila**: `--yes`-valitsin ja automaattinen CI-/putkivaratoiminta
- **Haku ja luettelo**: selaa rekistereitä komentoriviltä

Pakettiin sisältyy 130 testiä, jotka kattavat skeemat, riippuvuuksien ratkaisun, HTTP-haun, tiedostojen kirjoittamisen, kaikkien komentojen työnkulut sekä interaktiivisen Ink-UIn.

Koko dokumentaatio: [blockstudio.dev/registry](https://blockstudio.dev/fi/registry/).

## PHPStan-laajennus

Toinen suuri lisäys on `blockstudio/phpstan`: PHPStan-laajennus, joka tarjoaa Blockstudio-käyttäjille samanlaisen tyyppiturvallisuuden, jota TypeScript-kehittäjät odottavat.

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

Laajennus lukee projektisi todelliset skeemat analyysin aikana ja välittää niistä muodostetut tyypit takaisin kohteeseen PHPStan. Nyt tuki kattaa PHP-mallipohjat, Twign, Bladen, lohkotunnisteet, tyypitetyt tietokantatietueet, asetuspolut, hookien nimet ja skeemavalidoinnin ympäristöissä `block.json`, `field.json`, laajennuksessa JSON, `page.json`, `db.php`, `rpc.php`, `cron.php` ja `blockstudio.json`.

### Tyyppiturvalliset lohkomallipohjat

Kohteen `$a` kenttäkäyttö validoidaan viereisen kohteen `block.json` perusteella:

```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"?
```

### Tyyppiturvalliset tietokantatietueet

`Db::get()` palauttaa tyypitetyn ilmentymän `db.php`-skeemasi perusteella. Tietueen rakenne muodostetaan todellisista kentistä:

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

### Skeeman validointi

Virheelliset skeematiedostot havaitaan analyysin aikana: `block.json`, `field.json`, laajennus JSON, `page.json`, `db.php`, `rpc.php`, `cron.php` ja `blockstudio.json`. Puuttuvat nimet, väärät kenttätyypit, virheelliset määritykset ja vanhentuneet lyhennetyt totuusarvot (`"tailwind": true` sisäkkäisen objektin sijaan) ilmoitetaan kaikki lähdetiedoston tarkan rivin kanssa.

### Asetuspolkujen validointi

Kohteen `Settings::get()` kutsut validoidaan tunnettua asetuskeemaa vasten:

```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"?
```

### Hookien nimien validointi

Sama koskee suodatin- ja toimintohookien nimiä:

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

Laajennukseen sisältyy myös koko Blockstudion julkisen APIn tyngät: `Db`, `Settings`, `Field_Registry`, `Build` ja yleiset apufunktiot. Saat kaikkien Blockstudio-rajapintojen automaattisen täydennyksen ja tyyppitarkistuksen ilman, että laajennuksen lähdekoodia tarvitsee olla kehityskoneellasi.

## Kirjoittamisen helpotukset

Kaksi pienempää kirjoittamisen helpotusta täydentää julkaisun.

### Yleiset SCSS-esikoodit

Blockstudio tuki jo SCSS-käännöstä, mutta yksi hankala kitkakohta oli jaetun Sass-määrityksen tekeminen.

Jos halusit käyttää yhteistä muuttujien, funktioiden tai miksiinien joukkoa, ne piti tuoda jokaiseen SCSS-tiedostoon erikseen. Siitä tulee nopeasti toisteista, etenkin suuremmissa suunnittelujärjestelmissä tai Sass-työkalupakeissa, kuten Bootstrap.

Versio 7.2 lisää esikoodihookin juuri tätä varten:

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

Yhdessä olemassa olevan `blockstudio/assets/process/scss/import_paths`-suodattimen kanssa voit määrittää jaetun Sass-rajapinnan kerran, jolloin se on käytettävissä jokaisessa käännettävässä tiedostossa.

Lohkon tyylitiedosto voi keskittyä tarvitsemiinsa tyyleihin:

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

Lohko-omaisuuksiin ei tarvitse lisätä toistuvia tuonteja. Tämä ei ole erillinen "Bootstrap-tuki"-tila. Kyseessä on yleinen hook jaetun Sassn käyttöön projektissa, olipa se peräisin kohteesta Bootstrap tai omasta sisäisestä työkalupakistasi.

### PHP-natiivimääritykset lohkon APIlle

Versio 7.2 lisää myös valinnaisen PHP-natiivisyntaksin koko pinon lohkorajapinnoille. Taulukot ovat edelleen oletusarvo ja täysin tuettuja. Mitään ei ole korvattu. Jos kuitenkin pidät nimetyistä argumenteista, enumeraatioista ja attribuuteista sisäkkäisten määritystaulukoiden sijaan, voit nyt valita tämän tyylin.

Kohdetta `rpc.php` varten palauta objekti, jossa on attribuuteilla merkityt metodit:

```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'];
    }
};
```

Kohteen `cron.php` kanssa sama idea toimii myös kohteen `#[Cron]` avulla:

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

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

Kohdetta `db.php` varten on nyt myös pieni rakenninkerros:

```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),
    ],
);
```

Tämä tarjoaa paremman tasapainon suuremmissa koodikannoissa. Taulukkomuoto säilyy yksinkertaisena silloin, kun sitä haluat käyttää, ja voit siirtyä helpommin löydettävään PHP-rajapintaan, kun lohkoon tulee kourallista kenttiä tai päätepisteitä enemmän.

## Miksi nämä julkaistaan yhdessä

Hallinnan yleiskatsaus, rekisteriselain, rekisterin CLI ja PHPStan-laajennus vastaavat kaikki samaan kysymykseen: miten Blockstudio-projektin saa pysymään ymmärrettävänä sen kasvaessa?

Hallintatyökalut vastaavat kysymykseen projektitasolla: ne näyttävät, mitä on rekisteröity, mahdollistavat lohkojen tuomisen rekistereistä ja vähentävät arvailua.

CLI vastaa kysymykseen ekosysteemitasolla: se tarjoaa tavan jakaa lohkoja projektien ja tiimien kesken niputtamatta niitä npm-paketteihin tai taistelematta koontijärjestelmien kanssa.

PHPStan-laajennus vastaa kysymykseen kooditasolla: se havaitsee väärät kenttäkäytöt, skeemojen kirjoitusvirheet ja rikkinäiset hook-takaisinkutsut ennen niiden päätymistä suoritusaikaan.

Tämä on 7.2:n yleinen suunta: vähemmän arvailua ja toistoa, parempi näkyvyys ja nyt myös todellinen tyyppiturvallisuus.

## Virheenkorjaukset

- **Classes-kenttä**: käyttäjän kirjoittamat mukautetut luokkanimet katosivat huomaamatta, kun kentästä poistuttiin, koska validoija hyväksyi vain esimääritellyn Tailwind/asetusluettelon luokat. Nyt hyväksytään mikä tahansa ei-tyhjä merkkijono.
- **Attributes-kenttä**: attribuuttiparin poistaminen jätti tallennettuihin tietoihin `null`-merkintöjä. Lodashin `unset()` vaihdettiin funktioon `splice()`, joka poistaa alkiot null-arvoksi asettamisen sijaan.
- **CSS-minimointi**: TailwindPHP-minimoija poisti välilyönnit kohteen `+` ympäriltä kohteissa `calc()` ja `clamp()`, mikä tuotti virheellistä CSSää, kuten `calc(1rem+0.5vw)`. Korjaus tehtiin alkupään projektissa versiossa TailwindPHP v1.3.1: syvyyden huomioiva merkkikävely poistaa välilyöntejä valitsinten yhdistimien ympäriltä vain sulkeiden syvyydellä 0.
- **Lohkon lisäysvalikon esikatselu**: `$isPreview` oli aina `false` lohkon lisäysvalikon esikatselussa, koska renderöintivälimuistin tiivisteavaimessa ei ollut renderöintitilaa. Editorin ja esikatselun renderöinnit tallennetaan nyt eri välimuistimerkintöihin.
- **Sisäkkäinen InnerBlocks-mallipohja**: komponentti `<InnerBlocks template="..."/>` pudotti mallipohjan monikoista kolmannen alkion (lapset), esimerkiksi `['core/group', {}, [['core/paragraph']]]`, mikä tuotti tyhjiä säiliölohkoja. Nyt sisäkkäiset lapset säilyvät.
