> For the complete documentation index, see [llms.txt](https://docs.acpt.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.acpt.io/developers/functions/save_acpt_block.md).

# save\_acpt\_block

Create or update a dynamic block

Create or update a dynamic block.

Performs an upsert: if a block with the given `name` already exists (and no `id` is passed), its existing settings are merged with the ones you provide — so a partial update (e.g. just changing `title`) doesn't wipe `keywords`/`postTypes`/`controls` you didn't resend.

### Usage

```php
save_acpt_block([
    'name'      => 'my_block',
    'title'     => 'My Block',
    'category'  => 'widgets',
    'icon'      => 'smiley',
    'keywords'  => ['my', 'block'],
    'postTypes' => ['post', 'page'],
    'controls'  => [
        [
            'name'  => 'heading',
            'label' => 'Heading',
            'type'  => 'Text',
        ],
    ],
]);
```

To update an existing block, include its `id`:

```php
save_acpt_block([
    'id'    => 'a1b2c3d4-...',
    'name'  => 'my_block',
    'title' => 'My Block (updated)',
]);
```

### Parameters

| Parameter   | Type            | Required | Description                                                                                                                                                                                                                                            |
| ----------- | --------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`      | string          | Required | The block slug (must be unique)                                                                                                                                                                                                                        |
| `id`        | string          | Optional | Block UUID — if provided, updates the existing block instead of resolving it by `name`                                                                                                                                                                 |
| `title`     | string          | Optional | The human-readable block title                                                                                                                                                                                                                         |
| `category`  | string          | Optional | The block inserter category slug                                                                                                                                                                                                                       |
| `icon`      | string \| array | Optional | A Dashicon slug or an SVG icon definition for the block inserter                                                                                                                                                                                       |
| `css`       | string          | Optional | Custom CSS scoped to this block                                                                                                                                                                                                                        |
| `callback`  | string          | Optional | PHP callback used to render the block on the front end                                                                                                                                                                                                 |
| `keywords`  | array           | Optional | Search keywords shown in the block inserter                                                                                                                                                                                                            |
| `postTypes` | array           | Optional | Post type slugs this block is restricted to. Empty/omitted means all post types                                                                                                                                                                        |
| `controls`  | array           | Optional | Editor controls exposed for this block — each entry: `name` (required), `label`, `type` (one of `Checkbox`, `Radio`, `Select`, `SelectMulti`, `Toggle`, `Text`, `Textarea`, `Number`, `Range`, `Email`, `Phone`), `default`, `description`, `settings` |

### Return

| Type   | Description                           |
| ------ | ------------------------------------- |
| `bool` | `true` on success, `false` on failure |