Documentation

Message extends Message
in package
uses CharsetAwareTrait

Message class

Tags
category

Pop

author

Nick Sagona, III nick@popphp.org

copyright

Copyright (c) 2009-2026 Nick Sagona, III

license

https://www.popphp.org/license New BSD License

version
5.0.0

Table of Contents

Constants

CRLF  = "\r\n"
Message newline constant

Properties

$addresses  : array<string|int, mixed>
Message addresses
$body  : Body|null
Body
$boundary  : string|null
Boundary
$charSet  : string|null
Character set
$headers  : array<string|int, mixed>
Headers
$parts  : array<string|int, mixed>
Nested parts
$subType  : string|null
Subtype

Methods

__clone()  : void
Perform a "deep" clone of a message object
__construct()  : mixed
Constructor
__toString()  : string
Render the part
addFile()  : Part
Add file as body
addHeader()  : Part
Add a header
addHeaders()  : Part
Add headers
addHtml()  : Message
Add HTML message part
addPart()  : Message
Add message part
addParts()  : Part
Add nested parts
addText()  : Message
Add text message part
attachFile()  : Message
Attach file message part
attachFileFromStream()  : Message
Attach file message part from stream
attachment()  : static
Create an attachment part from a file on disk
attachmentFromContent()  : static
Create an attachment part from in-memory content
createForm()  : Message
Create multipart form object
decodeText()  : string
Decode text
generateBoundary()  : string
Generate boundary
generateId()  : string
Generate a Message-ID and set it as a side effect
getAttachments()  : array<string|int, mixed>
Get attachments
getBcc()  : array<string|int, mixed>
Get BCC
getBody()  : Body|null
Get body
getBodyContent()  : string|null
Get the rendered body content
getBoundary()  : string
Get message MIME boundary (auto-generating and setting MIME-Version if needed)
getCc()  : array<string|int, mixed>
Get CC
getCharSet()  : string|null
Get character set
getContents()  : mixed
Get contents (decoded)
getContentType()  : string|null
Get content-type
getFilename()  : string|null
Get attachment filename
getFrom()  : array<string|int, mixed>
Get From
getHeader()  : Header|null
Get headers
getHeaderAsString()  : string|null
Get a single header rendered as a full "Name: Value" string
getHeaders()  : array<string|int, mixed>
Get headers (flat name => string map)
getHeadersAsArray()  : array<string|int, mixed>
Get headers as array
getHeadersAsString()  : string
Get all headers rendered as a string, one per line
getHeaderValue()  : string|null
Get header value as a string
getPart()  : Part|null
Get message part
getParts()  : array<string|int, mixed>
Get message parts
getReplyTo()  : array<string|int, mixed>
Get Reply-To
getReturnPath()  : array<string|int, mixed>
Get Return-Path
getSender()  : array<string|int, mixed>
Get Sender
getSubject()  : string|null
Get subject
getSubType()  : string|null
Get subtype
getTo()  : array<string|int, mixed>
Get To
hasAttachment()  : bool
Has attachment (check via a header)
hasAttachments()  : bool
Does message have attachments (check via parts)
hasBcc()  : bool
Has BCC
hasBody()  : bool
Has body
hasBoundary()  : bool
Has boundary
hasCc()  : bool
Has CC
hasFrom()  : bool
Has From
hasHeader()  : bool
Has header
hasHeaders()  : bool
Has headers
hasParts()  : bool
Has nested parts
hasReplyTo()  : bool
Has Reply-To
hasReturnPath()  : bool
Has Return-Path
hasSender()  : bool
Has Sender
hasSubType()  : bool
Has subtype
hasTo()  : bool
Has To
html()  : static
Create a text/html part
inferSubType()  : Part
Infer and set the subtype (alternative/mixed) from the current nested parts
load()  : Message
Load a message from a string source or file on disk
parse()  : Message
Parse message from string
parseBody()  : array<string|int, mixed>
Parse message body string
parseForm()  : array<string|int, mixed>
Parse form data
parseFromFile()  : Message
Parse message from file
parseHeaders()  : array<string|int, mixed>
Parse message header string
parseMessage()  : Message
Parse message
parsePart()  : Part|array<string|int, mixed>
Parse message part string
removeHeader()  : Message
Remove header
render()  : string
Render the message
renderAsLines()  : array<string|int, mixed>
Render as an array of lines
renderBody()  : string
Render the part body
renderHeaders()  : string
Render the part headers
renderParts()  : string
Render the parts
renderRaw()  : string
Render the part raw (no headers or preamble)
save()  : void
Save message to file on disk
setBcc()  : Message
Set BCC
setBody()  : Message
Set body
setBoundary()  : Part
Set boundary
setCc()  : Message
Set CC
setCharSet()  : static
Set character set
setContentId()  : Part
Set the Content-ID header
setContentType()  : static
Set Content-Type header
setFrom()  : Message
Set From
setMessageId()  : Message
Set the Message-ID header
setReplyTo()  : Message
Set Reply-To
setReturnPath()  : Message
Set Return-Path
setSender()  : Message
Set Sender
setSubject()  : Message
Set Subject
setSubType()  : Part
Set subtype
setTo()  : Message
Set To
text()  : static
Create a text/plain part
toByteStream()  : void
Write this entire entity to a buffer
detectContentType()  : string
Detect a content type from a filename's extension
addressListToArray()  : array<string|int, mixed>
Convert an AddressList into an email => ?name array
arrayToAddressString()  : string
Convert an array of addresses into a comma-joined address string

