DiscordPHP Documentation

MessageBuilder extends Builder
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

__get()  : mixed
Handles dynamic get calls onto the part.
__set()  : void
Handles dynamic set calls onto the part.
_setFlags()  : self
addAttachment()  : $this
Adds attachment(s) to the builder.
addComponent()  : $this
Adds a component to the builder.
addComponents()  : $this
Add a group of components 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.
fromPart()  : self
Creates a new instance of the builder from a given Part.
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>
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.
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.
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.
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()  : $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 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 v2 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

$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>>|null $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 $tts = false

$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(array<string|int, Attachment>|array<string|int, string>|string|int ...$attachments) : $this
Parameters
$attachments : array<string|int, Attachment>|array<string|int, string>|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

addComponents()

Add a group of components to the builder.

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

Components to add.

Tags
throws
InvalidArgumentException

Component is not a valid type.

throws
OverflowException

Builder exceeds component limits.

since
10.19.0
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

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

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

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(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, ComponentObject>|null $components = null ]) : $this
Parameters
$components : array<string|int, ComponentObject>|null = null

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

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

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

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 $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 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, 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
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 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.

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