
Blockstudio 7.1 to pierwsze wydanie z nowymi funkcjami od czasu przepisania v7. Podczas gdy v7 odbudowało fundamenty, wersja 7.1 dodaje elementy, które zmieniają bloki w coś więcej: warstwę bazy danych, funkcje serwerowe, zadania zaplanowane i CLI. Folder bloku może teraz zawierać kompletną aplikację.

Oto wszystkie nowości.

## Komponenty

Zawsze istniał rozdźwięk między blokami używanymi przez redaktorów we wstawiaczu a blokami, z których deweloperzy budują inne elementy. Karta, plakietka, widżet ze statystykami, pole formularza. Potrzebują pełnego procesu Blockstudio (atrybutów, szablonów, zasobów, Tailwind), ale nie powinny pojawiać się we wstawiaczu.

Wersja 7.1 wprowadza komponenty, które rozwiązują ten problem. Ustaw `"component": true` w pliku block.json, a blok przejdzie przez cały proces kompilacji, ale nie zostanie zarejestrowany w rejestrze typów bloków WordPress. Nie pojawi się we wstawiaczu ani w danych edytora wysyłanych do JavaScript, ale będzie w pełni dostępny do renderowania programowego.

```json title="block.json"
{
  "name": "my-theme/card",
  "title": "Card",
  "blockstudio": {
    "component": true,
    "attributes": [
      { "id": "title", "type": "text" },
      { "id": "description", "type": "textarea" }
    ]
  }
}
```

Renderuj je z poziomu PHP:

```php
bs_render_block([
  'name' => 'my-theme/card',
  'data' => ['title' => 'My Card', 'description' => 'Card content.'],
]);
```

Lub użyj nowej składni tagów HTML:

```html
<bs:my-theme-card title="My Card" description="Card content." />
```

## Tagi bloków

Bloki można teraz osadzać jako tagi HTML, używając jednej z dwóch wymiennych składni:

```html
<bs:acme-hero title="Welcome" />
<block name="acme/hero" title="Welcome" />
```

Obie dają ten sam wynik. Obie działają z blokami Blockstudio i podstawowymi blokami WordPress. Wewnątrz szablonów bloków są renderowane automatycznie, bez konieczności włączania tej funkcji. Dzięki temu możesz bezpośrednio w szablonie tworzyć całe układy z innych bloków:

```twig title="index.twig"
<div class="my-page">
  <bs:mytheme-card title="Featured" />
  <block name="core/separator" />
  <bs:core-heading level="2">Section Title</bs:core-heading>
  <block name="core/group">
    <block name="core/paragraph">Inside a core group block.</block>
    <bs:mytheme-cta variant="primary" />
  </block>
</div>
```

