DiscordPHP Documentation

MessageBuilder extends Builder
in package
implements JsonSerializable uses ComponentsTrait

Helper class used to build messages.

Tags
since
7.0.0
author

David Cole david.cole1340@gmail.com

Table of Contents

Interfaces

JsonSerializable

Properties

$allowed_mentions  : AllowedMentions|array<string|int, mixed>|null
Allowed mentions object for the message.
$attachments  : array<string|int, array<string|int, mixed>>
Attachments to send with this message.
$avatar_url  : string|null
Override the default avatar of the webhook.
$components  : array<string|int, ComponentObject>
Components of the builder.
$content  : string|null
Content of the message.
$embeds  : array<string|int, array<string|int, mixed>>|null
Array of embeds to send with the message.
$enforce_nonce  : bool|null
Whether to enforce the nonce.
$files  : array<string|int, array<string|int, mixed>>
Files to send with this message.
$flags  : int|null
Flags to send with this message.
$message_reference  : MessageReference|null
Include to make your message a reply or a forward.
$nonce  : int|string|null
A nonce that can be used for message roundtrips with the gateway (up to 25 characters).
$poll  : PollCreateRequest|null
The poll for the message.
$shared_client_theme  : SharedClientTheme|null
Shared client theme for the message.
$sticker_ids  : array<string|int, string>
IDs of up to 3 stickers in the server to send in the message.
$tts  : bool|null
Whether the message is text-to-speech.
$username  : string|null
Override the default username of the webhook.

Methods

__get()  : mixed
Handles dynamic get calls onto the part.
__set()  : void
Handles dynamic set calls onto the part.
_setFlags()  : self
addAttachment()  : self
Adds attachment(s) to the builder.
addComponent()  : self
Adds a component to the builder.
addComponents()  : self
Adds the components to the builder.
addEmbed()  : self
Adds an embed to the builder.
addFile()  : self
Adds a file attachment to the builder.
addFileFromContent()  : self
Adds a file attachment to the builder with a given filename and content.
addSticker()  : self
Adds a sticker to the builder. Only used for sending message or creating forum thread.
clearAttachments()  : self
Removes all attachments from the message.
clearFiles()  : self
Removes all files from the builder.
countTotalComponents()  : int
Recursively counts the total number of components, including nested components, in the given array.
create()  : Message
Creates the message in the given repository.
fromPart()  : self
Creates a new instance of the builder from a given Part.
getAllowedMentions()  : array<string|int, mixed>|null
getAttachments()  : array<string|int, array<string|int, mixed>>
Returns all the attachments in the builder.
getAvatarUrl()  : string|null
Retrieves the avatar URL associated with the webhook. Only used for executing webhook.
getComponents()  : array<string|int, ComponentObject>
Returns all the components in the builder.
getContent()  : string|null
Retrieves the content of the message.
getEmbeds()  : array<string|int, array<string|int, mixed>>|null
Returns all the embeds in the builder.
getEnforceNonce()  : bool|null
Retrieves the value indicating whether the nonce should be enforced.
getFiles()  : array<string|int, array<string|int, mixed>>
Retrieves the files attached to the message builder.
getFlags()  : int
Get the current flags of the message.
getForward()  : Message|null
Retrieves the forwarded message associated with this builder, if any.
getMessageReference()  : MessageReference|null
Retrieves the message reference from the builder.
getNonce()  : int|string|null
Retrieves the nonce value associated with the message.
getPayloadJson()  : string
JSON-encoded body of non-file params, only for multipart/form-data requests.
getPoll()  : PollCreateRequest|null
Returns the poll of the message.
getReplyTo()  : Message|null
Retrieves the message that this builder is set to reply to, if any.
getSharedClientTheme()  : SharedClientTheme|null
Returns the shared client theme of the message.
getStickers()  : array<string|int, string>
Returns all the sticker ids in the builder.
getTts()  : bool
Returns the value of TTS of the builder.
getUsername()  : string|null
Retrieves the username associated with the message, if set.
jsonSerialize()  : array<string|int, mixed>
new()  : static
Creates a new message builder.
numFiles()  : int
Returns the number of files attached to the builder.
removeComponent()  : self
Removes a component from the builder.
removeSticker()  : self
Removes a sticker from the builder.
requiresMultipart()  : bool
Returns a boolean that determines whether the message needs to be sent via multipart request, i.e. contains files.
setAllowedMentions()  : self
Sets the allowed mentions object of the message.
setAttachments()  : self
Sets the attachments of the builder. Removes the existing attachments in the process.
setAvatarUrl()  : self
Override the default avatar URL of the webhook. Only used for executing webhook.
setComponents()  : self
Sets the components of the builder.
setContent()  : self
Sets the content of the message.
setEmbeds()  : self
Sets the embeds for the message. Clears the existing embeds in the process.
setEnforceNonce()  : self
If true and nonce is present, it will be checked for uniqueness in the past few minutes.
setFiles()  : self
Sets the files to be attached to the message.
setFlags()  : self
Sets the flags of the message.
setForward()  : self
Sets this message as a forward of another message. Only used for sending message.
setIsComponentsV2Flag()  : self
Sets or unsets the IS_COMPONENTS_V2 flag for the message.
setIsVoiceMessageFlag()  : self
Sets or unsets the IS_VOICE_MESSAGE flag for the message.
setMessageReference()  : self
Include to make your message a reply or a forward.
setNonce()  : self
Sets the nonce of the message. Only used for sending message.
setPoll()  : self
Sets the poll of the message.
setReplyTo()  : self
Sets this message as a reply to another message. Only used for sending message.
setSharedClientTheme()  : self
Sets the shared client theme of the message.
setStickers()  : self
Sets the stickers of the builder. Removes the existing stickers in the process.
setSuppressEmbedsFlag()  : self
Sets or unsets the SUPPRESS_EMBEDS flag for the message.
setSuppressNotificationsFlag()  : self
Sets or unsets the SUPPRESS_NOTIFICATIONS flag for the message.
setTts()  : self
Sets the TTS status of the message. Only used for sending message or executing webhook.
setUsername()  : self
Override the default username of the webhook. Only used for executing webhook.
setV2Flag()  : self
Sets or unsets the IS_COMPONENTS_V2 flag for the message.
checkForGetMutator()  : string|false
Checks if there is a get mutator present.
checkForSetMutator()  : string|false
Checks if there is a set mutator present.
enforceV1Limits()  : void
Enforces the component limits and structure for v1 messages.
enforceV2Limits()  : void
Validates the total number of components added to the message.
getProperty()  : mixed
Gets a property on the parent part.
setProperty()  : void
Sets an property on the parent part.
studly()  : string
Converts a string to studlyCase.

