
# Зберігання

За замовчуванням усі значення полів зберігаються як атрибути блоку в коментарі блоку у вмісті запису. Функція зберігання дає змогу додатково зберігати значення в метаданих запису (`wp_postmeta`) або параметрах (`wp_options`), щоб вони були доступні поза контекстом блоку.

## Навіщо використовувати зберігання?

Атрибути блоків зберігаються в коментарях HTML у вмісті запису, тобто доступ до них є лише під час розбору вмісту блоків. Використання додаткових місць зберігання дає змогу:

- **Фільтрувати записи за значеннями полів** за допомогою `meta_query`
- **Отримувати доступ до значень через REST API** у безголових конфігураціях
- **Обмінюватися даними з іншими плагінами**, як-от SEO, або з плагінами кешування
- **Створювати глобальні налаштування**, які зберігаються для всіх записів

## Типи сховища

| Тип | Розташування | Область дії | Найкраще підходить для |
|------|----------|-------|----------|
| `postMeta` | таблиця `wp_postmeta` | Для кожного запису | Дані запису, за якими можна виконувати запити |
| `option` | таблиця `wp_options` | Глобально (для всього сайту) | Налаштування сайту, спільні значення |


> **Примітка**
>
> Атрибути блоків автоматично зберігаються у коментарі HTML у вмісті запису. Властивість `storage` додає **додаткові** місця зберігання — вона не замінює зберігання в блоці.


## Конфігурація

Додайте властивість `storage` до визначення будь-якого поля:

```json title="block.json"
{
  "name": "blockstudio/example",
  "title": "Example Block",
  "blockstudio": {
    "attributes": [
      {
        "id": "subtitle",
        "type": "text",
        "label": "Subtitle",
        "storage": {
          "type": "postMeta",
          "postMetaKey": "my_subtitle"
        }
      }
    ]
  }
}
```

## Властивості сховища

| Властивість | Тип | Опис |
|----------|------|-------------|
| `type` | `string` \| `string[]` | Додаткове місце зберігання location(s): `"postMeta"`, `"option"` |
| `postMetaKey` | `string` | Власний ключ метаданих (за замовчуванням: `{block_name}_{field_id}`) |
| `optionKey` | `string` | Власний ключ параметра (за замовчуванням: `{block_name}_{field_id}`) |

### Одне чи кілька місць зберігання

```json
// Add post meta storage
"storage": {
  "type": "postMeta"
}

// Add both post meta and option storage
"storage": {
  "type": ["postMeta", "option"]
}
```

## Як це працює

1. **Реєстрація**: коли WordPress завантажується, Blockstudio реєструє метаключі та налаштування на основі конфігурацій ваших полів
2. **Редагування**: значення керуються як атрибути блоку в редакторі (завжди зберігаються в блоці)
3. **Збереження**: метадані запису синхронізуються після збереження запису. Параметри сайту синхронізуються після публікації запису або зміни значення поля в опублікованому записі.

Автозбереження та редакції не синхронізують жодне зі сховищ. Чернетки, записи на затвердженні, приватні й заплановані записи можуть оновлювати власні метадані, але не змінюють активні параметри сайту. Параметри запланованого запису синхронізуються, коли WordPress публікує його.

Значення копіюються буквально, зокрема зворотні скісні риски, лапки та вкладені значення повторювача. Не додавайте екранування до значень полів, щоб компенсувати збереження метаданих WordPress; на цій межі це обробляє Blockstudio. Параметри сайту зберігають ті самі буквальні значення без додаткового екранування.

Якщо попередня версія видаляла зворотні скісні риски з копії метаданих запису, після оновлення збережіть запис ще раз. Для оновлення копії метаданих використовується початкове значення поля в атрибутах його блоку.

### Збереження параметрів сайту

Параметри спільні для всього сайту. Публікація нового блоку записує значення полів параметрів, задані в збережених атрибутах. Під час наступного збереження кожне поле порівнюється з попередньою збереженою версією цього блоку, і записуються лише змінені значення. Збереження заголовка запису або незміненої старішої копії блоку в іншому записі не перезаписує новіше значення параметра.

Поле, відсутнє серед збережених атрибутів, залишає відповідну опцію без змін. Це також захищає наявні опції, коли до `block.json` додається нове поле. Явне `null` видаляє опцію; порожні рядки, `false`, `0` і порожні масиви зберігаються як значення. Видалення блоку не видаляє його опції.

Використовуйте один призначений опублікований блок для керування кожною спільною опцією. Якщо кілька блоків навмисно змінюють ту саму опцію, зберігається останнє змінене значення. Сховище не завантажує поточну опцію в кожен блок: кожен блок зберігає власні значення полів у вмісті запису.