Constants

CRLF

Message newline constant

public string CRLF = "\r\n"

Properties

$addresses

Message addresses

protected array<string|int, mixed> $addresses = ['To' => [], 'CC' => [], 'BCC' => [], 'From' => [], 'Reply-To' => [], 'Sender' => [], 'Return-Path' => []]

$boundary

Boundary

protected string|null $boundary = null

$headers

Headers

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

$parts

Nested parts

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

$subType

Subtype

protected string|null $subType = null

Methods

__clone()

Perform a "deep" clone of a message object

public __clone() : void

__construct()

Constructor

public __construct([string|null $subject = null ]) : mixed

Instantiate the message object

Parameters
$subject : string|null = null

__toString()

Render the part

public __toString() : string
Return values
string

addFile()

Add file as body

public addFile(string $file[, string $disposition = 'attachment' ][, Encoding $encoding = PartBodyEncoding::BASE64 ][, int|bool $split = true ]) : Part
Parameters
$file : string
$disposition : string = 'attachment'
$encoding : Encoding = PartBodyEncoding::BASE64
$split : int|bool = true
Tags
throws
Exception
Return values
Part

addHeader()

Add a header

public addHeader(Header|string $header[, string|null $value = null ]) : Part
Parameters
$header : Header|string
$value : string|null = null
Return values
Part

addHeaders()

Add headers

public addHeaders(array<string|int, mixed> $headers) : Part
Parameters
$headers : array<string|int, mixed>
Return values
Part

addHtml()

Add HTML message part

public addHtml(mixed $html) : Message
Parameters
$html : mixed
Return values
Message

addPart()

Add message part

public addPart(Part $part) : Message

Auto-infers the multipart subtype (alternative/mixed) from the nested parts via Part::inferSubType(); when parts exist but no subtype could be inferred (e.g. a single text-only part), defaults to 'mixed' per the "Single-part rendering" spec resolution.

Parameters
$part : Part
Return values
Message

addParts()

Add nested parts

public addParts(array<string|int, mixed> $parts) : Part
Parameters
$parts : array<string|int, mixed>
Return values
Part

addText()

Add text message part

public addText(mixed $text) : Message
Parameters
$text : mixed
Return values
Message

attachFile()

Attach file message part

