File Uploading Deep Dive
Building on the basic upload pattern, the method offers several configuration options that allow you to customize how and where your files are stored.
All customization happens within the $config array that is passed to the method.
The Configuration Array
The following four keys allow you to control the behavior of your uploads:
| Key | Type | Required | Default | Description |
|---|---|---|---|---|
destination |
string | yes | N/A | The path to the target directory. |
upload_to_module |
bool | no | false | If true, the destination is relative to the module folder. |
target_module |
string | no | current | The module directory to be used for the upload. |
make_rand_name |
bool | no | false | If true, generates a random 10-character filename. |
1. Choosing a Destination
The destination key determines where your uploaded files are stored. The behavior depends on whether you're uploading to the public directory or to a module directory.
Public Directory Uploads
By default (when upload_to_module is false or not set), files are uploaded to a directory within your public folder. This is ideal for publicly accessible files that don't require access control.
Important: Before uploading to the public directory, ensure the target directory exists and has the correct permissions (typically 755).
Module-Based Uploads
Setting upload_to_module to true keeps your files contained within your module directory.
External Module Uploads
If you are in one module (e.g., 'admin') but want to save files into another module (e.g., 'products'), you can use the target_module key. This is useful for centralized admin interfaces that manage content across multiple modules. The target_module key is also useful for scenarios were custom routing is being applied.
2. Handling Filenames
Trongate gives you two ways to handle the naming of uploaded files.
Original Filenames
By default, the original filename is preserved. If a file with the same name already exists in the destination folder, Trongate will automatically append a numeric suffix (e.g., filename_2.pdf) to prevent overwriting.
Random Filenames
For improved security and to prevent users from guessing file URLs, you can generate a random filename. The original file extension will always be preserved.
The File module uses Trongate's built-in function to ensure all uploaded files have safe, URL-friendly names. This function automatically handles international characters, removes special characters, replaces spaces with hyphens, and prevents security issues like null byte attacks - all without any configuration required.
3. Processing the Return Data
Once has executed successfully, it returns an array containing metadata about the file. This is useful for displaying information to the user or preparing data for a database entry.
Note: The file_size is returned in bytes.
Real-World Example: CV Upload with Database Integration
Let's combine what we've learned with a practical scenario: allowing users to upload their CV/resume. This example demonstrates how to store file references in your database for later retrieval.
Why Database Integration Matters
When you use random filenames for security, you need a way to retrieve those files later. Storing file metadata in your database allows you to:
- Associate files with users: Track who uploaded what and when
- Retrieve files reliably: Find files using database queries instead of guessing filenames
- Display file information: Show upload dates, file sizes, and original names to users
- Manage files programmatically: Build download, delete, and update features
The Complete Implementation
Understanding the Pattern
This example follows the same clean pattern from the basic uploader:
- Validate first: Check file type and size before uploading
- Configure the upload: Use random names and module storage for security
- Upload the file: The File module handles the heavy lifting
- Store the reference: Save the filename and upload date to your database
- Redirect on success: Use the POST-Redirect-GET pattern
We're continually improving the Trongate documentation. If anything is incorrect, unclear, incomplete, or could be better, we'd genuinely appreciate your input.
Share your thoughts in the Documentation Feedback.