API 參考

這裡列出 Laravel 應用程式會使用的方法與欄位。需要完整範例與行為時，可前往各段落 提供的說明頁面。下方程式區塊是方法簽章索引，不是可以直接執行的 PHP 程式。

建立待儲存檔案

FileMagic::fromUpload(UploadedFile $file): PendingFile
FileMagic::fromPath(string $path): PendingFile
FileMagic::fromContent(string $contents, ?string $originalFilename = null, ?string $mimeType = null): PendingFile
FileMagic::fromGeneratedContent(string $contents, ?string $originalFilename = null, ?string $mimeType = null): PendingFile
FileMagic::fromBase64(string $base64, ?string $originalFilename = null): PendingFile
FileMagic::fromUrl(string $url, ?RemoteFileOptions $options = null): PendingFile
FileMagic::text(string $text): PendingFile
FileMagic::json(array|JsonSerializable $data): PendingFile
FileMagic::csv(iterable $rows): PendingFile

• fromUpload()：接受 Laravel 上傳檔案。
• fromPath()：接受應用程式選擇的可讀本機路徑。
• fromContent()：接受文字或二進位內容。$originalFilename 與 $mimeType 是選用的 來源資訊，儲存類型仍以內容為準。
• fromGeneratedContent()：接受應用程式產生的 bytes。非 null MIME type 具有 Symfony extension mapping 時，會直接用於 MIME 政策與副檔名；MIME 為 null 或無 mapping 時委派給 fromContent()，非 null 的值仍只作不可信任提示。原始檔名不會決定 MIME 或儲存名稱； 這也不是內容安全認證。完整 $contents 已位於 PHP 記憶體，請勿將不可信任來源 連同可識別 MIME 傳入此入口。
• fromBase64()：接受 Base64 文字或 Base64 Data URI。
• fromUrl()：建立 HTTP(S) 來源，在 store() 時才下載；$options 可調整這次下載的規則。
• text()、json()、csv()：產生可以像一般檔案一樣儲存的內容。

以上方法都回傳 PendingFile。完整說明請看儲存檔案、 遠端檔案及文件與圖片。

設定並儲存 PendingFile

$pending->onDisk(string $disk): self
$pending->inDirectory(string $directory): self
$pending->named(string|int $filename): self
$pending->visibility(FileVisibility $visibility): self
$pending->onCollision(CollisionPolicy $policy): self
$pending->maxSize(int $bytes): self
$pending->allowMimeTypes(array $mimeTypes): self
$pending->blockMimeTypes(array $mimeTypes): self
$pending->withMetadata(array $metadata): self
$pending->ownedBy(Model $owner): self
$pending->resizeImage(?int $maxWidth = null, ?int $quality = null): self
$pending->store(): StoredFile

• onDisk()：選擇已設定的 Laravel Filesystem disk，disk 名稱不可為空字串。
• inDirectory()：選擇以 / 分隔、相對於 disk 的目錄；空字串代表根目錄。不安全或模糊路徑會拋出 InvalidStoragePath。
• named()：設定不含副檔名的檔名。不安全、保留、空白或超過 200 字元的名稱會拋出 InvalidFileName。
• visibility()：選擇 FileVisibility::Private 或 FileVisibility::Public。
• onCollision()：路徑已存在時選擇 Unique、Error 或 Overwrite。
• maxSize()：以正整數設定原始輸入與最終儲存結果可接受的最大 bytes。
• allowMimeTypes()：只接受清單中的 MIME type；空清單不額外限制。元素必須是非空字串。
• blockMimeTypes()：拒絕清單中的 MIME type；元素必須是非空字串，清單本身可以為空。
• withMetadata()：將應用程式資料儲存在檔案紀錄的 metadata 欄位。
• ownedBy()：關聯已儲存且主鍵為整數或非空字串的 Eloquent Model，否則拋出 InvalidFileOwner。
• resizeImage()：設定支援圖片的最大寬度與輸出品質；參數為 null 時使用設定預設值， 寬度必須為正整數，品質必須介於 1 至 100。
• store()：儲存實體檔案並回傳 StoredFile 紀錄。

尋找檔案

FileMagic::find(int|string|StoredFile|array|Collection ...$targets): FileQuery

$targets 可使用 ID、UUID、已存在的 StoredFile Model、一維 array 及 Laravel Collection，也能同時傳入多個不同類型的 targets。完整說明請看 查詢檔案。

$query->one(): ?StoredFile
$query->get(): Collection
$query->urls(): Collection
$query->exists(): bool
$query->url(): string
$query->temporaryUrl(?DateTimeInterface $expiration = null): string
$query->contents(): string
$query->readStream(): resource
$query->download(?string $name = null): StreamedResponse
$query->downloadZip(?string $name = null): BinaryFileResponse
$query->delete(): int

