Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/phpaisdk/core/llms.txt

Use this file to discover all available pages before exploring further.

Message is the immutable value object that represents a single turn in a conversation. Every generation request is ultimately a sequence of Message instances. A message carries a role (user, assistant, system, or tool), an array of typed Content parts, and optional metadata such as a tool call ID or pending tool calls. Use the static factory methods to construct messages; the constructor is private.

​
Constants

ConstantValue
Message::ROLE_SYSTEM'system'
Message::ROLE_USER'user'
Message::ROLE_ASSISTANT'assistant'
Message::ROLE_TOOL'tool'

​
Factory methods

​
user()

Create a user-role message. Accepts a plain string or an array of Content objects for multi-part messages (e.g. text + image). 
public static function user(string|array $content): self
​
content
string | Content[]
required
A plain string — automatically wrapped in a single Content::text() part — or an array of Content instances. Throws InvalidArgumentException if any array element is not a Content instance.
// Simple text message
$msg = Message::user('What is in this image?');

// Multi-part message with an image
$msg = Message::user([
    Content::text('What is in this image?'),
    Content::image('https://example.com/photo.jpg'),
]);

​
assistant()

Create an assistant-role message, optionally with pending tool calls. 
public static function assistant(string|array $content, array $toolCalls = []): self
​
content
string | Content[]
required
The assistant’s text response, or an array of Content parts.
​
toolCalls
ToolCall[]
default:"[]"
An array of ToolCall value objects representing tool invocations the model requested in this turn.
// Simple assistant reply
$msg = Message::assistant('The capital of France is Paris.');

// Assistant reply that also invoked a tool
$msg = Message::assistant('Let me check the weather.', toolCalls: $response->toolCalls());

​
system()

Create a system-role message that provides instructions or context before the conversation begins. 
public static function system(string $text): self
​
text
string
required
The system instruction text. Wrapped in a single Content::text() part internally.
$msg = Message::system('You are a helpful assistant that responds only in formal English.');

​
tool()

Create a tool-result message that delivers the output of a tool call back to the model. 
public static function tool(string $toolCallId, string $output, ?string $name = null): self
​
toolCallId
string
required
The identifier of the tool call this result corresponds to, matching the ToolCall::id from the model’s previous response.
​
output
string
required
The serialised tool output. Non-string results should be JSON-encoded before passing here.
​
name
string | null
default:"null"
The name of the tool that was called. Some providers require this field.
$msg = Message::tool(
    toolCallId: 'call_abc123',
    output: json_encode(['temperature' => 22, 'conditions' => 'Sunny']),
    name: 'get_weather',
);

​
Properties

​
role
string
The conversation role. One of 'user', 'assistant', 'system', or 'tool'. Use the ROLE_* constants for safe comparisons.
​
content
Content[]
An indexed array of Content parts that make up the message body. Always contains at least one element.
​
name
string | null
The tool name associated with a 'tool'-role message, or null for other roles.
​
toolCallId
string | null
The tool call ID for a 'tool'-role message, linking this result to the model’s prior tool invocation. null for other roles.
​
toolCalls
ToolCall[]
An indexed array of ToolCall objects present on 'assistant'-role messages. Empty for all other roles.

​
Methods

​
text()

Concatenate and return the text of all Content::TYPE_TEXT parts in this message. 
public function text(): string
​
return
string
A single string formed by concatenating the textValue() of every text-type content part. Returns an empty string if there are no text parts.
$msg = Message::user('Hello, world!');
echo $msg->text(); // "Hello, world!"

// Multi-part message — only text parts are concatenated
$msg = Message::user([
    Content::text('Part one. '),
    Content::image('https://example.com/img.png'),
    Content::text('Part two.'),
]);
echo $msg->text(); // "Part one. Part two."

​
Examples

​
Building a full conversation history

$messages = [
    Message::system('You are a senior PHP developer. Answer concisely.'),
    Message::user('What is the difference between abstract classes and interfaces in PHP?'),
    Message::assistant('Abstract classes can have implemented methods and properties; interfaces only declare method signatures. A class can implement multiple interfaces but only extend one abstract class.'),
    Message::user('Can you show an example?'),
];

$result = Generate::text()
    ->messages($messages)
    ->run();

​
Multi-part user message with image and audio

$message = Message::user([
    Content::text('Please transcribe this audio and describe the attached image.'),
    Content::audio('/path/to/recording.mp3'),
    Content::image('https://cdn.example.com/scene.png'),
]);

$result = Generate::text()
    ->messages([$message])
    ->run();

​
Manually constructing a tool result turn

// Step 1: model returns a tool call
$response = Generate::text()
    ->prompt('What is the weather in Tokyo?')
    ->tool($weatherTool)
    ->run();

// Step 2: append the assistant turn and the tool result
$history = [
    Message::user('What is the weather in Tokyo?'),
    Message::assistant($response->text, toolCalls: $response->toolCalls),
    Message::tool(
        toolCallId: $response->toolCalls[0]->id,
        output: '{"temperature":18,"conditions":"Partly cloudy"}',
        name: 'get_weather',
    ),
];

// Step 3: continue the conversation
$final = Generate::text()->messages($history)->run();
echo $final->text;

Build docs developers (and LLMs) love

Get started for freeTalk to us