Fields

File

Basics

Contains all Basic methods.

Before using, ensure that a symbolic link is set up for the storage directory.
php artisan storage:link

The File field is used for file uploads and includes all basic methods.

 namespaces
use MoonShine\UI\Fields\File;
 
File::make('File')
 namespaces
use MoonShine\UI\Fields\File;
 
File::make('File')
<x-moonshine::form.wrapper label="File">
    <x-moonshine::form.file
        name="file"
    />
</x-moonshine::form.wrapper>
<x-moonshine::form.wrapper label="File">
    <x-moonshine::form.file
        name="file"
    />
</x-moonshine::form.wrapper>

To correctly generate the file URL, you must set the environment variable APP_URL to match your application's URL.

Disk

The disk() method allows you to change the filesystems disk.

disk(string $disk)
disk(string $disk)
File::make('File')
    ->disk('public')
File::make('File')
    ->disk('public')

By default, the disk public is used. You can change it in the configuration file.

When using the local driver, the returned url is not a valid URL. For this reason, we recommend always naming your files in a way that will create valid URLs.

Directory

By default, files will be saved in the root directory of the disk. The dir() method allows you to specify a directory for saving files relative to the root directory.

dir(string $dir)
dir(string $dir)
File::make('File')
    ->dir('docs')
File::make('File')
    ->dir('docs')

Allowed Extensions

File and Image inherit the global allowed_extensions list from configuration. By default, the list is empty ([]), so extensions are unrestricted.

Use allowedExtensions() to replace the global list for an individual field. Specify extensions without a leading dot.

allowedExtensions(array|string $allowedExtensions)
allowedExtensions(array|string $allowedExtensions)
 namespaces
use MoonShine\UI\Fields\File;
 
File::make('Document')
    ->allowedExtensions(['pdf', 'doc', 'txt'])
 namespaces
use MoonShine\UI\Fields\File;
 
File::make('Document')
    ->allowedExtensions(['pdf', 'doc', 'txt'])

This field accepts its own list even if the global list only allows images. The lists are not merged. An explicit empty list ([]), the string '*', or the array ['*'] allows all extensions and overrides any global restriction.

File::make('Attachment')->allowedExtensions([]);
File::make('Attachment')->allowedExtensions('*');
File::make('Attachment')->allowedExtensions(['*']);
File::make('Attachment')->allowedExtensions([]);
File::make('Attachment')->allowedExtensions('*');
File::make('Attachment')->allowedExtensions(['*']);

The effective list provides the default HTML accept attribute and is checked on the server during uploads. The server checks both the extension detected from the uploaded file's MIME type and the extension of the stored filename, including names supplied by keepOriginalFileName() or customName().

To customize only the browser's file picker, use accept() or an explicit accept attribute. This does not change the server-side allowed extensions.

File::make('Document')
    ->allowedExtensions(['pdf'])
    ->accept('application/pdf')
File::make('Document')
    ->allowedExtensions(['pdf'])
    ->accept('application/pdf')

When using <x-moonshine::form.file> directly in Blade, set accept explicitly and validate uploads in your handler. The global setting is applied by the PHP File and Image fields.

Multiple Upload

To upload multiple files, use the multiple() method.

multiple(Closure|bool|null $condition = null)
multiple(Closure|bool|null $condition = null)
File::make('File')
    ->multiple()
File::make('File')
    ->multiple()

In the database, the field must be of type "text" or "json". It is also necessary to specify cast — "array", "json" or "collection".

File Removal

To enable file removal, you need to use the removable() method.

removable(
    Closure|bool|null $condition = null,
    array $attributes = []
)
removable(
    Closure|bool|null $condition = null,
    array $attributes = []
)
  • $condition - the condition for executing the method,
  • $attributes - additional attributes for the button.
File::make('File')
    ->removable()
File::make('File')
    ->removable()

The delete button will be available in the editing mode of the field.

When deleting a resource, the files are also deleted.

When mass deleting resource items, files are not deleted. You need to implement file deletion for mass resource item deletion yourself.

