MessageBuilder

Class  ·  Sharkord\Builders\MessageBuilder

Class MessageBuilder

Provides a fluent interface for constructing a message with optional file attachments before handing it off to a channel for dispatch.

Build a message with {@see \MessageBuilder::create()}, configure it with the fluent setters, then pass the instance directly to {@see \Sharkord\Models\Channel::sendMessage()}. Each queued file is read synchronously when the message is sent; the HTTP uploads are then dispatched concurrently. The builder is channel-agnostic until that point and can be prepared ahead of time or reused across multiple sends.

Examples

$builder = \Sharkord\Builders\MessageBuilder::create()
    ->setContent('Here are your files!')
    ->addFile('/tmp/photo.jpg')
    ->addFile('/tmp/report.pdf', 'application/pdf');

$sharkord->channels->get('media')->sendMessage($builder);

// Build once, send to multiple channels.
$sharkord->on(\Sharkord\Events::MESSAGE_CREATE, function(\Sharkord\Models\Message $message) {
    if ($message->content === '!logs') {
        $builder = \Sharkord\Builders\MessageBuilder::create()
            ->setContent('Latest log file:')
            ->addFile('/var/log/app.log', 'text/plain');

        $message->channel->sendMessage($builder)
            ->catch(function(\Throwable $e) use ($message) {
                $message->channel->sendMessage("Could not attach log: {$e->getMessage()}");
            });
    }
});

Methods

static create()

Creates a new MessageBuilder instance.

Use this static factory rather than new MessageBuilder() to enable a fully fluent one-liner construction style.

Returns static

Example

$builder = \Sharkord\Builders\MessageBuilder::create()
    ->setContent('Hello!')
    ->addFile('/tmp/file.txt');

---

setContent()

Sets the message body text.

Parameters

Parameter	Type	Description
$content	string	The message content.

Returns static — Returns the builder instance for method chaining.

Example

\Sharkord\Builders\MessageBuilder::create()->setContent('Hello, world!');

---

addFile()

Queues a local file to be uploaded and attached to the message.

Files are not uploaded until the builder is passed to {@see \Sharkord\Models\Channel::sendMessage()}. Each file is read synchronously at that point; the resulting HTTP uploads are then dispatched concurrently. Multiple calls append files in the order they are added. The MIME type is detected automatically via mime_content_type() when omitted; if detection fails, application/octet-stream is used as a safe fallback.

Parameters

Parameter	Type	Description
$filePath	string	The absolute or relative path to the file.
$mimeType (optional)	?string	MIME type override. Detected automatically when null.

Returns static — Returns the builder instance for method chaining.

Example

\Sharkord\Builders\MessageBuilder::create()
    ->addFile('/tmp/image.png')
    ->addFile('/tmp/data.csv', 'text/csv');

---

setReply()

Sets a user to be mentioned at the start of the message.

Produces a mention span identical to the one generated by {@see \Sharkord\Models\Message::reply()}, prepended before the message content when the message is dispatched. The content set via setContent() is appended after the mention and is escaped normally.

Parameters

Parameter	Type	Description
$user	User	The user to mention.

Returns static — Returns the builder instance for method chaining.

Example

$sharkord->on(\Sharkord\Events::MESSAGE_CREATE, function(\Sharkord\Models\Message $message) {
    $builder = \Sharkord\Builders\MessageBuilder::create()
        ->setReply($message->author)
        ->setContent('Thanks for your message!')
        ->addFile('/tmp/response.pdf');

    $message->channel->sendMessage($builder);
});

---

buildHtml()

Builds the final HTML string for the message body.

If a reply user has been set via setReply(), a mention span is prepended before the escaped content. The result is always wrapped in a <p> tag, matching the wire format expected by the messages.send RPC.

Returns string — The fully constructed HTML string ready for dispatch.

Example

$builder = \Sharkord\Builders\MessageBuilder::create()->setContent('Hello!');
echo $builder->buildHtml(); // "<p>Hello!</p>"

---

getContent()

Returns the message body text.

Returns string

Example

$builder = \Sharkord\Builders\MessageBuilder::create()->setContent('Hello!');
echo $builder->getContent(); // "Hello!"

---

getPendingFiles()

Returns the list of queued files.

Returns array<int,array{path: string, mime: string|null}>

Example

$builder = \Sharkord\Builders\MessageBuilder::create()
    ->addFile('/tmp/a.png')
    ->addFile('/tmp/b.pdf', 'application/pdf');

var_dump($builder->getPendingFiles());

---