• one()：回傳第一筆符合的檔案紀錄，找不到時為 null。
• get()：以 Collection<int, StoredFile> 回傳全部符合的紀錄。
• urls()：回傳以 Model key 為索引的公開 URL；storage 上不存在的檔案會省略。
• exists()：確認第一筆符合的實體檔案是否存在。
• url()：取得第一筆符合檔案的公開 URL。
• temporaryUrl()：取得 temporary URL；$expiration 為 null 時使用設定的有效時間。
• contents()：以 string 取得第一筆符合檔案的完整內容。
• readStream()：取得第一筆符合檔案的 readable stream；使用完畢後必須關閉。
• download()：回傳串流下載；$name 可取代下載檔名。
• downloadZip()：將全部符合檔案回傳為 ZIP 下載；$name 設定 ZIP 檔名。
• delete()：刪除符合的實體檔案與紀錄，回傳完成刪除的數量。

沒有紀錄時，one() 回傳 null，get() 與 urls() 回傳空 Collection，delete() 回傳 0。 downloadZip() 與所有需要第一筆結果的方法（包括 exists()）會拋出 FileNotFound。

StoredFile 欄位

StoredFile 是儲存或查詢完成後取得的 Eloquent 紀錄。

欄位	型別	資料
id	int	Database key。
uuid	string	對外使用的唯一識別碼。
disk	string	Laravel Filesystem disk。
path	string	相對於 disk 的完整路徑。
location_hash	string	Disk 與 path 組合的識別值。
filename	string	不含副檔名的儲存檔名。
original_filename	?string	有提供時的原始檔名。
extension	string	儲存副檔名。
mime_type	string	檔案的 MIME type。
size	int	檔案 bytes。
checksum	?string	有提供時的 checksum。
visibility	FileVisibility	Public 或 private visibility。
owner_type, owner_id	?string	Polymorphic owner identifiers。
metadata	?array	與檔案一同儲存的應用程式資料。
created_at, updated_at	?Carbon	紀錄時間。
owner	?Model	關聯的 Eloquent Model。

StoredFile 方法

$file->owner(): MorphTo
$file->storage(): FilesystemAdapter
$file->existsOnDisk(): bool
$file->fullName(): string
$file->originalName(): string
$file->url(): string
$file->temporaryUrl(DateTimeInterface $expiration): string
$file->contents(): string
$file->readStream(): resource
$file->download(?string $name = null): StreamedResponse
$file->delete(): ?bool

• owner()：提供 Eloquent owner relationship。
• storage()：取得 disk 對應的 Laravel Filesystem adapter。
• existsOnDisk()：確認 path 是否存在於 disk。
• fullName()：取得 filename 與 extension 組成的完整檔名。
• originalName()：取得 original_filename；沒有原始檔名時回傳 fullName()。
• Model 的 temporaryUrl() 必須明確傳入到期時間；要使用 temporary_url_ttl，請改用 FileMagic::find($target)->temporaryUrl()。
• URL、內容、stream、下載及刪除方法會操作這筆紀錄對應的實體檔案。

RemoteFileOptions

RemoteFileOptions 用來調整單次 fromUrl() 下載，提供以下 public 欄位：

欄位	型別	預設	用途
verifyTls	bool	true	要求有效的 HTTPS certificate。
allowHttp	bool	false	允許未加密 HTTP。
allowHtml	bool	false	允許 HTML 與 XHTML 內容。
connectTimeoutSeconds	int	5	最長連線時間。
timeoutSeconds	int	30	每次 HTTP 請求的最長秒數。
maxRedirects	int	3	最多 redirect 次數，範圍 0 至 10。
allowedHosts	list<string>	[]	精確 host allowlist；空陣列允許符合條件的 public hosts。
allowedPorts	list<int>	[80, 443]	允許的連線 ports。
allowedPrivateHosts	list<string>	[]	明確允許的 private hosts。

RemoteFileOptions::withoutTlsVerification(): RemoteFileOptions

只有無法驗證 certificate 的受控環境才使用此 helper。它不會開啟 HTTP，也不會允許 private hosts。完整說明請看遠端檔案。

Enums

FileVisibility::Private
FileVisibility::Public

CollisionPolicy::Unique
CollisionPolicy::Error
CollisionPolicy::Overwrite

Unique 在目標存在時更換檔名，Error 拒絕檔名碰撞，Overwrite 取代檔案並保持 相同 storage path。

例外結果方法

所有套件例外都繼承 FileMagicException。完整清單請看 Model 與例外。

$exception->deletedCount(): int
$exception->failedCount(): int
$exception->failedKeys(): array

PartialFileDeletion 的這些方法會取得完成數量、失敗數量，以及仍需處理的 Model keys。

$exception->operationFailure(): Throwable

FileRecoveryFailed::operationFailure() 會取得觸發補償的原始錯誤；getPrevious() 則是 舊檔案還原或新檔案清理失敗的原因。