public attachFile(string $file[, Encoding $encoding = PartBodyEncoding::BASE64 ]) : Message
Parameters
$file : string
$encoding : Encoding = PartBodyEncoding::BASE64
Return values
Message

attachFileFromStream()

Attach file message part from stream

public attachFileFromStream(string $stream[, string $basename = 'file.tmp' ][, Encoding $encoding = PartBodyEncoding::BASE64 ]) : Message
Parameters
$stream : string
$basename : string = 'file.tmp'
$encoding : Encoding = PartBodyEncoding::BASE64
Return values
Message

attachment()

Create an attachment part from a file on disk

public static attachment(string $file[, string|null $contentType = null ][, string $disposition = 'attachment' ][, Encoding $encoding = PartBodyEncoding::BASE64 ][, int|bool $split = true ]) : static
Parameters
$file : string
$contentType : string|null = null
$disposition : string = 'attachment'
$encoding : Encoding = PartBodyEncoding::BASE64
$split : int|bool = true
Return values
static

attachmentFromContent()

Create an attachment part from in-memory content

public static attachmentFromContent(string $content, string $filename[, string|null $contentType = null ][, string $disposition = 'attachment' ][, Encoding $encoding = PartBodyEncoding::BASE64 ][, int|bool $split = true ]) : static
Parameters
$content : string
$filename : string
$contentType : string|null = null
$disposition : string = 'attachment'
$encoding : Encoding = PartBodyEncoding::BASE64
$split : int|bool = true
Return values
static

createForm()

Create multipart form object

public static createForm([array<string|int, mixed> $fields = [] ]) : Message
Parameters
$fields : array<string|int, mixed> = []
Return values
Message

decodeText()

Decode text

public static decodeText(string $text) : string
Parameters
$text : string
Return values
string

generateBoundary()

Generate boundary

public generateBoundary() : string
Return values
string

generateId()

Generate a Message-ID and set it as a side effect

public generateId([string|null $domain = null ]) : string

This overrides Part::generateId(?string $domain = null): string (same signature, legal). Note: MimeMessage::setMessageId() internally does $id ?? $this->generateId($domain) when no $id is given - calling setMessageId(null, $domain) from inside this override would resolve $this->generateId() polymorphically back to THIS method, recursing forever. Generating the id via parent::generateId() first and passing it explicitly avoids that.

Parameters
$domain : string|null = null
Return values
string

getAttachments()

Get attachments

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

getBcc()

Get BCC

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

getBody()

Get body

public getBody() : Body|null
Return values
Body|null

getBodyContent()

Get the rendered body content

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

getBoundary()

Get message MIME boundary (auto-generating and setting MIME-Version if needed)

public getBoundary() : string
Return values
string

getCc()

Get CC

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

getCharSet()

Get character set

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

getContents()

Get contents (decoded)

public getContents() : mixed

getContentType()

Get content-type

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

getFilename()

Get attachment filename

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

getFrom()

Get From

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

getHeader()

Get headers

public getHeader(string $name) : Header|null
Parameters
$name : string
Return values
Header|null

getHeaderAsString()

Get a single header rendered as a full "Name: Value" string

public getHeaderAsString(string $name) : string|null
Parameters
$name : string
Return values
string|null

getHeaders()

Get headers (flat name => string map)

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

getHeadersAsArray()

Get headers as array

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

getHeadersAsString()

Get all headers rendered as a string, one per line

public getHeadersAsString([array<string|int, mixed> $omitHeaders = [] ]) : string
Parameters
$omitHeaders : array<string|int, mixed> = []
Return values
string

getHeaderValue()

Get header value as a string

public getHeaderValue(string $name) : string|null

Named getHeaderValue() rather than getHeader() because Pop\Mime\Part already declares a public getHeader(string $name): ?Header. A same-named override returning ?string here is not legal (return-type covariance requires a subtype of Header|null, and string is unrelated) - PHP fatals at class-load time for every new Message(). getHeader() is therefore left un-overridden and inherited as-is (returns the raw Part\Header object, consistent with how Text/Html/Attachment already expose it); this method is the flat-string convenience accessor instead.

