README

anomaly.field_type.file

A file upload field type.

The file field type provides a single file upload input with integration to the Files Module.

Features

• Single file upload
• Integration with Files Module
• BelongsTo relationship with file records
• Folder restrictions for organized uploads
• File type/extension filtering
• Drag and drop upload support
• File browsing from media library
• Preview support for images and documents
• Configurable display modes

Configuration

Basic Configuration

protected $fields = [ 'attachment' => [ 'type' => 'anomaly.field_type.file' ] ];

With Folder Restriction

'document' => [ 'type' => 'anomaly.field_type.file', 'config' => [ 'folders' => ['documents'] ] ]

With File Type Restrictions

'avatar' => [ 'type' => 'anomaly.field_type.file', 'config' => [ 'folders' => ['avatars'], 'extensions' => ['jpg', 'jpeg', 'png'] ] ]

With Display Mode

'image' => [ 'type' => 'anomaly.field_type.file', 'config' => [ 'mode' => 'compact', 'folders' => ['images'] ] ]

Usage Examples

Basic File Upload

$stream->create([ 'attachment' => 1 // File ID ]);

With File Upload in Form

protected $fields = [ 'document' => [ 'type' => 'anomaly.field_type.file', 'rules' => [ 'required' ] ] ];

Accessing Values

In Twig Templates

{# Display file name #} {{ entry.attachment.name }} {# Display file link #} <a href="{{ entry.attachment.path }}">Download {{ entry.attachment.name }}</a> {# Display image #} {% if entry.image %} <img src="{{ entry.image.path }}" alt="{{ entry.image.name }}"> {% endif %} {# Display image with manipulation #} <img src="{{ entry.avatar.make().fit(200, 200).path() }}" alt="Avatar"> {# Check if file exists #} {% if entry.document %} <p>Document attached: {{ entry.document.name }}</p> {% endif %} {# Get file properties #} {{ entry.attachment.size }} bytes {{ entry.attachment.extension }} {{ entry.attachment.mime_type }}

In PHP

$entry = $model->find(1); // Get file object $file = $entry->attachment; if ($file) { // Get file properties $name = $file->name; $path = $file->path(); $size = $file->size; $extension = $file->extension; $mimeType = $file->mime_type; // Get file ID $fileId = $entry->attachment_id; // Image manipulation if ($file->isImage()) { $thumbnail = $file->make()->fit(150, 150)->path(); } }

Setting Values

In Forms

$form = $builder->make('example.module.test'); $form->on('saving', function(FormBuilder $builder) { $entry = $builder->getFormEntry(); // Set file ID $entry->attachment = 5; });

Direct Assignment

// Set by file ID $entry->attachment_id = 10; $entry->save(); // Or set by file object $file = File::find(10); $entry->attachment()->associate($file); $entry->save();

Database Structure

The file field type stores the file relationship as:

• INTEGER - Foreign key to files_files.id

Validation

Required File

'attachment' => [ 'type' => 'anomaly.field_type.file', 'rules' => [ 'required' ] ]

File Must Exist

'document' => [ 'type' => 'anomaly.field_type.file', 'rules' => [ 'required', 'exists:files_files,id' ] ]

Common Use Cases

User Avatar

'avatar' => [ 'type' => 'anomaly.field_type.file', 'config' => [ 'folders' => ['avatars'], 'extensions' => ['jpg', 'jpeg', 'png', 'gif'], 'mode' => 'compact' ] ]

PDF Document Upload

'contract' => [ 'type' => 'anomaly.field_type.file', 'config' => [ 'folders' => ['contracts'], 'extensions' => ['pdf'] ], 'rules' => [ 'required' ] ]

Product Featured Image

'featured_image' => [ 'type' => 'anomaly.field_type.file', 'config' => [ 'folders' => ['products'], 'extensions' => ['jpg', 'jpeg', 'png'] ], 'rules' => [ 'required' ] ]

Report Attachment

'report' => [ 'type' => 'anomaly.field_type.file', 'config' => [ 'folders' => ['reports'], 'extensions' => ['pdf', 'doc', 'docx', 'xls', 'xlsx'] ] ]

Best Practices

1. Restrict Folders: Always limit uploads to specific folders for organization
2. Validate Extensions: Use extension restrictions for security
3. Image Optimization: Use image manipulation for thumbnails and responsive images
4. Clean Up: Implement cleanup for unused file records
5. Check Existence: Always check if file exists before accessing properties
6. Use Relationships: Leverage Eloquent relationships for easy access
7. Consider Storage: Monitor disk space for large file uploads

Requirements

• Streams Platform ^1.10
• PyroCMS 3.10+
• Files Module

License

The File Field Type is open-sourced software licensed under the MIT license.

Authors

PyroCMS, Inc. - https://pyrocms.com Ryan Thompson - support@pyrocms.com