Для сторінок на основі файлів постійний ключ блоку `key` дає змогу Blockstudio розпізнавати той самий блок після його переміщення в документі. Блоки без ключа зіставляються за назвою блоку та позицією.


## Доступ до збережених значень

### У шаблонах блоків

У шаблоні блоку значення полів завжди доступні через `$attributes`:


#### PHP

```php title="index.php"
<div>
  <h1><?php echo $a['subtitle']; ?></h1>
</div>
```

#### Twig

```twig title="index.twig"
<div>
  <h1>{{ a.subtitle }}</h1>
</div>
```

### Метадані запису (поза контекстом блоку)

Значення, збережені в `postMeta`, доступні будь-де в WordPress:


#### PHP

```php
// Get meta value
$subtitle = get_post_meta( $post_id, 'my_subtitle', true );

// Query posts by meta value
$posts = get_posts([
  'meta_key'   => 'my_subtitle',
  'meta_value' => 'Hello World',
]);
```

#### Twig

```twig
{# Using Timber #}
{{ post.meta('my_subtitle') }}

{# Or via function #}
{{ function('get_post_meta', post.id, 'my_subtitle', true) }}
```

Метадані запису також доступні через REST API:

```bash
GET /wp-json/wp/v2/posts/123
# Response includes: { "meta": { "my_subtitle": "Hello World" } }
```

### Опції (глобальні значення)

Значення, збережені в `option`, доступні на всьому сайті:


#### PHP

```php
$company_name = get_option( 'site_company_name' );
```

#### Twig

```twig
{{ function('get_option', 'site_company_name') }}
```

## Приклади

### Поля метаданих SEO

Зберігайте дані SEO у метаданих запису для сумісності з плагінами SEO:

```json title="block.json"
{
  "blockstudio": {
    "attributes": [
      {
        "id": "seo_title",
        "type": "text",
        "label": "SEO Title",
        "storage": {
          "type": "postMeta",
          "postMetaKey": "_yoast_wpseo_title"
        }
      },
      {
        "id": "seo_description",
        "type": "textarea",
        "label": "Meta Description",
        "storage": {
          "type": "postMeta",
          "postMetaKey": "_yoast_wpseo_metadesc"
        }
      }
    ]
  }
}
```

### Рекомендований вміст із запитами

Додайте сховище метаданих запису, щоб можна було запитувати записи за значенням поля:

```json title="block.json"
{
  "blockstudio": {
    "attributes": [
      {
        "id": "featured",
        "type": "toggle",
        "label": "Featured",
        "storage": {
          "type": "postMeta",
          "postMetaKey": "is_featured"
        }
      }
    ]
  }
}
```

Запит рекомендованих записів:

```php
$featured_posts = get_posts([
  'meta_key'   => 'is_featured',
  'meta_value' => '1',
]);
```

### Глобальні налаштування сайту

Зберігайте конфігурацію всього сайту в опціях:

```json title="block.json"
{
  "blockstudio": {
    "attributes": [
      {
        "id": "company_name",
        "type": "text",
        "label": "Company Name",
        "storage": {
          "type": "option",
          "optionKey": "site_company_name"
        }
      },
      {
        "id": "support_email",
        "type": "text",
        "label": "Support Email",
        "storage": {
          "type": "option",
          "optionKey": "site_support_email"
        }
      }
    ]
  }
}
```

Доступ будь-де на сайті:

```php
<footer>
  <p>&copy; <?php echo get_option( 'site_company_name' ); ?></p>
  <p>Contact: <?php echo get_option( 'site_support_email' ); ?></p>
</footer>
```

### Метадані запису та опція

Для даних, які мають бути доступні і на рівні запису, і глобально:

```json title="block.json"
{
  "blockstudio": {
    "attributes": [
      {
        "id": "important_value",
        "type": "text",
        "label": "Important Value",
        "storage": {
          "type": ["postMeta", "option"],
          "postMetaKey": "important_meta",
          "optionKey": "important_option"
        }
      }
    ]
  }
}
```

## Назви ключів за замовчуванням

Якщо не вказати власний ключ, Blockstudio автоматично згенерує його:

| Тип сховища | Формат ключа за замовчуванням | Приклад |
|--------------|-------------------|---------|
| `postMeta` | `{block_name}_{field_id}` | `blockstudio_example_subtitle` |
| `option` | `{block_name}_{field_id}` | `blockstudio_example_subtitle` |

Назва блоку нормалізується (слеші замінюються підкресленнями).


> **Попередження**
>
> Для використання у виробничому середовищі рекомендуються власні ключі. Ключі за замовчуванням можуть змінитися, якщо перейменувати блок.
