Content: Typed Message Part for Text, Images, and Files

Content is an immutable value object that represents a single typed part within a Message. Each message body is an array of Content parts. A part has a type — one of text, image, audio, or file — and a payload whose shape depends on how the source was resolved. The static factory methods inspect the $source argument and automatically determine the correct ContentSource variant, making it straightforward to pass URLs, file paths, base64 strings, or raw binary data.

Constants

Constant	Value
`Content::TYPE_TEXT`	`'text'`
`Content::TYPE_IMAGE`	`'image'`
`Content::TYPE_AUDIO`	`'audio'`
`Content::TYPE_FILE`	`'file'`

Factory methods

`text()`

Create a plain text content part.

public static function text(string $text): self

text

string

required

The raw text string. Stored as a ContentSource::Text part with source = 'text'.

$part = Content::text('Describe the following document in three bullet points.');

`image()`

Create an image content part. The $source argument is inspected to determine how the image data is provided — see Source resolution logic below.

public static function image(
    string|Stringable $source,
    ?string $mimeType = null,
    ?string $filename = null,
    ?InputEncoding $encoding = null,
): self

source

string | Stringable

required

The image data source. Interpreted as a URL, data URI, base64 string, file path, or raw bytes — see the resolution rules below.

mimeType

string | null

default:"null"

MIME type such as 'image/png' or 'image/jpeg'. Required for base64 sources and for raw string sources that are not readable file paths.

filename

string | null

default:"null"

Optional filename hint forwarded to the provider. Auto-detected from URLs and file paths when not provided.

encoding

InputEncoding | null

default:"null"

Pass InputEncoding::Base64 to indicate that $source is a base64-encoded string. Requires $mimeType.

// From URL
$part = Content::image('https://example.com/photo.jpg');

// From local file (MIME type auto-detected)
$part = Content::image('/var/app/uploads/diagram.png');

// From base64 string
$part = Content::image($base64String, 'image/webp', null, InputEncoding::Base64);

`audio()`

Create an audio content part. Source resolution follows the same rules as image().

public static function audio(
    string|Stringable $source,
    ?string $mimeType = null,
    ?string $filename = null,
    ?InputEncoding $encoding = null,
): self

source

string | Stringable

required

The audio data source.

mimeType

string | null

default:"null"

MIME type, e.g. 'audio/mpeg' or 'audio/wav'. Required for base64 and raw string sources.

filename

string | null

default:"null"

Optional filename hint.

encoding

InputEncoding | null

default:"null"

InputEncoding::Base64 when $source is a base64 string.

// From URL
$part = Content::audio('https://example.com/recording.mp3');

// From a local file
$part = Content::audio('/var/recordings/interview.wav');

// From base64
$part = Content::audio($base64Audio, 'audio/mpeg', 'clip.mp3', InputEncoding::Base64);

`file()`

Create a file content part for PDFs, documents, or other binary files. Source resolution follows the same rules as image().

public static function file(
    string|Stringable $source,
    ?string $mimeType = null,
    ?string $filename = null,
    ?InputEncoding $encoding = null,
): self

source

string | Stringable

required

The file data source.

mimeType

string | null

default:"null"

MIME type, e.g. 'application/pdf'. Required for base64 and raw string sources.

filename

string | null

default:"null"

Optional filename hint.

encoding

InputEncoding | null

default:"null"

InputEncoding::Base64 when $source is a base64 string.

// From a local PDF (MIME auto-detected)
$part = Content::file('/var/docs/report.pdf');

// From base64-encoded PDF
$part = Content::file($base64Pdf, 'application/pdf', 'Q4-Report.pdf', InputEncoding::Base64);

Source resolution logic

The image(), audio(), and file() factories all delegate to the same internal resolver. The rules are applied in order:

Condition	Resulting `ContentSource`	Notes
`$source` starts with `http://` or `https://` and is a valid URL	`ContentSource::Url`	`filename` is inferred from the URL path when not provided.
`$source` starts with `data:`	`ContentSource::DataUri`	The MIME type is parsed from the data URI prefix; `$mimeType` overrides it.
`$encoding === InputEncoding::Base64`	`ContentSource::Base64`	`$mimeType` is required — throws `InvalidArgumentException` when absent.
`$source` is a readable file path (`is_file` + `is_readable`)	`ContentSource::Raw`	File bytes are read immediately; MIME type is auto-detected via `mime_content_type()` when not provided.
Any other string and `$mimeType` is provided	`ContentSource::Raw`	Raw string bytes stored directly.
Any other string without `$mimeType`	—	Throws `InvalidArgumentException`.

Accessor methods

`textValue()`

Return the text string for TYPE_TEXT parts, or null for all other types.

public function textValue(): ?string

return

string | null

The text content, or null if this is not a text part.

$part = Content::text('Hello');
echo $part->textValue(); // "Hello"

$img = Content::image('https://example.com/img.png');
var_dump($img->textValue()); // NULL

`data()`

Return the raw data payload for non-URL parts.

public function data(): ?string

return

string | null

The raw bytes (for Raw), the base64 string (for Base64), or the full data URI string (for DataUri). null for Url and Text sources.

$part = Content::image('/var/img/logo.png');
$bytes = $part->data(); // raw file bytes

`mimeType()`

Return the MIME type of the content, if known.

public function mimeType(): ?string

return

string | null

A MIME type string such as 'image/png' or 'audio/mpeg', or null if not set or not applicable.

