Introduction

From Slack's Block Kit documentation:

Block Kit is a UI framework for Slack apps that offers a balance of control and flexibility when building experiences in messages and other surfaces.

Customize the order and appearance of information and guide users through your app's capabilities by composing, updating, sequencing, and stacking blocks — reusable components that work almost everywhere in Slack.

This library provides an OOP interface in PHP for composing messages/modals using Slack Block Kit. It also does the reverse, meaning you can "hydrate" message/modal JSON into an object hierarchy.

Block Kit Concepts

This library helps you build Slack messages and modals programmatically and dynamically in your code, but you need to know how they work generally first. The library does try to prevent you from doing things you are not permitted to do in Block Kit, but it may not validate against every single or condition.

You may want to review the following concepts in the Slack documentation:

• Surfaces – There are 3 main types: Message, Modal, and App Home
• Blocks – Includes section, context, actions, and more
• Block Elements – Includes buttons, menus, text inputs, and other interactive components. We call all of these "Elements" in this library.
• Composition Objects – We call these "Parts" in the library

In general, we refer to ALL of these different things in Block Kit collectively as "components".

Installation

Install easily via Composer:

Then include the Composer-generated autoloader in your project's initialization code.

Note: This library is built for PHP 8.1+.

Version 1 of this library supports version 7.3/7.4.

Basic Usage

This library supports an intuitive syntax for composing Slack surfaces (e.g., messages, modals) that utilizes PHP 8's named parameters feature.

The Kit Façade

The Kit class acts as a façade for the whole library's set of components and has factory methods for each one. It allows you to limit the number of classes you have to import to build a message (or other surface).

Each factory method has the same parameters as the original component's constructor.

Fluent Interface

If named parameters aren't your jam, there is another way to set a component's properties, through the setter methods. Each component has chainable setter methods for each of its properties, which allows for a fluent-style interface.

The fluent syntax is not dependent on the Kit façade. Component classes have a static new() method that can be used for chaining as well.

Null Values

All properties are considered as null/empty until set.

You can also set a property explicitly to null to remove its value (e.g., from a component you created from existing data).

Finally, null values are allowed in lists of blocks, elements, options, etc., so it's safe to use conditional items.

Preview in Block Kit Builder

Slack provides an interactive Block Kit Builder for composing/testing messages and other surfaces. This is a great way to play around with and learn the Block Kit format.

The Kit::preview method allows you to render your message/surface as a Block Kit Builder URL, so you can link to a preview or your message/surface in the browser via their interactive tool. This will help you see how it would be rendered in a Slack client.

Output

And here's the actual Block Kit Builder link.

It will show up in the Block Kit Builder looking something like this:

Component Hydration

Some Slack application integrations (such as with Modals) require receiving the JSON of an existing surface and then modifying or replacing that surface with another. You can "hydrate" the JSON of a surface (or element) into its object representation using its fromArray method (or fromJson).

Message Formatting

The Md class exists to provide helpers for formatting "mrkdwn" text. These helpers can be used so that you don't have to have the Slack mrkdwn syntax memorized. Also, these functions will properly escape <, >, and & characters automatically, if it's needed.

Example:

Example Result:

Virtual Blocks

In addition to the standard blocks, the following are virtual/custom blocks composed of one or more other blocks:

• TwoColumnTable - Uses Sections with Fields to create a two-column table with an optional header.
• CodeBlock - Uses Sections to create a code block with an optional header.

Class Structure

• Surfaces, Blocks, Elements, and Parts are all types of Block Kit Components.
• The Kit façade can be used as a factory to create any Component.
• Components contains properties and sub-Components that define their appearance and behavior.
• Parts are repeated patterns that form the properties of other Components.
• Surfaces contain one or more Blocks.
• Blocks contain one or more Elements.
• Most Elements are interactive in some way.
• Many Elements are also Inputs that receive user input.

[Kit]-creates>[Component]
[Surface]^[Message]
[Surface]^[Modal]
[Surface]^[AppHome]
[Surface]^[Attachment]
[Component]^[Surface]
[Component]^[Block]
[Component]^[Element]
[Component]^[Part]
[Component]<>->[Part]
[Surface]<>->[Block]
[Message]<>->[Attachment]
[Block]<>->[Element]
[Element]^[Input]
[Element]-[note:Examples: Button, OverflowMenu {bg:cornsilk}]
[Input]-[note:Examples: Select Menu, DatePicker {bg:cornsilk}]
[Part]-[note: Examples: Text, Fields {bg:cornsilk}]
[Block]-[note: Examples: Section, Actions {bg:cornsilk}]

Contributions

Contributions welcome to support new elements, add tests, improve code, etc.