README

A PHP library for building Slack Block Kit messages programmatically.

Block Kit PHP makes it easier to construct Slack Block Kit payloads in PHP without manually writing JSON. You can build complex modals, messages, and interactive elements using PHP objects, arrays, or method chaining.

Features

• Build Slack Block Kit messages entirely in PHP.
• Supports all Slack Block Kit blocks, surfaces, elements & objects.
• Construct blocks using static helpers or object instances.
• Method chaining for a fluent API.
• Full type hints and docblocks on all methods.
• Strict input validation to ensure payloads comply with Slack's Block Kit rules.
• Convert payloads to JSON or array for Slack API consumption.
• Compatible with PHP 8.1+.

Installation

Install via Composer:

composer require two16D/block-kit-php

Quick Example

use BlockKitPHP\Surfaces;
use BlockKitPHP\Blocks;
use BlockKitPHP\Elements;
use BlockKitPHP\Objects;
use BlockKitPHP\RichTextElements;
use BlockKitPHP\RichTextObjects;

$modal = Surfaces::modal(
    'Create Task',
    [
        Blocks::section([
            'block_id' => 'intro',
            'text' => Objects::markdownText("*Create a new task* and assign it to your team.\nPlease fill in the details below."),
        ]),
        Blocks::input(
            'Task title',
            Elements::plainTextInput([
                'action_id' => 'title_input',
                'placeholder' => 'e.g. Prepare Q4 report',
            ]),
            ['block_id' => 'task_title'],
        ),
        Blocks::input(
            'Due date',
            Elements::datePicker([
                'action_id' => 'due_date_select',
                'placeholder' => 'Select a date',
            ]),
            ['block_id' => 'due_date'],
        ),
        Blocks::section([
            'block_id' => 'priority',
            'text' => Objects::markdownText('Set the task *priority*:'),
            'accessory' => Elements::staticSelect([
                'action_id' => 'priority_select',
                'placeholder' => 'Choose priority',
                'options' => [
                    Objects::option('Low', 'low'),
                    Objects::option('Medium', 'medium'),
                    Objects::option('High', 'high'),
                ],
            ]),
        ]),
        Blocks::actions(
            [
                Elements::button('Preview', ['action_id' => 'preview_task', 'style' => 'primary']),
                Elements::button('Clear', [
                    'action_id' => 'delete_draft',
                    'confirm' => Objects::confirmationDialog(
                        'Clear all fields?',
                        'This will remove all entered information.',
                        'Yes, clear',
                        'Keep editing'
                    ),
                ]),
            ],
            ['block_id' => 'footer_actions']
        ),
    ],
    [
        'close' => 'Cancel',
        'submit' => 'Save',
        'callback_id' => 'task_create_modal',
    ]
);

// Convert to JSON
$json = $modal->toJson();

// Or convert to array
$array = $modal->array();

Usage Patterns

// Helper style
$text = Objects::plainText('Hello world', ['emoji' => true]);

// Object style
$text = new PlainText('Hello world', ['emoji' => true]);

// Method chaining
$button = Elements::button('Click me')->setStyle('primary')->setActionId('click_me');

Blocks and Classes

Block Kit PHP is organized to reflect Slack's Block Kit model. This helps you compose messages modularly and clearly.

Surfaces

The top-level entry points for creating Slack payloads. All other classes ultimately feed into these surface objects.

• Message: Surfaces::message(...)
• Modal: Surfaces::modal(...)
• App Home (Home Tab): Surfaces::appHome(...)

Blocks

Blocks are the main structural elements of a Slack message. For example:

• Actions: Blocks::actions(...)
• Section: Blocks::section(...)
• Input: Blocks::input(...)
• Divider, Header, Image, RichText, Table, Video ...

Elements

Elements are interactive components that live inside blocks:

• Button: Elements::button(...)
• Select menus: Elements::staticSelect(...), Elements::usersSelect(...)
• Inputs: Elements::plainTextInput(...), Elements::datePicker(...)
• Checkboxes, Image, Overflow, WorkflowButton ...

Objects

Objects represent smaller data structures used inside blocks or elements:

• Text objects: Objects::plainText(...), Objects::markdownText(...)
  • Options and option groups: Objects::option(...), Objects::optionGroup(...)
  • Confirmation dialogues (Objects::confirmationDialog(...))
  • Workflow triggers, Slack files, Conversation filters ...

RichText

RichText allows creating Slack’s advanced text formatting blocks. It has its own hierarchy:

• Rich Text Elements: RichTextElements::section(...), RichTextElements::list(...), ...
• Rich Text Objects: RichTextObjects::text(...), RichTextObjects::link(...), ...

Contributing

• Open a GitHub issue for bugs or feature requests.
• Pull requests should include tests where appropriate.
• Keep code style PSR-12 compliant.

License

MIT License. See LICENSE for details.