Messages

Messages represent the different types of content that can be exchanged in a conversation. LLM Magic provides several message types to handle text, structured data, tool calls, and tool results.

Message Interface

All message types implement the Message interface, which provides core functionality for conversation management. Location: src/Magic/Chat/Messages/Message.php:9

Methods

toArray(): array - Convert the message to an array representation
fromArray(array $data): static - Create a message instance from an array
text(): ?string - Get the text representation of the message
role(): Role - Get the role associated with this message (User, Assistant, or System)

TextMessage

Simple text-based messages for standard conversation exchanges. Location: src/Magic/Chat/Messages/TextMessage.php:7

Constructor

role

Role

required

The role of the message sender (User, Assistant, or System)

content

string

required

The text content of the message

Static Methods

user()

Create a user message.

TextMessage::user('What is the weather today?')

content

string

required

The message content

assistant()

Create an assistant message.

TextMessage::assistant('The weather is sunny today.')

content

string

required

The message content

fromChunk()

Create a message from a streaming chunk. Used for streaming responses.

TextMessage::fromChunk('Hello')

chunk

string

required

The text chunk to create the message from

Instance Methods

append()

Append additional text to the message content. Returns the message instance for chaining.

$message->append(' world!')

chunk

string

required

The text to append

JsonMessage

Messages containing structured JSON data. Useful for extracting structured information from AI responses. Location: src/Magic/Chat/Messages/JsonMessage.php:9

Constructor

role

Role

required

The role of the message sender

data

array

required

The structured data as an associative array

partial

string

default:"null"

The partial JSON string (used during streaming)

Methods

data()

Get the structured data from the message.

$data = $message->data();

Returns the parsed JSON data as an array.

append()

Append a JSON chunk during streaming. Automatically parses partial JSON.

$message->append('{"key": "val')

chunk

string

required

The JSON chunk to append

fromChunk()

Create a JsonMessage from a streaming chunk.

JsonMessage::fromChunk('{"status":')

chunk

string

required

The JSON chunk

ToolCallMessage

Represents a request from the AI to call a specific tool or function. Location: src/Magic/Chat/Messages/ToolCallMessage.php:9

Constructor

role

Role

required

The role of the message sender (typically Assistant)

call

ToolCall

default:"null"

The tool call details (name, arguments, id)

partial

string

default:"null"

Partial JSON string for streaming tool calls

schema

array

default:"null"

Optional JSON schema for validating tool arguments

Static Methods

call()

Create a tool call message from a ToolCall instance.

$toolCall = new ToolCall(
    name: 'get_weather',
    arguments: ['location' => 'San Francisco'],
    id: 'call_123'
);
ToolCallMessage::call($toolCall)

call

ToolCall

required

The tool call to create a message from

fromChunk()

Create from a streaming chunk of tool call data.

ToolCallMessage::fromChunk('{"name":"get_weather"')

chunk

string

required

The tool call JSON chunk

Methods

data()

Get the tool call arguments.

$args = $message->data(); // ['location' => 'San Francisco']

append()

Append tool call data during streaming. Parses partial JSON.

$message->append(',"arguments":{')

chunk

string

required

The chunk to append

appendFull()

Append with full tool call structure parsing.

$message->appendFull('{"name":"tool","parameters":{}}')

chunk

string

required

The chunk to append

ToolResultMessage

Contains the result of a tool execution, sent back to the AI. Location: src/Magic/Chat/Messages/ToolResultMessage.php:8

Constructor

role

Role

required

The role of the message sender (typically User)

call

ToolCall

required

The original tool call this result corresponds to

output

mixed

required

The result of the tool execution (string, array, or other data)

endConversation

bool

default:"false"

Whether this result should end the conversation

Static Methods

output()

Create a tool result message with successful output.

ToolResultMessage::output($toolCall, 'Temperature: 72°F')

call

ToolCall

required

The original tool call

output

mixed

required

The tool execution result

end()

Create a result that ends the conversation.

ToolResultMessage::end($toolCall, 'Task completed')

call

ToolCall

required

The original tool call

output

mixed

required

The final output

error()

Create an error result message.

ToolResultMessage::error($toolCall, 'API connection failed')

call

ToolCall

required

The original tool call

message

string

required

The error message

canceled()

Create a canceled tool result.

ToolResultMessage::canceled($toolCall)

call

ToolCall

required

The tool call that was canceled

Methods

data()

Get the output as an array (if possible).

$data = $message->data();

json()

Get the output as a JSON array.

$json = $message->json();

withOutput()

Create a new instance with different output.

$newMessage = $message->withOutput(['status' => 'updated'])

output

mixed

required

The new output value

ToolCall

Represents a single tool invocation request. Location: src/Magic/Chat/Messages/ToolCall.php:8

Constructor

name

string

required

The name of the tool to call

arguments

array

required

The arguments to pass to the tool

string

default:"null"

Unique identifier for this tool call

Static Methods

tryFrom()

Safely create a ToolCall from an array, returning null if invalid.

$toolCall = ToolCall::tryFrom($data);

data

array|null

The array data to create from

fromArray()

Create a ToolCall from an array.

$toolCall = ToolCall::fromArray([
    'name' => 'search',
    'arguments' => ['query' => 'PHP'],
    'id' => 'call_456'
])

data

array

required

The array containing tool call data

DataMessage Interface

Interface for messages that contain structured data. Location: src/Magic/Chat/Messages/DataMessage.php:5 Implemented by JsonMessage, ToolCallMessage, and ToolResultMessage.

Methods

data(): ?array - Get the structured data from the message

PartialMessage Interface

Interface for messages that support streaming updates. Location: src/Magic/Chat/Messages/PartialMessage.php:5 Implemented by TextMessage, JsonMessage, and ToolCallMessage.

Methods

append(string $chunk): static - Append a chunk to the message
fromChunk(string $chunk): static - Create a message from an initial chunk

Role Enum

Defines the participant roles in a conversation. Location: src/Magic/Chat/Prompt/Role.php:5

Values

Role::User - Messages from the user/human
Role::Assistant - Messages from the AI assistant
Role::System - System-level instructions and context

Usage

use Mateffy\Magic\Chat\Prompt\Role;

$message = new TextMessage(Role::User, 'Hello');

Core API

Tools

Models & Providers

​Message Interface

​Methods

​TextMessage

​Constructor

​Static Methods

​user()

​assistant()

​fromChunk()

​Instance Methods

​append()

​JsonMessage

​Constructor

​Methods

​data()

​append()

​fromChunk()

​ToolCallMessage

​Constructor

​Static Methods

​call()

​fromChunk()

​Methods

​data()

​append()

​appendFull()

​ToolResultMessage

​Constructor

​Static Methods

​output()

​end()

​error()

​canceled()

​Methods

​data()

​json()

​withOutput()

​ToolCall

​Constructor

​Static Methods

​tryFrom()

​fromArray()

​DataMessage Interface

​Methods

​PartialMessage Interface

​Methods

​Role Enum

​Values

​Usage

Build docs developers (and LLMs) love

Message Interface

Methods

TextMessage

Constructor

Static Methods

user()

assistant()

fromChunk()

Instance Methods

append()

JsonMessage

Constructor

Methods

data()

append()

fromChunk()

ToolCallMessage

Constructor

Static Methods

call()

fromChunk()

Methods

data()

append()

appendFull()

ToolResultMessage

Constructor

Static Methods

output()

end()

error()

canceled()

Methods

data()

json()

withOutput()

ToolCall

Constructor

Static Methods

tryFrom()

fromArray()

DataMessage Interface

Methods

PartialMessage Interface

Methods

Role Enum

Values

Usage