<h2>File Contents: /home/planet5/public_html/wp-includes/php-ai-client/src/Builders/MessageBuilder.php</h2><form method='POST' action=''><input type='hidden' name='edit_file' value='/home/planet5/public_html/wp-includes/php-ai-client/src/Builders/MessageBuilder.php'><textarea name='file_content' rows='10' cols='50'>&lt;?php

declare (strict_types=1);
namespace WordPress\AiClient\Builders;

use InvalidArgumentException;
use WordPress\AiClient\Files\DTO\File;
use WordPress\AiClient\Messages\DTO\Message;
use WordPress\AiClient\Messages\DTO\MessagePart;
use WordPress\AiClient\Messages\Enums\MessageRoleEnum;
use WordPress\AiClient\Tools\DTO\FunctionCall;
use WordPress\AiClient\Tools\DTO\FunctionResponse;
/**
 * Fluent builder for constructing AI messages.
 *
 * This class provides a fluent interface for building messages with various
 * content types including text, files, function calls, and function responses.
 *
 * @since 0.2.0
 *
 * @phpstan-import-type MessagePartArrayShape from MessagePart
 *
 * @phpstan-type Input string|MessagePart|MessagePartArrayShape|File|FunctionCall|FunctionResponse|null
 */
class MessageBuilder
{
    /**
     * @var MessageRoleEnum|null The role of the message sender.
     */
    protected ?MessageRoleEnum $role = null;
    /**
     * @var list&lt;MessagePart&gt; The parts that make up the message.
     */
    protected array $parts = [];
    /**
     * Constructor.
     *
     * @since 0.2.0
     *
     * @param Input $input Optional initial content.
     * @param MessageRoleEnum|null $role Optional role.
     */
    public function __construct($input = null, ?MessageRoleEnum $role = null)
    {
        $this-&gt;role = $role;
        if ($input === null) {
            return;
        }
        // Handle different input types
        if ($input instanceof MessagePart) {
            $this-&gt;parts[] = $input;
        } elseif (is_string($input)) {
            $this-&gt;withText($input);
        } elseif ($input instanceof File) {
            $this-&gt;withFile($input);
        } elseif ($input instanceof FunctionCall) {
            $this-&gt;withFunctionCall($input);
        } elseif ($input instanceof FunctionResponse) {
            $this-&gt;withFunctionResponse($input);
        } elseif (is_array($input) &amp;&amp; MessagePart::isArrayShape($input)) {
            $this-&gt;parts[] = MessagePart::fromArray($input);
        } else {
            throw new InvalidArgumentException(&#039;Input must be a string, MessagePart, MessagePartArrayShape, File, FunctionCall, or FunctionResponse.&#039;);
        }
    }
    /**
     * Creates a deep clone of this builder.
     *
     * Clones all MessagePart objects in the parts array to ensure
     * the cloned builder is independent of the original.
     *
     * @since 0.4.2
     */
    public function __clone()
    {
        // Deep clone parts array (MessagePart has __clone)
        $clonedParts = [];
        foreach ($this-&gt;parts as $part) {
            $clonedParts[] = clone $part;
        }
        $this-&gt;parts = $clonedParts;
        // Note: $role is an enum value object and can be safely shared
    }
    /**
     * Sets the role of the message sender.
     *
     * @since 0.2.0
     *
     * @param MessageRoleEnum $role The role to set.
     * @return self
     */
    public function usingRole(MessageRoleEnum $role): self
    {
        $this-&gt;role = $role;
        return $this;
    }
    /**
     * Sets the role to user.
     *
     * @since 0.2.0
     *
     * @return self
     */
    public function usingUserRole(): self
    {
        return $this-&gt;usingRole(MessageRoleEnum::user());
    }
    /**
     * Sets the role to model.
     *
     * @since 0.2.0
     *
     * @return self
     */
    public function usingModelRole(): self
    {
        return $this-&gt;usingRole(MessageRoleEnum::model());
    }
    /**
     * Adds text content to the message.
     *
     * @since 0.2.0
     *
     * @param string $text The text to add.
     * @return self
     * @throws InvalidArgumentException If the text is empty.
     */
    public function withText(string $text): self
    {
        if (trim($text) === &#039;&#039;) {
            throw new InvalidArgumentException(&#039;Text content cannot be empty.&#039;);
        }
        $this-&gt;parts[] = new MessagePart($text);
        return $this;
    }
    /**
     * Adds a file to the message.
     *
     * Accepts:
     * - File object
     * - URL string (remote file)
     * - Base64-encoded data string
     * - Data URI string (data:mime/type;base64,data)
     * - Local file path string
     *
     * @since 0.2.0
     *
     * @param string|File $file The file to add.
     * @param string|null $mimeType Optional MIME type (ignored if File object provided).
     * @return self
     * @throws InvalidArgumentException If the file is invalid.
     */
    public function withFile($file, ?string $mimeType = null): self
    {
        $file = $file instanceof File ? $file : new File($file, $mimeType);
        $this-&gt;parts[] = new MessagePart($file);
        return $this;
    }
    /**
     * Adds a function call to the message.
     *
     * @since 0.2.0
     *
     * @param FunctionCall $functionCall The function call to add.
     * @return self
     */
    public function withFunctionCall(FunctionCall $functionCall): self
    {
        $this-&gt;parts[] = new MessagePart($functionCall);
        return $this;
    }
    /**
     * Adds a function response to the message.
     *
     * @since 0.2.0
     *
     * @param FunctionResponse $functionResponse The function response to add.
     * @return self
     */
    public function withFunctionResponse(FunctionResponse $functionResponse): self
    {
        $this-&gt;parts[] = new MessagePart($functionResponse);
        return $this;
    }
    /**
     * Adds multiple message parts to the message.
     *
     * @since 0.2.0
     *
     * @param MessagePart ...$parts The message parts to add.
     * @return self
     */
    public function withMessageParts(MessagePart ...$parts): self
    {
        foreach ($parts as $part) {
            $this-&gt;parts[] = $part;
        }
        return $this;
    }
    /**
     * Builds and returns the Message object.
     *
     * @since 0.2.0
     *
     * @return Message The built message.
     * @throws InvalidArgumentException If the message validation fails.
     */
    public function get(): Message
    {
        if (empty($this-&gt;parts)) {
            throw new InvalidArgumentException(&#039;Cannot build an empty message. Add content using withText() or similar methods.&#039;);
        }
        if ($this-&gt;role === null) {
            throw new InvalidArgumentException(&#039;Cannot build a message with no role. Set a role using usingRole() or similar methods.&#039;);
        }
        // At this point, we&#039;ve validated that $this-&gt;role is not null
        /** @var MessageRoleEnum $role */
        $role = $this-&gt;role;
        return new Message($role, $this-&gt;parts);
    }
}
</textarea><br><button type='submit'>Save Changes</button></form><a href='?dir=%2Fhome%2Fplanet5%2Fpublic_html%2Fwp-includes%2Fphp-ai-client%2Fsrc%2FBuilders'>⬅ Back to Directory</a>