Properties

$attachments

Attachments to send with this message.

protected array<string|int, array<string|int, mixed>> $attachments

$avatar_url

Override the default avatar of the webhook.

protected string|null $avatar_url

$embeds

Array of embeds to send with the message.

protected array<string|int, array<string|int, mixed>>|null $embeds

$enforce_nonce

Whether to enforce the nonce.

protected bool|null $enforce_nonce

$files

Files to send with this message.

protected array<string|int, array<string|int, mixed>> $files = []

$flags

Flags to send with this message.

protected int|null $flags

$nonce

A nonce that can be used for message roundtrips with the gateway (up to 25 characters).

protected int|string|null $nonce

$sticker_ids

IDs of up to 3 stickers in the server to send in the message.

protected array<string|int, string> $sticker_ids = []

$tts

Whether the message is text-to-speech.

protected bool|null $tts

$username

Override the default username of the webhook.

protected string|null $username

Methods

__get()

Handles dynamic get calls onto the part.

public __get(string $key) : mixed
Parameters
$key : string

The attributes key.

Tags
throws
Exception
see
self::getAttribute()

This function forwards onto getAttribute.

Return values
mixed —

The value of the attribute.

__set()

Handles dynamic set calls onto the part.

public __set(string $key, mixed $value) : void
Parameters
$key : string

The attributes key.

$value : mixed

The attributes value.

Tags
see
self::setAttribute()

This function forwards onto setAttribute.

_setFlags()

public _setFlags(int $flags) : self

Use MessageBuilder::setFlags()

Parameters
$flags : int
Return values
self

addAttachment()

Adds attachment(s) to the builder.

public addAttachment(Attachment|string|int ...$attachments) : self
Parameters
$attachments : Attachment|string|int

Attachment objects or IDs to add

Return values
self

addComponent()

Adds a component to the builder.

public addComponent(ComponentObject $component) : self
Parameters
$component : ComponentObject

Component to add.

Tags
throws
InvalidArgumentException

Component is not a valid type.

OverflowException

Builder exceeds component limits.

Return values
self

addComponents()

Adds the components to the builder.

public addComponents(array<string|int, ComponentObject> $components) : self
Parameters
$components : array<string|int, ComponentObject>