Parameters
$name : string
Return values
string|null

getPart()

Get message part

public getPart(int $i) : Part|null
Parameters
$i : int
Return values
Part|null

getParts()

Get message parts

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

getReplyTo()

Get Reply-To

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

getReturnPath()

Get Return-Path

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

getSender()

Get Sender

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

getSubject()

Get subject

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

getSubType()

Get subtype

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

getTo()

Get To

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

hasAttachment()

Has attachment (check via a header)

public hasAttachment() : bool
Return values
bool

hasAttachments()

Does message have attachments (check via parts)

public hasAttachments() : bool
Return values
bool

hasBcc()

Has BCC

public hasBcc() : bool
Return values
bool

hasBody()

Has body

public hasBody() : bool
Return values
bool

hasBoundary()

Has boundary

public hasBoundary() : bool
Return values
bool

hasCc()

Has CC

public hasCc() : bool
Return values
bool

hasFrom()

Has From

public hasFrom() : bool
Return values
bool

hasHeader()

Has header

public hasHeader(string $name) : bool
Parameters
$name : string
Return values
bool

hasHeaders()

Has headers

public hasHeaders() : bool
Return values
bool

hasParts()

Has nested parts

public hasParts() : bool
Return values
bool

hasReplyTo()

Has Reply-To

public hasReplyTo() : bool
Return values
bool

hasReturnPath()

Has Return-Path

public hasReturnPath() : bool
Return values
bool

hasSender()

Has Sender

public hasSender() : bool
Return values
bool

hasSubType()

Has subtype

public hasSubType() : bool
Return values
bool

hasTo()

Has To

public hasTo() : bool
Return values
bool

html()

Create a text/html part

public static html(string $content) : static
Parameters
$content : string
Return values
static

inferSubType()

Infer and set the subtype (alternative/mixed) from the current nested parts

public inferSubType() : Part
Return values
Part

load()

Load a message from a string source or file on disk

public static load(string $message) : Message
Parameters
$message : string
Tags
throws
Exception
Return values
Message

parse()

Parse message from string

public static parse(string $stream) : Message
Parameters
$stream : string
Tags
throws
Exception
Return values
Message

parseBody()

Parse message body string

public static parseBody(string $bodyString[, string|null $boundary = null ]) : array<string|int, mixed>
Parameters
$bodyString : string
$boundary : string|null = null
Return values
array<string|int, mixed>

parseForm()

Parse form data

public static parseForm(string $formString) : array<string|int, mixed>
Parameters
$formString : string
Return values
array<string|int, mixed>

parseFromFile()

Parse message from file

public static parseFromFile(string $file) : Message
Parameters
$file : string
Tags
throws
Exception
Return values
Message

parseHeaders()

Parse message header string

public static parseHeaders(string $headerString) : array<string|int, mixed>
Parameters
$headerString : string
Return values
array<string|int, mixed>

parseMessage()

Parse message

public static parseMessage(string $messageString) : Message
Parameters
$messageString : string
Return values
Message

parsePart()

Parse message part string

public static parsePart(string $partString) : Part|array<string|int, mixed>
Parameters
$partString : string
Return values
Part|array<string|int, mixed>

removeHeader()

Remove header

public removeHeader(string $header) : Message
Parameters
$header : string
Return values
Message

render()

Render the message

public render([bool $preamble = true ][, string|null $body = null ]) : string

Overrides Part::render() to explicitly call getBoundary() first (when parts are present), which is what actually generates the MIME-Version header as a side effect. Part::renderParts() (called internally by the inherited render()) reads $this->boundary/generateBoundary() directly and never routes through this class's getBoundary() override, so without this, MIME-Version was never emitted on real rendered output. Routing through getHeadersAsString() also picks up the charset-append logic that the inherited renderHeaders() doesn't have.

