Files & Folders
Work with the File and Folder models
Files & Folders
The File model
File represents a stored file and its metadata. Beyond the database columns it offers helpers for type detection, storage access, and search.
Type helpers
$file->isImage(); // mimetype starts with image/
$file->isVideo(); // mimetype starts with video/
$file->isAudio(); // mimetype starts with audio/Reading the file
// Absolute filesystem path — local disks only, throws on remote disks
$path = $file->getFullPath();
// Stream resource — works with local and remote disks (S3, etc.)
$stream = $file->getStream();Searching
The search scope matches against filename_disk, filename_download, title, and description:
File::search('invoice')->get();Relationships
$file->folder; // BelongsTo<Folder>
$file->attachments; // HasMany<Attachment>, ordered by sortFile metadata
The metadata column is cast to a FileMetadataValueObject, so you read structured data instead of decoding JSON:
$file->metadata->width;
$file->metadata->height;
$file->metadata->aspect_ratio;
$file->metadata->color_space;
$file->metadata->color_profile;
$file->metadata->bit_depth;
$file->metadata->resolution; // ResolutionValueObject|null (DPI)
$file->metadata->exif; // ExifValueObject|null
$file->metadata->iptc; // IptcValueObject|nullSee File Metadata for the full structure.
The Folder model
Folder is an optional self-nesting tree for organizing files:
use OiLab\OiLaravelAttachments\Models\Folder;
$root = Folder::create(['name' => 'Invoices']);
$year = Folder::create(['name' => '2026', 'parent_id' => $root->id]);Relationships
$folder->parent; // BelongsTo<Folder>
$folder->children; // HasMany<Folder>
$folder->files; // HasMany<File>A file is placed in a folder by setting its folder_id:
$file->update(['folder_id' => $year->id]);Soft deletes
Both File and Folder use soft deletes, so deleting a record keeps the row (and its history) while hiding it from queries. The attachments pivot rows are removed via the database cascadeOnDelete on file_id when a file is force-deleted.