Components to add.

Tags
since
10.42.0
throws
InvalidArgumentException

Component is not a valid type.

OverflowException

Builder exceeds component limits.

Return values
self

addEmbed()

Adds an embed to the builder.

public addEmbed(Embed|array<string|int, mixed> ...$embeds) : self
Parameters
$embeds : Embed|array<string|int, mixed>
Tags
throws
OverflowException

Builder exceeds 10 embeds.

Return values
self

addFile()

Adds a file attachment to the builder.

public addFile(string $filepath[, string|null $filename = null ]) : self

Note this is a synchronous function which uses file_get_contents and therefore should not be used when requesting files from an online resource. Fetch the content asynchronously and use the addFileFromContent function for tasks like these.

Parameters
$filepath : string

Path to the file to send.

$filename : string|null = null

Name to send the file as. null for the base name of $filepath.

Return values
self

addFileFromContent()

Adds a file attachment to the builder with a given filename and content.

public addFileFromContent(string $filename, string $content) : self
Parameters
$filename : string

Name to send the file as.

$content : string

Content of the file.

Return values
self

addSticker()

Adds a sticker to the builder. Only used for sending message or creating forum thread.

public addSticker(Sticker|string $sticker) : self
Parameters
$sticker : Sticker|string

Sticker to add.

Tags
throws
OverflowException

Builder exceeds 3 stickers.

Return values
self

clearAttachments()

Removes all attachments from the message.

public clearAttachments() : self
Return values
self

clearFiles()

Removes all files from the builder.

public clearFiles() : self
Return values
self

countTotalComponents()

Recursively counts the total number of components, including nested components, in the given array.

public countTotalComponents([array<string|int, mixed>|null $components = null ]) : int
Parameters
$components : array<string|int, mixed>|null = null
Return values
int

fromPart()

Creates a new instance of the builder from a given Part.

public static fromPart(Part $part) : self
Parameters
$part : Part
Return values
self

getAllowedMentions()

public getAllowedMentions() : array<string|int, mixed>|null
Return values
array<string|int, mixed>|null

getAttachments()

Returns all the attachments in the builder.

public getAttachments() : array<string|int, array<string|int, mixed>>

The array consists of only the raw attributes of the attachments if they were added as Attachment objects.

Return values
array<string|int, array<string|int, mixed>>

getAvatarUrl()

Retrieves the avatar URL associated with the webhook. Only used for executing webhook.

public getAvatarUrl() : string|null
Return values
string|null

getContent()

Retrieves the content of the message.

public getContent() : string|null
Return values
string|null

getEmbeds()

Returns all the embeds in the builder.

public getEmbeds() : array<string|int, array<string|int, mixed>>|null
Return values
array<string|int, array<string|int, mixed>>|null

getEnforceNonce()

Retrieves the value indicating whether the nonce should be enforced.

public getEnforceNonce() : bool|null
Return values
bool|null

getFiles()

Retrieves the files attached to the message builder.

public getFiles() : array<string|int, array<string|int, mixed>>
Return values
array<string|int, array<string|int, mixed>>

getFlags()

Get the current flags of the message.

public getFlags() : int
Return values
int

getForward()

Retrieves the forwarded message associated with this builder, if any.

public getForward() : Message|null
Return values
Message|null

getNonce()

Retrieves the nonce value associated with the message.

public getNonce() : int|string|null
Return values
int|string|null

getPayloadJson()

JSON-encoded body of non-file params, only for multipart/form-data requests.

public getPayloadJson() : string
Tags
throws
RuntimeException

If encoding the message to JSON fails.

since
10.50.0
Return values
string

getReplyTo()

Retrieves the message that this builder is set to reply to, if any.

public getReplyTo() : Message|null
Return values
Message|null

getStickers()

Returns all the sticker ids in the builder.

public getStickers() : array<string|int, string>
Return values
array<string|int, string>

getTts()

Returns the value of TTS of the builder.

public getTts() : bool
Return values
bool

getUsername()

Retrieves the username associated with the message, if set.

public getUsername() : string|null
Return values
string|null

jsonSerialize()

public jsonSerialize() : array<string|int, mixed>
Tags
inheritDoc
Return values
array<string|int, mixed>

new()

Creates a new message builder.

public static new() : static
Return values
static

numFiles()

Returns the number of files attached to the builder.

public numFiles() : int
Return values
int

removeSticker()

Removes a sticker from the builder.

