VOOZH about

URL: https://deepwiki.com/hypervel/notifications/6.5.1-block-kit-contracts

⇱ Block Kit Contracts | hypervel/notifications | DeepWiki

Loading...
Loading...
Menu

Block Kit Contracts

Purpose and Scope

This document describes the three foundational contract interfaces that define the type system for Slack Block Kit components in the hypervel/notifications package. These contracts establish the structural requirements that all Block Kit blocks, elements, and objects must satisfy for proper serialization to the Slack API format.

For detailed information about specific Block Kit components that implement these contracts, see Block Types and Elements and Composites. For overall Block Kit usage patterns, see Slack Block Kit.

Contract Interface Hierarchy

The Block Kit type system is built on three marker interfaces that extend Hyperf\Contract\Arrayable. These contracts provide type safety while ensuring all components can be serialized to array format for JSON transmission to Slack's API.

The Three Core Contracts

ContractFile PathPurpose
BlockContractsrc/Contracts/Slack/BlockContract.php9-11Defines types that represent top-level block structures in Slack messages
ElementContractsrc/Contracts/Slack/ElementContract.php9-11Defines types for interactive and display elements contained within blocks
ObjectContractsrc/Contracts/Slack/ObjectContract.php9-11Defines types for composite objects used within blocks and elements

All three contracts share an identical structure—they extend Hyperf\Contract\Arrayable without adding additional method requirements. This design pattern provides type discrimination through the PHP type system while delegating serialization behavior to the Arrayable contract.

Sources: src/Contracts/Slack/BlockContract.php1-12 src/Contracts/Slack/ElementContract.php1-12 src/Contracts/Slack/ObjectContract.php1-12

Contract Interface Definitions

BlockContract



The BlockContract marks classes that represent Slack block types. Blocks are the top-level layout components in Slack messages. Implementations include section blocks, action blocks, divider blocks, header blocks, image blocks, and context blocks.


Sources: src/Contracts/Slack/BlockContract.php9-11


ElementContract




The ElementContract marks classes that represent interactive or display elements. Elements are contained within blocks and include buttons, images, text objects, and other UI components that users can interact with or view.


Sources: src/Contracts/Slack/ElementContract.php9-11


ObjectContract




The ObjectContract marks classes that represent composite objects used throughout Block Kit. These objects encapsulate related data such as confirmation dialogs, text objects with formatting, and option definitions.


Sources: src/Contracts/Slack/ObjectContract.php9-11




Diagram: Contract Type Hierarchy




Sources: src/Contracts/Slack/BlockContract.php9-11 src/Contracts/Slack/ElementContract.php9-11 src/Contracts/Slack/ObjectContract.php9-11




The Arrayable Requirement


All three Block Kit contracts extend Hyperf\Contract\Arrayable, which defines a single method:




This inheritance ensures every Block Kit component can be serialized to an array structure. The Slack API requires messages to be sent as JSON, and the array representation produced by toArray() must conform to Slack's Block Kit specification.


Serialization Pattern


The typical implementation pattern for Block Kit components is:


    

  1. The component stores its configuration in private properties
    2. 

  2. The toArray() method constructs an array matching Slack's expected schema
    3. 

  3. The array includes a type field identifying the component type
    4. 

  4. Additional fields are included based on the specific component's requirements
    5. 



This approach separates the PHP object interface from the JSON wire format, allowing the codebase to provide a fluent builder API while ensuring correct serialization.


Sources: src/Contracts/Slack/BlockContract.php7-11 src/Contracts/Slack/ElementContract.php7-11 src/Contracts/Slack/ObjectContract.php7-11




Diagram: Type System in Block Kit Context




Sources: src/Contracts/Slack/BlockContract.php9-11 src/Contracts/Slack/ElementContract.php9-11 src/Contracts/Slack/ObjectContract.php9-11




Type Safety and Composition


The contract interfaces provide compile-time type safety for Block Kit component composition. The type system enforces several structural constraints:


Block-Level Constraints


Methods that accept blocks are typed to accept BlockContract implementations:




This ensures that only valid block types (ActionsBlock, SectionBlock, etc.) can be added to a message's block array.


Element-Level Constraints


Methods that accept elements within blocks are typed to accept ElementContract implementations. For example, the ActionsBlock's elements parameter requires an array of ElementContract objects, preventing invalid element types from being added.


Object-Level Constraints


Methods that accept composite objects are typed to accept ObjectContract implementations. This ensures that confirmation dialogs, text objects, and other composite structures conform to the expected interface.


Sources: src/Contracts/Slack/BlockContract.php9-11 src/Contracts/Slack/ElementContract.php9-11 src/Contracts/Slack/ObjectContract.php9-11




Serialization to Slack API Format


The contract interfaces enable a two-phase serialization process:


Phase 1: Component Construction


Developers use fluent builder methods to construct Block Kit components with type-safe PHP objects:




Phase 2: Array Serialization


When the message is sent to Slack, each component's toArray() method is called recursively to build the JSON payload:




This recursive serialization produces the nested array structure that Slack's API expects, with proper type fields and component-specific properties.


Sources: src/Contracts/Slack/BlockContract.php7-11 src/Contracts/Slack/ElementContract.php7-11 src/Contracts/Slack/ObjectContract.php7-11




Diagram: Serialization Flow




Sources: src/Contracts/Slack/BlockContract.php7-11 src/Contracts/Slack/ElementContract.php7-11 src/Contracts/Slack/ObjectContract.php7-11




Interface Simplicity and Extension Points


The minimal interface definitions (no methods beyond Arrayable) provide flexibility for concrete implementations. Each implementation is free to:


    

  • Define its own constructor signature and required parameters
    • 

  • Implement validation logic in toArray() or constructor
    • 

  • Provide fluent setter methods for optional properties
    • 

  • Throw exceptions for invalid configurations
    • 



The contracts serve as type markers rather than behavioral contracts, allowing implementations to vary widely in their internal structure while maintaining API compatibility through the common toArray() serialization interface.


Sources: src/Contracts/Slack/BlockContract.php1-12 src/Contracts/Slack/ElementContract.php1-12 src/Contracts/Slack/ObjectContract.php1-12




Summary


The three Block Kit contract interfaces establish a minimal, marker-based type system for Slack message components:































AspectImplementation
Type SafetyPHP type hints enforce correct component composition
SerializationArrayable inheritance ensures all components can convert to arrays
SimplicityNo additional methods required beyond toArray()
FlexibilityImplementations define their own construction and validation logic
HierarchyThree-level hierarchy: Blocks contain Elements contain Objects


This design balances type safety with implementation flexibility, enabling a rich fluent API for Block Kit construction while ensuring correct serialization to Slack's JSON format.


Sources: src/Contracts/Slack/BlockContract.php1-12 src/Contracts/Slack/ElementContract.php1-12 src/Contracts/Slack/ObjectContract.php1-12