Attributes

File::make('File')
    ->removable(
        attributes: ['@click.prevent' => '$event.target.closest(`.x-removeable`).remove()']
    )
File::make('File')
    ->removable(
        attributes: ['@click.prevent' => '$event.target.closest(`.x-removeable`).remove()']
    )

disableDeleteFiles()

The disableDeleteFiles() method allows you to delete only the database record but not the actual file.

disableDeleteFiles()
disableDeleteFiles()
File::make('File')
    ->removable()
    ->disableDeleteFiles()
File::make('File')
    ->removable()
    ->disableDeleteFiles()

enableDeleteDir()

The enableDeleteDir() method deletes the directory specified in the dir() method if it is empty.

enableDeleteDir()
enableDeleteDir()
File::make('File')
    ->dir('docs')
    ->removable()
    ->enableDeleteDir()
File::make('File')
    ->dir('docs')
    ->removable()
    ->enableDeleteDir()

Disable Download

The disableDownload() method allows you to exclude the ability to download the file.

disableDownload(Closure|bool|null $condition = null)
disableDownload(Closure|bool|null $condition = null)
File::make('File', 'file')
    ->disableDownload()
File::make('File', 'file')
    ->disableDownload()

Original File Name

When uploading, a file name is generated by default. The keepOriginalFileName() method allows you to keep the original file name.

keepOriginalFileName()
keepOriginalFileName()
File::make('File')
    ->keepOriginalFileName()
File::make('File')
    ->keepOriginalFileName()

Custom File Name

The customName() method allows you to save a file with a custom name.

customName(Closure $name)
customName(Closure $name)
 namespaces
use Illuminate\Http\UploadedFile;
use Illuminate\Support\Str;
 
File::make('File', 'file')
    ->customName(fn(UploadedFile $file, Field $field) =>  Str::random(10) . '.' . $file->extension())
 namespaces
use Illuminate\Http\UploadedFile;
use Illuminate\Support\Str;
 
File::make('File', 'file')
    ->customName(fn(UploadedFile $file, Field $field) =>  Str::random(10) . '.' . $file->extension())

Element Names

The names() method allows you to change the displayed name without altering the file name.

names(Closure $closure)
names(Closure $closure)
  • $closure - a closure that takes the file name and the file index as parameters.
File::make('File', 'file')
    ->names(fn(string $filename, int $index = 0) => 'File ' . $index + 1)
File::make('File', 'file')
    ->names(fn(string $filename, int $index = 0) => 'File ' . $index + 1)

Sorting with dragging

You can specify a URL that will process the positions and save the new ones.

File::make('Files')
    ->reorderable(fn(File $ctx) => "/reorder/" . $ctx->getData()->getKey())
    ->multiple(),
File::make('Files')
    ->reorderable(fn(File $ctx) => "/reorder/" . $ctx->getData()->getKey())
    ->multiple(),

Element Attributes

The itemAttributes() method allows you to add additional attributes to the elements.

itemAttributes(Closure $closure)
itemAttributes(Closure $closure)
  • $closure - a closure that takes the file name and the file index as parameters.
File::make('File', 'file')
    ->itemAttributes(fn(string $filename, int $index = 0) => [
        'style' => 'width: 250px; height: 250px;'
    ])
File::make('File', 'file')
    ->itemAttributes(fn(string $filename, int $index = 0) => [
        'style' => 'width: 250px; height: 250px;'
    ])

Dropzone attributes

File::make('Files')
    ->dropzoneAttributes(fn(File $ctx) => ['class' => 'custom-class'])
    ->multiple(),
File::make('Files')
    ->dropzoneAttributes(fn(File $ctx) => ['class' => 'custom-class'])
    ->multiple(),

Helper Methods

getRemainingValues()

The getRemainingValues() method allows you to get the values that remain in the form, taking into account deletions.

getRemainingValues()
getRemainingValues()

removeExcludedFiles()

The removeExcludedFiles() method allows you to physically delete files during the process.

removeExcludedFiles()
removeExcludedFiles()