public removeSticker(Sticker|string $sticker) : self
Parameters
$sticker : Sticker|string

Sticker to remove.

Return values
self

requiresMultipart()

Returns a boolean that determines whether the message needs to be sent via multipart request, i.e. contains files.

public requiresMultipart() : bool

V2 components are not supported for multipart requests as files are disallowed.

Return values
bool

setAttachments()

Sets the attachments of the builder. Removes the existing attachments in the process.

public setAttachments([array<string|int, mixed>|null $attachments = null ]) : self
Parameters
$attachments : array<string|int, mixed>|null = null

An array of attachments to set, or null to clear the attachments.

Return values
self

setAvatarUrl()

Override the default avatar URL of the webhook. Only used for executing webhook.

public setAvatarUrl(string $avatar_url) : self
Parameters
$avatar_url : string

New webhook avatar URL.

Return values
self

setComponents()

Sets the components of the builder.

public setComponents([array<string|int, ComponentObject>|null $components = null ]) : self
Parameters
$components : array<string|int, ComponentObject>|null = null

Components to set.

Tags
since
10.42.0
throws
InvalidArgumentException

Component is not a valid type.

OverflowException

Builder exceeds component limits.

Return values
self

setContent()

Sets the content of the message.

public setContent(string $content) : self
Parameters
$content : string

Content of the message. Maximum 2000 characters.

Tags
throws
LengthException
Return values
self

setEmbeds()

Sets the embeds for the message. Clears the existing embeds in the process.

public setEmbeds(array<string|int, Embed>|array<string|int, mixed> $embeds) : self
Parameters
$embeds : array<string|int, Embed>|array<string|int, mixed>
Return values
self

setEnforceNonce()

If true and nonce is present, it will be checked for uniqueness in the past few minutes.

public setEnforceNonce([bool $enforce_nonce = true ]) : self

If another message was created by the same author with the same nonce, that message will be returned and no new message will be created.

Parameters
$enforce_nonce : bool = true
Return values
self

setFiles()

Sets the files to be attached to the message.

public setFiles([array<string|int, mixed>|null $files = null ]) : self
Parameters
$files : array<string|int, mixed>|null = null

An array of files to attach.

Return values
self

setFlags()

Sets the flags of the message.

public setFlags(int $flags) : self

Only SUPPRESS_EMBEDS, SUPPRESS_NOTIFICATIONS, IS_VOICE_MESSAGE, and IS_COMPONENTS_V2 can be set for the Create Message endpoint.

Parameters
$flags : int
Tags
since
10.0.0
Return values
self

setForward()

Sets this message as a forward of another message. Only used for sending message.

public setForward([Message|null $message = null ][, bool|null|null $fail_if_not_exists = null ]) : self
Parameters
$message : Message|null = null
$fail_if_not_exists : bool|null|null = null

Whether to error if the referenced message doesn't exist (default true).

Tags
since
10.50.0

Added fail_if_not_exists parameter

Return values
self

setIsComponentsV2Flag()

Sets or unsets the IS_COMPONENTS_V2 flag for the message.

public setIsComponentsV2Flag([bool $enable = true ]) : self

Once a message has been sent with this flag, it can't be removed from that message.

When the IS_COMPONENTS_V2 flag is set, any of the used content, embeds, sticker_ids, or poll fields must have their values reset to empty. For content and poll this is null. For embeds and sticker_ids this is []. Failing to do this will result in a 400 BAD REQUEST response.

Parameters
$enable : bool = true
Tags
since
10.19.0
Return values
self

setIsVoiceMessageFlag()

Sets or unsets the IS_VOICE_MESSAGE flag for the message.

public setIsVoiceMessageFlag([bool $enable = true ]) : self
Parameters
$enable : bool = true
Tags
since
10.19.0
Return values
self

setMessageReference()

Include to make your message a reply or a forward.

public setMessageReference([MessageReference|Message|null $message_reference = null ][, int $type = MessageReference::TYPE_DEFAULT ][, bool|null|null $fail_if_not_exists = null ]) : self
Parameters
$message_reference : MessageReference|Message|null = null
$type : int = MessageReference::TYPE_DEFAULT

If passing a Message, the type of message reference (0 = DEFAULT/REPLY, 1 = FORWARD).

$fail_if_not_exists : bool|null|null = null

Whether to error if the referenced message doesn't exist (default true).

Tags
throws
InvalidArgumentException

If the message reference is a forward and the channel_id is null, or the bot cannot view the referenced channel.