Body must be rendered BEFORE headers are stringified: renderParts() (invoked by getBodyContent()) is what lazily synthesizes the Content-Type: multipart/...; boundary=... header as a side effect when one isn't already present. Calling getHeadersAsString() first would stringify the header set before that side effect fires, silently dropping Content-Type from the rendered output.

$body may be passed in to reuse an already-rendered body (e.g. when only the headers differ across repeated renders of the same message, such as looping Bcc transactions) instead of re-running renderParts() (and re-encoding any attachments) on every call.

Parameters
$preamble : bool = true
$body : string|null = null
Return values
string

renderAsLines()

Render as an array of lines

public renderAsLines([string|null $body = null ]) : array<string|int, mixed>
Parameters
$body : string|null = null

pre-rendered body to reuse (see render())

Return values
array<string|int, mixed>

renderBody()

Render the part body

public renderBody() : string
Return values
string

renderHeaders()

Render the part headers

public renderHeaders() : string
Return values
string

renderParts()

Render the parts

public renderParts([bool $preamble = true ][, bool $headers = true ]) : string
Parameters
$preamble : bool = true
$headers : bool = true
Return values
string

renderRaw()

Render the part raw (no headers or preamble)

public renderRaw() : string
Return values
string

save()

Save message to file on disk

public save(string $to) : void
Parameters
$to : string

setBoundary()

Set boundary

public setBoundary(string $boundary) : Part
Parameters
$boundary : string
Return values
Part

setCharSet()

Set character set

public setCharSet([string|null $charSet = null ]) : static
Parameters
$charSet : string|null = null
Return values
static

setContentId()

Set the Content-ID header

public setContentId([string|null $id = null ][, string|null $domain = null ]) : Part
Parameters
$id : string|null = null
$domain : string|null = null
Return values
Part

setContentType()

Set Content-Type header

public setContentType(string $contentType) : static
Parameters
$contentType : string
Return values
static

setMessageId()

Set the Message-ID header

public setMessageId([string|null $id = null ][, string|null $domain = null ]) : Message
Parameters
$id : string|null = null
$domain : string|null = null
Return values
Message

setReplyTo()

Set Reply-To

public setReplyTo(mixed $replyTo) : Message
Parameters
$replyTo : mixed
Return values
Message

setReturnPath()

Set Return-Path

public setReturnPath(mixed $returnPath) : Message
Parameters
$returnPath : mixed
Return values
Message

setSender()

Set Sender

public setSender(mixed $sender) : Message
Parameters
$sender : mixed
Return values
Message

setSubject()

Set Subject

public setSubject(string $subject) : Message
Parameters
$subject : string
Return values
Message

setSubType()

Set subtype

public setSubType(string $subType) : Part
Parameters
$subType : string
Return values
Part

text()

Create a text/plain part

public static text(string $content) : static
Parameters
$content : string
Return values
static

toByteStream()

Write this entire entity to a buffer

public toByteStream(BufferInterface $is[, string|null $body = null ]) : void
Parameters
$is : BufferInterface
$body : string|null = null

pre-rendered body to reuse (see render())

detectContentType()

Detect a content type from a filename's extension

protected static detectContentType(string $filename) : string
Parameters
$filename : string
Return values
string

addressListToArray()

Convert an AddressList into an email => ?name array

private static addressListToArray(AddressList $list) : array<string|int, mixed>
Parameters
$list : AddressList
Return values
array<string|int, mixed>

arrayToAddressString()

Convert an array of addresses into a comma-joined address string

private static arrayToAddressString(array<string|int, mixed> $addresses) : string

Supports:

  • ['email@example.com' => 'Name', ...] (key is email)
  • ['Name' => 'email@example.com', ...] (value is email)
  • [0 => 'email@example.com', ...] (plain list)
  • [0 => stdClass{mailbox, host}, ...]
Parameters
$addresses : array<string|int, mixed>
Return values
string 

        

        
    




    

    

                                

                

                                
    

        On this page

        
    


                

                            

            

    

        

            
Search results