DiscordPHP Documentation

MessageBuilder
in package
implements JsonSerializable

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, Attachment>|null
Attachments to send with this message.
$avatar_url  : string|null
Override the default avatar of the webhook.
$components  : array<string|int, ComponentObject>|null
Components to send with this message.
$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>>|null
Files to send with this message.
$flags  : int|null
Flags to send with this message.
$forward  : Message|null
Message to forward with this message.
$nonce  : int|string|null
A nonce that can be used for message roundtrips with the gateway (up to 25 characters).
$poll  : Poll|null
The poll for the message.
$replyTo  : Message|null
Message to reply to with this message.
$sticker_ids  : array<string|int, string>
IDs of up to 3 stickers in the server to send in the message.
$tts  : bool
Whether the message is text-to-speech.
$username  : string|null
Override the default username of the webhook.

Methods

_setFlags()  : self
addAttachment()  : $this
Adds attachment(s) to the builder.
addComponent()  : $this
Adds a component to the builder.
addEmbed()  : $this
Adds an embed to the builder.
addFile()  : $this
Adds a file attachment to the builder.
addFileFromContent()  : $this
Adds a file attachment to the builder with a given filename and content.
addSticker()  : $this
Adds a sticker to the builder. Only used for sending message or creating forum thread.
clearAttachments()  : $this
Removes all attachments from the message.
clearFiles()  : $this
Removes all files from the builder.
countTotalComponents()  : int
Recursively counts the total number of components, including nested components, in the given array.
getAllowedMentions()  : array<string|int, mixed>|null
getAttachments()  : array<string|int, Attachment>
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.
getNonce()  : int|string|null
Retrieves the nonce value associated with the message.
getPoll()  : Poll|null
Returns the poll of the message.
getReplyTo()  : Message|null
Retrieves the message that this builder is set to reply to, if any.
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>
{@inheritDoc}
new()  : static
Creates a new message builder.
numFiles()  : int
Returns the number of files attached to the builder.
removeComponent()  : $this
Removes a component from the builder.
removeSticker()  : $this
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()  : $this
Sets the allowed mentions object of the message.
setAvatarUrl()  : $this
Override the default avatar URL of the webhook. Only used for executing webhook.
setComponents()  : $this
Sets the components of the message. Removes the existing components in the process.
setContent()  : $this
Sets the content of the message.
setEmbeds()  : $this
Sets the embeds for the message. Clears the existing embeds in the process.
setEnforceNonce()  : $this
If true and nonce is present, it will be checked for uniqueness in the past few minutes.
setFiles()  : $this
Sets the files to be attached to the message.
setFlags()  : $this
Sets the flags of the message.
setForward()  : $this
Sets this message as a forward of another message. Only used for sending message.
setNonce()  : $this
Sets the nonce of the message. Only used for sending message.
setPoll()  : $this
Sets the poll of the message.
setReplyTo()  : $this
Sets this message as a reply to another message. Only used for sending message.
setStickers()  : $this
Sets the stickers of the builder. Removes the existing stickers in the process.
setTts()  : $this
Sets the TTS status of the message. Only used for sending message or executing webhook.
setUsername()  : $this
Override the default username of the webhook. Only used for executing webhook.
setV2Flag()  : self
Sets or unsets the V2 components flag for the message.
enforceV1Limits()  : void
Enforces the component limits and structure for v2 messages.
enforceV2Limits()  : void
Validates the total number of components added to the message.

Properties

$avatar_url

Override the default avatar of the webhook.

private string|null $avatar_url

$embeds

Array of embeds to send with the message.

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

$enforce_nonce

Whether to enforce the nonce.

private bool|null $enforce_nonce

$files

Files to send with this message.

private array<string|int, array<string|int, mixed>>|null $files

$flags

Flags to send with this message.

private int|null $flags

$nonce

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

private int|string|null $nonce

$sticker_ids

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

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

$tts

Whether the message is text-to-speech.

private bool $tts = false

$username

Override the default username of the webhook.

private string|null $username

Methods

_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) : $this
Parameters
$attachments : Attachment|string|int

Attachment objects or IDs to add

Return values
$this

addComponent()

Adds a component to the builder.

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

Component to add.

Tags
throws
InvalidArgumentException

Component is not a valid type.

throws
OverflowException

Builder exceeds component limits.

Return values
$this

addEmbed()

Adds an embed to the builder.

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

Builder exceeds 10 embeds.

Return values
$this

addFile()

Adds a file attachment to the builder.

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

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
$this

addFileFromContent()

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

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

Name to send the file as.

$content : string

Content of the file.

Return values
$this

addSticker()

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

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

Sticker to add.

Tags
throws
OverflowException

Builder exceeds 3 stickers.

Return values
$this

clearAttachments()

Removes all attachments from the message.

public clearAttachments() : $this
Return values
$this

clearFiles()

Removes all files from the builder.

public clearFiles() : $this
Return values
$this

countTotalComponents()

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

public countTotalComponents() : int
Return values
int

getAllowedMentions()

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

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

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()

{@inheritDoc}

public jsonSerialize() : array<string|int, mixed>
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(string|Sticker $sticker) : $this
Parameters
$sticker : string|Sticker

Sticker to remove.

Return values
$this

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

setAvatarUrl()

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

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

New webhook avatar URL.

Return values
$this

setComponents()

Sets the components of the message. Removes the existing components in the process.

public setComponents(array<string|int, mixed> $components) : $this
Parameters
$components : array<string|int, mixed>

New message components.

Return values
$this

setContent()

Sets the content of the message.

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

Content of the message. Maximum 2000 characters.

Tags
throws
LengthException
Return values
$this

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) : $this
Parameters
$embeds : array<string|int, Embed>|array<string|int, mixed>
Return values
$this

setEnforceNonce()

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

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

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
$this

setFiles()

Sets the files to be attached to the message.

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

An array of files to attach.

Return values
$this

setFlags()

Sets the flags of the message.

public setFlags(int $flags) : $this

Only works for some message types and some message flags.

Parameters
$flags : int
Tags
since
10.0.0
Return values
$this

setForward()

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

public setForward([Message|null $message = null ]) : $this
Parameters
$message : Message|null = null
Return values
$this

setNonce()

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

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

Nonce of the message.

Tags
throws
LengthException

$nonce string exceeds 25 characters.

Return values
$this

setPoll()

Sets the poll of the message.

public setPoll(Poll|null $poll) : $this
Parameters
$poll : Poll|null
Return values
$this

setReplyTo()

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

public setReplyTo([Message|null $message = null ]) : $this
Parameters
$message : Message|null = null
Return values
$this

setStickers()

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

public setStickers(array<string|int, mixed> $stickers) : $this
Parameters
$stickers : array<string|int, mixed>

New sticker ids.

Return values
$this

setTts()

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

public setTts([bool $tts = false ]) : $this
Parameters
$tts : bool = false
Return values
$this

setUsername()

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

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

New webhook username.

Tags
throws
LengthException

$username exceeds 80 characters.

Return values
$this

setV2Flag()

Sets or unsets the V2 components flag for the message.

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

enforceV1Limits()

Enforces the component limits and structure for v2 messages.

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

If more than 5 components are added.

throws
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.


        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results