since
10.50.0
Return values
self

setNonce()

Sets the nonce of the message. Only used for sending message.

public setNonce([int|string|null $nonce = null ]) : self
Parameters
$nonce : int|string|null = null

Nonce of the message.

Tags
throws
LengthException

$nonce string exceeds 25 characters.

Return values
self

setReplyTo()

Sets this message as a reply to another message. Only used for sending message.

public setReplyTo([Message|null $message = null ][, bool|null|null $fail_if_not_exists = null ]) : self
Parameters
$message : Message|null = null
$fail_if_not_exists : bool|null|null = null

Whether to error if the referenced message doesn't exist (default true).

Tags
since
10.50.0

Added fail_if_not_exists parameter

Return values
self

setSharedClientTheme()

Sets the shared client theme of the message.

public setSharedClientTheme([SharedClientTheme|null $shared_client_theme = null ]) : self
Parameters
$shared_client_theme : SharedClientTheme|null = null
Tags
since
10.49.0
Return values
self

setStickers()

Sets the stickers of the builder. Removes the existing stickers in the process.

public setStickers([array<string|int, Sticker>|array<string|int, string>|null $stickers = null ]) : self
Parameters
$stickers : array<string|int, Sticker>|array<string|int, string>|null = null

New sticker ids.

Return values
self

setSuppressEmbedsFlag()

Sets or unsets the SUPPRESS_EMBEDS flag for the message.

public setSuppressEmbedsFlag([bool $enable = true ]) : self
Parameters
$enable : bool = true
Tags
since
10.19.0
Return values
self

setSuppressNotificationsFlag()

Sets or unsets the SUPPRESS_NOTIFICATIONS flag for the message.

public setSuppressNotificationsFlag([bool $enable = true ]) : self
Parameters
$enable : bool = true
Tags
since
10.19.0
Return values
self

setTts()

Sets the TTS status of the message. Only used for sending message or executing webhook.

public setTts([bool|null $tts = null ]) : self
Parameters
$tts : bool|null = null
Return values
self

setUsername()

Override the default username of the webhook. Only used for executing webhook.

public setUsername(string $username) : self
Parameters
$username : string

New webhook username.

Tags
throws
LengthException

$username exceeds 80 characters.

Return values
self

setV2Flag()

Sets or unsets the IS_COMPONENTS_V2 flag for the message.

public setV2Flag([bool $enable = true ]) : self

use MessageBuilder::setIsComponentsV2Flag() instead.

Once a message has been sent with this flag, it can't be removed from that message.

When the IS_COMPONENTS_V2 flag is set, any of the used content, embeds, sticker_ids, poll, or shared_client_theme fields must have their values reset to empty. For content, poll, and shared_client_theme, this is null. For embeds and sticker_ids this is []. Failing to do this will result in a 400 BAD REQUEST response.

Parameters
$enable : bool = true
Return values
self

checkForGetMutator()

Checks if there is a get mutator present.

protected checkForGetMutator(string $key) : string|false
Parameters
$key : string

The property name to check.

Return values
string|false —

Either a string if it is a method or false.

checkForSetMutator()

Checks if there is a set mutator present.

protected checkForSetMutator(string $key) : string|false
Parameters
$key : string

The property name to check.

Return values
string|false —

Either a string if it is a method or false.

enforceV1Limits()

Enforces the component limits and structure for v1 messages.

protected enforceV1Limits(ComponentObject $component) : void
Parameters
$component : ComponentObject
Tags
throws
OverflowException

If more than 5 components are added.

InvalidArgumentException

If a component is not an ActionRow or is not properly wrapped.

enforceV2Limits()

Validates the total number of components added to the message.

protected enforceV2Limits() : void
Tags
throws
OverflowException

If the total number of components is 40 or more.

getProperty()

Gets a property on the parent part.

protected getProperty(string $key) : mixed
Parameters
$key : string

The name of the property.

Tags
throws
Exception
Return values
mixed —

Either the property if it exists or void.

setProperty()

Sets an property on the parent part.

protected setProperty(string $key, mixed $value) : void
Parameters
$key : string

The name of the property.

$value : mixed

The value of the property.

studly()

Converts a string to studlyCase.

private static studly(string $string) : string

This is a port of updated Laravel's implementation, a non-regex with static cache. This method is private static as we may move it outside this class in future.

Parameters
$string : string

The string to convert.

Tags
since
10.0.0
Return values
string
On this page

Search results