Obie składnie można dowolnie zagnieżdżać. Bloki Blockstudio przechodzą przez pełny proces renderowania (szablony, Tailwind, zasoby). Bloki podstawowe są renderowane przez WordPress z użyciem tych samych mechanizmów renderujących, które obsługują strony i wzorce [Pages and Patterns](https://blockstudio.dev/pl/docs/pages-and-patterns/).

Aby renderować na poziomie strony (treść wpisu, obszary widżetów), włącz tę funkcję w `blockstudio.json`:

```json
{ "blockTags": { "enabled": true } }
```

Listy dozwolonych i zablokowanych wzorców określają, które bloki można renderować za pomocą tagów. Atrybuty `data-*` i `html-*` są przekazywane do głównego elementu HTML renderowanego bloku. Własne renderery można zarejestrować za pomocą filtra `blockstudio/block_tags/renderers`.

Parser tagów to nowy, lekki skaner ciągów znaków, który całkowicie zastępuje DOMDocument. Obsługuje zagnieżdżone tagi, śledząc ich poziom zagnieżdżenia, rekurencyjne bloki-kontenery i mieszaną składnię w jednym przebiegu. W testach porównawczych analizuje 1,000 płaskich tagów w 2.4ms i 100 poziomów zagnieżdżenia w 3.7ms, konsekwentnie szybciej niż zarówno DOMDocument, jak i WordPress `WP_HTML_Tag_Processor`. Ten sam parser obsługuje również analizę surowych elementów HTML na potrzeby stron i wzorców [Pages and Patterns](https://blockstudio.dev/pl/docs/pages-and-patterns/), zastępując parser oparty na DOMDocument, który wcześniej obsługiwał elementy `<p>`, `<div>` i inne elementy HTML.

## Nowe typy pól

### Blok

Nowy typ pola `block`, który pozwala odwołać się do innego bloku Blockstudio jako atrybutu. Pola bloku, do którego prowadzi odwołanie, rozwijają się w wierszu z użyciem `idStructure` i `overrides`, dokładnie tak jak pola własne. Różnica polega na tym, że w szablonie odczytanie wartości zwraca wyrenderowany blok.

```json title="block.json"
{
  "blockstudio": {
    "attributes": [
      {
        "id": "card",
        "type": "block",
        "block": "mytheme/card",
        "idStructure": "card_{id}"
      }
    ]
  }
}
```

Jeśli `mytheme/card` ma pola `heading` i `content`, blok nadrzędny otrzymuje na pasku bocznym `card_heading` i `card_content`. W szablonie `{{ a.card }}` zwraca wyrenderowaną kartę. Działa zarówno ze zwykłymi blokami, jak i komponentami.

### Tag HTML

W każdym motywie są bloki, w których poziom nagłówka powinien zależeć od kontekstu. H1 na stronie głównej, H2 na podstronach. Zamiast za każdym razem tworzyć w tym celu pole wyboru ze zdefiniowanymi na sztywno opcjami, możesz teraz użyć dedykowanego pola typu `html-tag` z wbudowanymi ustawieniami.

```json
{
  "id": "tag",
  "type": "html-tag",
  "default": "h2",
  "tags": "heading",
  "exclude": ["h5", "h6"]
}
```

Ustawienia: `heading` (h1-h6), `text` (nagłówki + p, span, div), `structural` (div, section, article, aside, main, header, footer, nav), `all`. Możesz też przekazać własną tablicę. `exclude` usuwa określone tagi z dowolnego ustawienia.

```twig
<{{ a.tag }}>{{ a.title }}</{{ a.tag }}>
```

## Baza danych

To główny element tego wydania. Dodaj plik `db.php` do dowolnego katalogu bloku, a Blockstudio wygeneruje pięć punktów końcowych REST CRUD, sprawdzi każde żądanie zapisu względem schematu, automatycznie zarządzi zapleczem pamięci masowej oraz udostępni klienta JavaScript (`bs.db()`) i PHP API (`Db::get()`). Bez plików migracji, klas kontrolerów i rejestracji tras.

```php title="db.php"
return [
    'subscribers' => [
        'storage'    => 'table',
        'capability' => [
            'create' => true,
            'read'   => true,
            'update' => 'edit_posts',
            'delete' => 'manage_options',
        ],
        'fields' => [
            'email' => [
                'type'     => 'string',
                'format'   => 'email',
                'required' => true,
                'validate' => function ($value) {
                    if (str_ends_with($value, '@spam.com')) {
                        return 'This domain is blocked.';
                    }
                    return true;
                },
            ],
            'name' => ['type' => 'string', 'maxLength' => 100],
            'plan' => ['type' => 'string', 'enum' => ['free', 'pro']],
        ],
    ],
];
```

Sam ten schemat tworzy w pełni działające API z punktami końcowymi do tworzenia, wyświetlania listy, pobierania, aktualizacji i usuwania, a każdy z nich waliduje dane wejściowe.

### Pamięć masowa

Pięć zapleczy pamięci masowej, każde odpowiednie do innych zastosowań:

- **`table`**: Niestandardowa tabela MySQL zarządzana przez `dbDelta()`. Dodanie pól do schematu spowoduje dodanie kolumn przy następnym wczytaniu strony. Domyślna konfiguracja produkcyjna.
- **`sqlite`**: Pojedynczy plik SQLite w folderze `db/` bloku. Prawdziwe zapytania SQL, tryb WAL do równoczesnych odczytów i pełna przenośność. Skopiuj folder, skopiuj bazę danych.
- **`jsonc`**: Jeden obiekt JSON w każdym wierszu płaskiego pliku. Czytelny dla człowieka, z możliwością kontroli wersji, przyjazny dla git.
- **`meta`**: Tablica JSON w metadanych wpisu WordPress, powiązana z konkretnym wpisem.
- **`post_type`**: Każdy rekord staje się wpisem WordPress w niestandardowym typie wpisu. Pola są przechowywane jako osobne wpisy metadanych, w pełni dostępne w zapytaniach `WP_Query`.

### Klienci

Po stronie JavaScript `bs.db()` zapewnia kompletny klient CRUD:

```js
const db = bs.db('my-theme/block', 'subscribers');
const record = await db.create({ email: 'a@b.com', plan: 'pro' });
const pros = await db.list({ plan: 'pro' });
await db.update(record.id, { plan: 'free' });
await db.delete(record.id);
```

Dołączono do niego trzy dodatkowe narzędzia:

- **`bs.cache`**: Pamięć podręczna zapytań w pamięci z obsługą `get`, `set`, `invalidate` i `clear`. Współdzielona przez wszystkie wywołania zapytań i mutacji.
- **`bs.query(key, fn, options)`**: Opakowuje dowolną funkcję asynchroniczną, zapewniając buforowanie, deduplikację żądań i konfigurowalne `staleTime`. Kilka wywołań z tym samym kluczem podczas trwającego żądania zwraca tę samą obietnicę.
- **`bs.mutate(options)`**: Obsługuje optymistyczne mutacje z automatycznym wycofaniem zmian. Przekaż reaktywny obiekt stanu, akcję (`create`, `update`, `delete`) i optymistyczne dane. UI aktualizuje się natychmiast. Jeśli wywołanie serwera się nie powiedzie, stan wraca do migawki sprzed mutacji.

Razem obsługują pełny cykl odczytu i zapisu: `bs.query` do buforowanych odczytów, `bs.mutate` do optymistycznych zapisów, `bs.cache` do ręcznego sterowania.

Po stronie PHP klasa `Db` udostępnia te same operacje:

```php
use Blockstudio\Db;

$db = Db::get('my-theme/block', 'subscribers');
$db->create(['email' => 'a@b.com', 'plan' => 'pro']);
$db->list(['plan' => 'pro']);
```

### Walidacja

Błędy walidacji są zwracane jako tablice błędów dla poszczególnych pól, zgodnie z formatem `fieldErrors` Zod. Kilka reguł może nie przejść walidacji dla tego samego pola, a struktura ułatwia przypisywanie błędów do pól formularza w interfejsie użytkownika:

```json
{
  "data": {
    "status": 400,
    "errors": {
      "email": ["Must be a valid email address.", "This domain is blocked."],
      "plan": ["Must be one of: free, pro."]
    }
  }
}
```

Niestandardowe wywołania zwrotne `validate` działają po stronie serwera i obsługują wszystko, czego nie obejmują wbudowane reguły: blokowanie domen, walidację między polami i zewnętrzne wyszukiwanie danych.

### Dane przypisane do użytkownika

W przypadku danych przypisanych do użytkownika, takich jak zadania do zrobienia, ulubione czy wersje robocze, ustaw `userScoped` na `true`, a Blockstudio zajmie się resztą. Doda kolumnę `user_id`, automatycznie ustawi jej wartość przy tworzeniu i ograniczy każde zapytanie do bieżącego użytkownika. Przy aktualizacji i usuwaniu sprawdzi uprawnienia. Bez ręcznego pola `user_id`, haka `before_create` i filtrowania w RPC. Wystarczy jedna linia konfiguracji. W przypadku pamięci masowej `post_type` `userScoped` jest mapowane na `post_author` zamiast osobnej kolumny.

```php
return [
    'storage'    => 'sqlite',
    'userScoped' => true,
    'fields'     => [ /* ... */ ],
];
```

### Odpytywanie w czasie rzeczywistym

Ustaw `'realtime' => true` w schemacie, a klient będzie automatycznie sprawdzać, czy zaszły zmiany. Gdy coś zmieni się na serwerze, magazyn Interactivity API zaktualizuje się, a UI ponownie wyrenderuje widok bez zmian w JavaScript po Twojej stronie. Skonfiguruj za pomocą `'realtime' => ['key' => 'todos', 'interval' => 5000]` niestandardowe klucze stanu i interwały. Odpytywanie używa porównywania skrótów, by ograniczyć rozmiar żądań, i zatrzymuje się, gdy karta przeglądarki jest ukryta.

### Bezpieczeństwo, haki i przenośność

Publiczne punkty końcowe są chronione automatycznie dodawanym nagłówkiem CSRF `X-BS-Token`. Użyj `'open'`, jeśli potrzebujesz dostępu bez uwierzytelniania, na przykład do przychodzących webhooków.

Haki cyklu życia uruchamiają się przed każdą operacją zapisu i po niej. Zdefiniuj je bezpośrednio w `db.php` lub globalnie za pomocą akcji WordPress.

Pola mogą definiować klucz `component`, aby renderować formularze na podstawie schematu za pomocą `bs_db_form()`.

W przypadku pamięci masowej SQLite lub JSONC cała aplikacja mieści się w jednym folderze: kod, logika, kontrola dostępu i dane. Skopiuj folder, aby wdrożyć aplikację.

## RPC

Czasami CRUD nie wystarcza. Potrzebna jest niestandardowa logika serwerowa: przełączanie statusu zadania, wysyłanie powiadomienia, agregowanie statystyk. Do tego służy `rpc.php`. Zdefiniuj funkcję PHP, wywołaj ją z interfejsu użytkownika za pomocą `bs.fn()`, a Blockstudio zajmie się punktem końcowym REST, uwierzytelnianiem, ochroną CSRF i serializacją JSON. Wzorzec jest inspirowany [tRPC](https://trpc.io): procedury definiuje się po stronie serwera, a klient wywołuje je po nazwie.

```php title="rpc.php"
return [
    'subscribe' => function (array $params): array {
        $email = sanitize_email($params['email']);
        return ['success' => true];
    },
];
```

```js
const result = await bs.fn('subscribe', { email: 'user@example.com' });
```

Skrypty wstawiane bezpośrednio (`script-inline.js`) automatycznie odczytują nazwę bloku z atrybutu `data-block` znacznika skryptu, więc nie trzeba przekazywać jej ręcznie. W przypadku skryptów modułowych przekaż ją jako trzeci argument.

Opcje kontroli dostępu obejmują `public` (z CSRF), `'open'` (bez ochrony), ciągi uprawnień lub tablice. Obsługiwane są też kontrola metody HTTP dla każdej funkcji, haki cyklu życia i wywołania między blokami zarówno z JS, jak i PHP.

## Cron

Zadania działające w tle definiuje się w pliku `cron.php`. Ustaw harmonogram i funkcję zwrotną, a Blockstudio zarejestruje je podczas inicjalizacji w WordPress Cron. Po dezaktywacji wtyczki wszystkie zadania są poprawnie usuwane z harmonogramu.

```php title="cron.php"
return [
    'cleanup' => [
        'schedule' => 'daily',
        'callback' => function () {
            $db = Db::get('my-theme/app', 'logs');
            // delete old entries
        },
    ],
    'sync' => [
        'schedule' => 'hourly',
        'callback' => function () {
            // pull from external API
        },
    ],
];
```

Obsługiwane są wszystkie wbudowane harmonogramy WordPress oraz niestandardowe interwały konfigurowane przez filtr `cron_schedules`.

## CLI

Nowe polecenie `wp bs` obejmuje pełny zestaw funkcji Blockstudio: bloki, bazę danych, RPC, cron, ustawienia, kompilację Tailwind, kompilację SCSS, pola własne i zarządzanie zasobami.

```bash
wp bs blocks list --components
wp bs db schemas
wp bs db create my-theme/app subs --email=a@b.com
wp bs db list my-theme/app subs --plan=pro --format=json
wp bs rpc call my-theme/app subscribe --email=a@b.com
wp bs cron run my-theme/app cleanup
wp bs tailwind compile --file=template.html
wp bs scss compile --file=style.scss
wp bs fields list
wp bs assets list --type=global
wp bs settings get tailwind/enabled
```

Wszystkie polecenia obsługują `--format=json` do obsługi skryptów.

## Ulepszenia powtarzacza

### textMinimized dla pól obiektowych

Zwinięte wiersze powtarzacza poprawnie obsługują teraz wartości pól obiektowych. Wcześniej wskazanie pola łącza za pomocą `textMinimized` wyświetlało `[object Object]`. Teraz Blockstudio automatycznie odczytuje właściwą właściwość podrzędną na podstawie typu pola: `title` w przypadku łączy, `value` w przypadku kolorów i gradientów oraz `icon` w przypadku ikon. Możesz też ustawić właściwość `key`, aby odczytać dowolną wybraną właściwość podrzędną.

```json
{
  "type": "repeater",
  "textMinimized": { "id": "href", "fallback": "Add a link" },
  "attributes": [{ "id": "href", "type": "link" }]
}
```

### RichText i MediaPlaceholder

Oba komponenty szablonu działają teraz wewnątrz pól powtarzacza; notacja nawiasowa pozwala wskazać właściwy wiersz. Każdy wiersz powtarzacza może zawierać nagłówki i akapity edytowane bezpośrednio w treści oraz obszary przesyłania multimediów.

```twig
{% for item in a.items %}
  <div class="card">
    <MediaPlaceholder attribute="items[{{ loop.index0 }}].image" />
    <RichText tag="h2" attribute="items[{{ loop.index0 }}].heading" />
    <RichText tag="p" attribute="items[{{ loop.index0 }}].content" />
  </div>
{% endfor %}
```

## Warunki pól własnych z idStructure

Jeśli używasz pola własnego z `idStructure`, identyfikatory warunków w definicji pola są teraz automatycznie zmieniane, aby odpowiadały rozwiniętym nazwom. Jeśli grupa pól font-size zawiera warunek dotyczący `enable` i rozwijasz ją za pomocą `idStructure: "title_font_{id}"`, warunek prawidłowo odwołuje się teraz do `title_font_enable` zamiast do oryginalnego `enable`.

Obsługiwane są również warunki na poziomie odwołania. Dodaj `conditions` do odwołania do pola własnego, aby zastosować warunki jednocześnie do każdego rozwiniętego pola.

## Dynamiczne argumenty populate

Argumenty populate mogą teraz odwoływać się do atrybutów innych bloków za pomocą składni `{attributes.*}`. Gdy zmieni się wskazywany atrybut, pole wyboru automatycznie pobierze ponownie dostępne opcje. Możesz połączyć pola wyboru: jedno do wyboru typu wpisu, drugie do wczytywania wpisów tego typu.

```json
{
  "id": "selected_post",
  "type": "select",
  "populate": {
    "type": "query",
    "query": "posts",
    "arguments": {
      "post_type": "{attributes.post_type}"
    }
  }
}
```

Zmień `post_type` na "page", a drugie pole wyboru wczyta strony. Zmień na "post", a wczyta wpisy. Działa z dowolnym typem populate i atrybutem.

## Composer

Blockstudio działa teraz po wczytaniu z dowolnego miejsca w obrębie `wp-content/`, a nie tylko z katalogu wtyczek. Adresy URL zasobów są rozwiązywane za pomocą stałej `BLOCKSTUDIO_URL` zamiast `plugins_url()`, dzięki czemu instalacje z plikami dołączonymi do motywu działają od razu:

```php title="functions.php"
require_once __DIR__ . '/vendor/autoload.php';
require_once __DIR__ . '/vendor/blockstudio/blockstudio/blockstudio.php';
```

Oczyszczono zależności wykonawcze `composer.json`. Pakiety z przestrzeniami nazw (TailwindPHP, ScssPhp, Minify), które są już dołączone do `lib/`, nie są już wymienione jako zależności wykonawcze. Pozostały tylko `php >= 8.2` i `plugin-update-checker`.

Wszystkie trzy sposoby instalacji (archiwum ZIP wtyczki, wtyczka przez Composer, pliki motywu dołączone przez Composer) uruchamiają się tak samo: pełna aktywacja WordPress, rejestracja bloków i renderowanie interfejsu użytkownika.

Instrukcje konfiguracji znajdziesz w [Composer dokumentacji](https://blockstudio.dev/pl/docs/dev/composer/).

## Profiler wydajności

Dodaj `?blockstudio-perf` do dowolnego pliku strony URL, a u dołu pojawi się panel debugowania z czasem renderowania poszczególnych bloków, podziałem na etapy i współczynnikiem trafień w pamięć podręczną. Dane o czasie są również wysyłane w nagłówkach Server-Timing i widoczne w karcie Sieć w DevTools przeglądarki.

```json title="blockstudio.json"
{ "dev": { "perf": true } }
```

Włącz tę funkcję na stałe w ustawieniach, aby mierzyć czas wczytywania każdej strony. Jest widoczna tylko dla zalogowanych użytkowników z uprawnieniem `edit_posts`.

Samozamykające się tagi bloków są teraz buforowane w pamięci. Gdy ten sam blok z identycznymi atrybutami występuje na stronie kilka razy, kolejne renderowania pomijają cały proces renderowania szablonu.

## Poprawki błędów

- **Ostrzeżenia o wycofaniu PHP 8.4**: Naprawiono ostrzeżenia o wycofaniu `strpos()` i `str_replace()`, spowodowane przekazywaniem `null` do `add_submenu_page()`.

## Więcej

- **Pola kodu SCSS**: Pola kodu obsługują `language: "scss"`. Wartości są kompilowane przez ScssPhp zarówno w edytorze, jak i w interfejsie użytkownika.
- **Standardowe bloki WordPress**: Katalogi Blockstudio mogą zawierać wyjście `@wordpress/create-block` obok bloków Blockstudio. Są rejestrowane automatycznie, bez osobnego kodu wtyczki.

---

Jeśli chcesz zobaczyć wzorzec full-stack w praktyce, [Przewodnik po blokach full-stack](https://blockstudio.dev/pl/guides/full-stack-blocks/) pokazuje, jak od podstaw zbudować aplikację z listą zadań dla pojedynczego użytkownika i publiczny formularz zapisu do newslettera.
