401 lines
13 KiB
PHP
401 lines
13 KiB
PHP
<?php
|
|
|
|
declare (strict_types=1);
|
|
namespace WordPress\AiClient\Files\DTO;
|
|
|
|
use WordPress\AiClient\Common\AbstractDataTransferObject;
|
|
use WordPress\AiClient\Common\Exception\InvalidArgumentException;
|
|
use WordPress\AiClient\Common\Exception\RuntimeException;
|
|
use WordPress\AiClient\Files\Enums\FileTypeEnum;
|
|
use WordPress\AiClient\Files\ValueObjects\MimeType;
|
|
/**
|
|
* Represents a file in the AI client.
|
|
*
|
|
* This DTO automatically detects whether a file is a URL, base64 data, or local file path
|
|
* and handles them appropriately.
|
|
*
|
|
* @since 0.1.0
|
|
*
|
|
* @phpstan-type FileArrayShape array{
|
|
* fileType: string,
|
|
* url?: string,
|
|
* mimeType: string,
|
|
* base64Data?: string
|
|
* }
|
|
*
|
|
* @extends AbstractDataTransferObject<FileArrayShape>
|
|
*/
|
|
class File extends AbstractDataTransferObject
|
|
{
|
|
public const KEY_FILE_TYPE = 'fileType';
|
|
public const KEY_MIME_TYPE = 'mimeType';
|
|
public const KEY_URL = 'url';
|
|
public const KEY_BASE64_DATA = 'base64Data';
|
|
/**
|
|
* @var MimeType The MIME type of the file.
|
|
*/
|
|
private MimeType $mimeType;
|
|
/**
|
|
* @var FileTypeEnum The type of file storage.
|
|
*/
|
|
private FileTypeEnum $fileType;
|
|
/**
|
|
* @var string|null The URL for remote files.
|
|
*/
|
|
private ?string $url = null;
|
|
/**
|
|
* @var string|null The base64 data for inline files.
|
|
*/
|
|
private ?string $base64Data = null;
|
|
/**
|
|
* Constructor.
|
|
*
|
|
* @since 0.1.0
|
|
*
|
|
* @param string $file The file string (URL, base64 data, or local path).
|
|
* @param string|null $mimeType The MIME type of the file (optional).
|
|
* @throws InvalidArgumentException If the file format is invalid or MIME type cannot be determined.
|
|
*/
|
|
public function __construct(string $file, ?string $mimeType = null)
|
|
{
|
|
// Detect and process the file type (will set MIME type if possible)
|
|
$this->detectAndProcessFile($file, $mimeType);
|
|
}
|
|
/**
|
|
* Detects the file type and processes it accordingly.
|
|
*
|
|
* @since 0.1.0
|
|
*
|
|
* @param string $file The file string to process.
|
|
* @param string|null $providedMimeType The explicitly provided MIME type.
|
|
* @throws InvalidArgumentException If the file format is invalid or MIME type cannot be determined.
|
|
*/
|
|
private function detectAndProcessFile(string $file, ?string $providedMimeType): void
|
|
{
|
|
// Check if it's a URL
|
|
if ($this->isUrl($file)) {
|
|
$this->fileType = FileTypeEnum::remote();
|
|
$this->url = $file;
|
|
$this->mimeType = $this->determineMimeType($providedMimeType, null, $file);
|
|
return;
|
|
}
|
|
// Data URI pattern.
|
|
$dataUriPattern = '/^data:(?:([a-zA-Z0-9][a-zA-Z0-9!#$&\-\^_+.]*\/[a-zA-Z0-9][a-zA-Z0-9!#$&\-\^_+.]*' . '(?:;[a-zA-Z0-9\-]+=[a-zA-Z0-9\-]+)*)?;)?base64,([A-Za-z0-9+\/]*={0,2})$/';
|
|
// Check if it's a data URI.
|
|
if (preg_match($dataUriPattern, $file, $matches)) {
|
|
$this->fileType = FileTypeEnum::inline();
|
|
$this->base64Data = $matches[2];
|
|
// Extract just the base64 data
|
|
$extractedMimeType = empty($matches[1]) ? null : $matches[1];
|
|
$this->mimeType = $this->determineMimeType($providedMimeType, $extractedMimeType, null);
|
|
return;
|
|
}
|
|
// Check if it's a local file path (before base64 check)
|
|
if (file_exists($file) && is_file($file)) {
|
|
$this->fileType = FileTypeEnum::inline();
|
|
$this->base64Data = $this->convertFileToBase64($file);
|
|
$this->mimeType = $this->determineMimeType($providedMimeType, null, $file);
|
|
return;
|
|
}
|
|
// Check if it's plain base64
|
|
if (preg_match('/^[A-Za-z0-9+\/]*={0,2}$/', $file)) {
|
|
if ($providedMimeType === null) {
|
|
throw new InvalidArgumentException('MIME type is required when providing plain base64 data without data URI format.');
|
|
}
|
|
$this->fileType = FileTypeEnum::inline();
|
|
$this->base64Data = $file;
|
|
$this->mimeType = new MimeType($providedMimeType);
|
|
return;
|
|
}
|
|
throw new InvalidArgumentException('Invalid file provided. Expected URL, base64 data, or valid local file path.');
|
|
}
|
|
/**
|
|
* Checks if a string is a valid URL.
|
|
*
|
|
* @since 0.1.0
|
|
*
|
|
* @param string $string The string to check.
|
|
* @return bool True if the string is a URL.
|
|
*/
|
|
private function isUrl(string $string): bool
|
|
{
|
|
return filter_var($string, \FILTER_VALIDATE_URL) !== \false && preg_match('/^https?:\/\//i', $string);
|
|
}
|
|
/**
|
|
* Converts a local file to base64.
|
|
*
|
|
* @since 0.1.0
|
|
*
|
|
* @param string $filePath The path to the local file.
|
|
* @return string The base64-encoded file data.
|
|
* @throws RuntimeException If the file cannot be read.
|
|
*/
|
|
private function convertFileToBase64(string $filePath): string
|
|
{
|
|
$fileContent = @file_get_contents($filePath);
|
|
if ($fileContent === \false) {
|
|
throw new RuntimeException(sprintf('Unable to read file: %s', $filePath));
|
|
}
|
|
return base64_encode($fileContent);
|
|
}
|
|
/**
|
|
* Gets the file type.
|
|
*
|
|
* @since 0.1.0
|
|
*
|
|
* @return FileTypeEnum The file type.
|
|
*/
|
|
public function getFileType(): FileTypeEnum
|
|
{
|
|
return $this->fileType;
|
|
}
|
|
/**
|
|
* Checks if the file is an inline file.
|
|
*
|
|
* @since 0.1.0
|
|
*
|
|
* @return bool True if the file is inline (base64/data URI).
|
|
*/
|
|
public function isInline(): bool
|
|
{
|
|
return $this->fileType->isInline();
|
|
}
|
|
/**
|
|
* Checks if the file is a remote file.
|
|
*
|
|
* @since 0.1.0
|
|
*
|
|
* @return bool True if the file is remote (URL).
|
|
*/
|
|
public function isRemote(): bool
|
|
{
|
|
return $this->fileType->isRemote();
|
|
}
|
|
/**
|
|
* Gets the URL for remote files.
|
|
*
|
|
* @since 0.1.0
|
|
*
|
|
* @return string|null The URL, or null if not a remote file.
|
|
*/
|
|
public function getUrl(): ?string
|
|
{
|
|
return $this->url;
|
|
}
|
|
/**
|
|
* Gets the base64-encoded data for inline files.
|
|
*
|
|
* @since 0.1.0
|
|
*
|
|
* @return string|null The plain base64-encoded data (without data URI prefix), or null if not an inline file.
|
|
*/
|
|
public function getBase64Data(): ?string
|
|
{
|
|
return $this->base64Data;
|
|
}
|
|
/**
|
|
* Gets the data as a data URI for inline files.
|
|
*
|
|
* @since 0.1.0
|
|
*
|
|
* @return string|null The data URI in format: data:[mimeType];base64,[data], or null if not an inline file.
|
|
*/
|
|
public function getDataUri(): ?string
|
|
{
|
|
if ($this->base64Data === null) {
|
|
return null;
|
|
}
|
|
return sprintf('data:%s;base64,%s', $this->getMimeType(), $this->base64Data);
|
|
}
|
|
/**
|
|
* Gets the MIME type of the file as a string.
|
|
*
|
|
* @since 0.1.0
|
|
*
|
|
* @return string The MIME type string value.
|
|
*/
|
|
public function getMimeType(): string
|
|
{
|
|
return (string) $this->mimeType;
|
|
}
|
|
/**
|
|
* Gets the MIME type object.
|
|
*
|
|
* @since 0.1.0
|
|
*
|
|
* @return MimeType The MIME type object.
|
|
*/
|
|
public function getMimeTypeObject(): MimeType
|
|
{
|
|
return $this->mimeType;
|
|
}
|
|
/**
|
|
* Checks if the file is a video.
|
|
*
|
|
* @since 0.1.0
|
|
*
|
|
* @return bool True if the file is a video.
|
|
*/
|
|
public function isVideo(): bool
|
|
{
|
|
return $this->mimeType->isVideo();
|
|
}
|
|
/**
|
|
* Checks if the file is an image.
|
|
*
|
|
* @since 0.1.0
|
|
*
|
|
* @return bool True if the file is an image.
|
|
*/
|
|
public function isImage(): bool
|
|
{
|
|
return $this->mimeType->isImage();
|
|
}
|
|
/**
|
|
* Checks if the file is audio.
|
|
*
|
|
* @since 0.1.0
|
|
*
|
|
* @return bool True if the file is audio.
|
|
*/
|
|
public function isAudio(): bool
|
|
{
|
|
return $this->mimeType->isAudio();
|
|
}
|
|
/**
|
|
* Checks if the file is text.
|
|
*
|
|
* @since 0.1.0
|
|
*
|
|
* @return bool True if the file is text.
|
|
*/
|
|
public function isText(): bool
|
|
{
|
|
return $this->mimeType->isText();
|
|
}
|
|
/**
|
|
* Checks if the file is a document.
|
|
*
|
|
* @since 0.1.0
|
|
*
|
|
* @return bool True if the file is a document.
|
|
*/
|
|
public function isDocument(): bool
|
|
{
|
|
return $this->mimeType->isDocument();
|
|
}
|
|
/**
|
|
* Checks if the file is a specific MIME type.
|
|
*
|
|
* @since 0.1.0
|
|
*
|
|
* @param string $type The mime type to check (e.g. 'image', 'text', 'video', 'audio').
|
|
*
|
|
* @return bool True if the file is of the specified type.
|
|
*/
|
|
public function isMimeType(string $type): bool
|
|
{
|
|
return $this->mimeType->isType($type);
|
|
}
|
|
/**
|
|
* Determines the MIME type from various sources.
|
|
*
|
|
* @since 0.1.0
|
|
*
|
|
* @param string|null $providedMimeType The explicitly provided MIME type.
|
|
* @param string|null $extractedMimeType The MIME type extracted from data URI.
|
|
* @param string|null $pathOrUrl The file path or URL to extract extension from.
|
|
* @return MimeType The determined MIME type.
|
|
* @throws InvalidArgumentException If MIME type cannot be determined.
|
|
*/
|
|
private function determineMimeType(?string $providedMimeType, ?string $extractedMimeType, ?string $pathOrUrl): MimeType
|
|
{
|
|
// Prefer explicitly provided MIME type
|
|
if ($providedMimeType !== null) {
|
|
return new MimeType($providedMimeType);
|
|
}
|
|
// Use extracted MIME type from data URI
|
|
if ($extractedMimeType !== null) {
|
|
return new MimeType($extractedMimeType);
|
|
}
|
|
// Try to determine from file extension
|
|
if ($pathOrUrl !== null) {
|
|
$parsedUrl = parse_url($pathOrUrl);
|
|
$path = $parsedUrl['path'] ?? $pathOrUrl;
|
|
// Remove query string and fragment if present
|
|
$cleanPath = strtok($path, '?#');
|
|
if ($cleanPath === \false) {
|
|
$cleanPath = $path;
|
|
}
|
|
$extension = pathinfo($cleanPath, \PATHINFO_EXTENSION);
|
|
if (!empty($extension)) {
|
|
try {
|
|
return MimeType::fromExtension($extension);
|
|
} catch (InvalidArgumentException $e) {
|
|
// Extension not recognized, continue to error
|
|
unset($e);
|
|
}
|
|
}
|
|
}
|
|
throw new InvalidArgumentException('Unable to determine MIME type. Please provide it explicitly.');
|
|
}
|
|
/**
|
|
* {@inheritDoc}
|
|
*
|
|
* @since 0.1.0
|
|
*/
|
|
public static function getJsonSchema(): array
|
|
{
|
|
return ['type' => 'object', 'oneOf' => [['properties' => [self::KEY_FILE_TYPE => ['type' => 'string', 'const' => FileTypeEnum::REMOTE, 'description' => 'The file type.'], self::KEY_MIME_TYPE => ['type' => 'string', 'description' => 'The MIME type of the file.', 'pattern' => '^[a-zA-Z0-9][a-zA-Z0-9!#$&\-\^_+.]*\/[a-zA-Z0-9]' . '[a-zA-Z0-9!#$&\-\^_+.]*$'], self::KEY_URL => ['type' => 'string', 'format' => 'uri', 'description' => 'The URL to the remote file.']], 'required' => [self::KEY_FILE_TYPE, self::KEY_MIME_TYPE, self::KEY_URL]], ['properties' => [self::KEY_FILE_TYPE => ['type' => 'string', 'const' => FileTypeEnum::INLINE, 'description' => 'The file type.'], self::KEY_MIME_TYPE => ['type' => 'string', 'description' => 'The MIME type of the file.', 'pattern' => '^[a-zA-Z0-9][a-zA-Z0-9!#$&\-\^_+.]*\/[a-zA-Z0-9]' . '[a-zA-Z0-9!#$&\-\^_+.]*$'], self::KEY_BASE64_DATA => ['type' => 'string', 'description' => 'The base64-encoded file data.']], 'required' => [self::KEY_FILE_TYPE, self::KEY_MIME_TYPE, self::KEY_BASE64_DATA]]]];
|
|
}
|
|
/**
|
|
* {@inheritDoc}
|
|
*
|
|
* @since 0.1.0
|
|
*
|
|
* @return FileArrayShape
|
|
*/
|
|
public function toArray(): array
|
|
{
|
|
$data = [self::KEY_FILE_TYPE => $this->fileType->value, self::KEY_MIME_TYPE => $this->getMimeType()];
|
|
if ($this->url !== null) {
|
|
$data[self::KEY_URL] = $this->url;
|
|
} elseif (!$this->fileType->isRemote() && $this->base64Data !== null) {
|
|
$data[self::KEY_BASE64_DATA] = $this->base64Data;
|
|
} else {
|
|
throw new RuntimeException('File requires either url or base64Data. This should not be a possible condition.');
|
|
}
|
|
return $data;
|
|
}
|
|
/**
|
|
* {@inheritDoc}
|
|
*
|
|
* @since 0.1.0
|
|
*/
|
|
public static function fromArray(array $array): self
|
|
{
|
|
static::validateFromArrayData($array, [self::KEY_FILE_TYPE]);
|
|
// Check which properties are set to determine how to construct the File
|
|
$mimeType = $array[self::KEY_MIME_TYPE] ?? null;
|
|
if (isset($array[self::KEY_URL])) {
|
|
return new self($array[self::KEY_URL], $mimeType);
|
|
} elseif (isset($array[self::KEY_BASE64_DATA])) {
|
|
return new self($array[self::KEY_BASE64_DATA], $mimeType);
|
|
} else {
|
|
throw new InvalidArgumentException('File requires either url or base64Data.');
|
|
}
|
|
}
|
|
/**
|
|
* Performs a deep clone of the file.
|
|
*
|
|
* This method ensures that the MimeType value object is cloned to prevent
|
|
* any shared references between the original and cloned file.
|
|
*
|
|
* @since 0.4.2
|
|
*/
|
|
public function __clone()
|
|
{
|
|
$this->mimeType = clone $this->mimeType;
|
|
}
|
|
}
|