$part = Content::image('/var/img/logo.png');
echo $part->mimeType(); // e.g. "image/png"

`url()`

Return the URL for ContentSource::Url parts.

public function url(): ?string

return

string | null

The full HTTP/HTTPS URL string, or null for non-URL parts.

$part = Content::image('https://cdn.example.com/hero.jpg');
echo $part->url(); // "https://cdn.example.com/hero.jpg"

`filename()`

Return the filename hint associated with this content part.

public function filename(): ?string

return

string | null

The filename string, or null if none was provided or inferred.

$part = Content::file('/docs/report.pdf');
echo $part->filename(); // "report.pdf"

`source()`

Return the ContentSource enum case describing how the data is stored in this part.

public function source(): ContentSource

return

ContentSource

One of ContentSource::Text, ContentSource::Url, ContentSource::DataUri, ContentSource::Base64, or ContentSource::Raw.

$part = Content::image('https://example.com/img.png');
echo $part->source()->value; // "url"

`base64Data()`

Return a base64-encoded representation of the content data, regardless of the original source type.

public function base64Data(): ?string

return

string | null

For ContentSource::Base64: returns the stored base64 string directly.
For ContentSource::DataUri: extracts the base64 payload from the data URI.
For ContentSource::Raw: base64-encodes the raw bytes.
null for Url and Text sources.

$part = Content::image('/var/img/logo.png');
$b64 = $part->base64Data(); // base64-encoded PNG bytes

`dataUri()`

Return a complete data: URI string, constructing one from base64 data and MIME type if the source is not already a data URI.

public function dataUri(): ?string

return

string | null

A data:{mimeType};base64,{data} string, or null if the base64 data or MIME type is unavailable.

$part = Content::image('/var/img/logo.png');
echo $part->dataUri(); // "data:image/png;base64,iVBORw0KGgo..."

ContentSource enum

ContentSource is a string-backed enum describing how content data is stored internally.

enum ContentSource: string
{
    case Text    = 'text';
    case Url     = 'url';
    case DataUri = 'data_uri';
    case Base64  = 'base64';
    case Raw     = 'raw';
}

Text

'text'

Used exclusively by Content::text(). The data is a plain UTF-8 string.

Url

'url'

The source is an HTTP/HTTPS URL. The provider fetches the resource directly.

DataUri

'data_uri'

The source is a data:... URI. The full URI is stored in data().

Base64

'base64'

The source is a raw base64 string. Requires a MIME type.

Raw

'raw'

The source is raw bytes (read from a file or passed directly as a string with a MIME type).

InputEncoding enum

InputEncoding declares supported binary-to-text encodings for binary content passed as a string.

enum InputEncoding: string
{
    case Base64 = 'base64';
}

Base64

'base64'

Indicates that the $source string passed to image(), audio(), or file() is base64-encoded binary data. A MIME type must be provided alongside it.

Examples by source type

URL source

$message = Message::user([
    Content::text('What objects appear in this photo?'),
    Content::image('https://upload.wikimedia.org/wikipedia/commons/thumb/4/47/PNG_transparency_demonstration_1.png/240px-PNG_transparency_demonstration_1.png'),
]);

Local file source (MIME auto-detected)

$message = Message::user([
    Content::text('Please summarise this document.'),
    Content::file('/var/documents/quarterly-report.pdf'),
]);

Data URI source

$dataUri = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA...';

$message = Message::user([
    Content::text('Describe this image.'),
    Content::image($dataUri),
]);

Base64 source

$base64 = base64_encode(file_get_contents('/var/audio/clip.mp3'));

$message = Message::user([
    Content::text('Transcribe this audio clip.'),
    Content::audio($base64, 'audio/mpeg', 'clip.mp3', InputEncoding::Base64),
]);

Raw bytes with explicit MIME type

$rawBytes = file_get_contents('/var/img/screenshot.png');

$message = Message::user([
    Content::text('What does this screenshot show?'),
    Content::image($rawBytes, 'image/png', 'screenshot.png'),
]);

Core Classes

Results & Responses

Contracts & Enums

Content: Typed Message Part for Text, Images, and Files

Constants

Factory methods

`text()`

`image()`

`audio()`

`file()`

Source resolution logic

Accessor methods

`textValue()`

`data()`

`mimeType()`

`url()`

`filename()`

`source()`

`base64Data()`

`dataUri()`

ContentSource enum

InputEncoding enum

Examples by source type

URL source

Local file source (MIME auto-detected)

Data URI source

Base64 source

Raw bytes with explicit MIME type

Build docs developers (and LLMs) love

Core Classes

Results & Responses

Contracts & Enums

Documentation Index

​Constants

​Factory methods

​text()

​image()

​audio()

​file()

​Source resolution logic

​Accessor methods

​textValue()

​data()

​mimeType()

​url()

​filename()

​source()

​base64Data()

​dataUri()

​ContentSource enum

​InputEncoding enum

​Examples by source type

​URL source

​Local file source (MIME auto-detected)

​Data URI source

​Base64 source

​Raw bytes with explicit MIME type

Build docs developers (and LLMs) love

Constants

Factory methods

`text()`

`image()`

`audio()`

`file()`

Source resolution logic

Accessor methods

`textValue()`

`data()`

`mimeType()`

`url()`

`filename()`

`source()`

`base64Data()`

`dataUri()`

ContentSource enum

InputEncoding enum

Examples by source type

URL source

Local file source (MIME auto-detected)

Data URI source

Base64 source

Raw bytes with explicit MIME type