upload()

public function upload(array $config): array

Description

Handles the file upload process with specified configuration. This method validates the configuration, processes the uploaded file, performs security checks, generates a secure filename, and moves the file to the target destination.

Validation First: Always validate uploaded files using Trongate's validation module before calling upload(). The validation module checks file type, size, and required status. The upload() method handles the physical file transfer after validation passes.

Parameters

Parameter	Type	Description	Required
$config	array	An associative array containing upload configuration options	Yes

Understanding The Configuration Array

The $config array controls where and how files are uploaded. It determines the destination directory, whether to use module-specific paths, and how filenames should be generated. At minimum, you must specify a destination directory - all other options have sensible defaults.

Property Name	Required	Expected Type	Description	Sample Value
destination	Yes	string	Target directory path. Behavior depends on upload_to_module setting.	`'public/uploads'`
upload_to_module	No	bool	If true, uploads to module directory. If false, uploads relative to application root. Default: false	`true`
target_module	No	string	Specific module name to use when upload_to_module is true. If not set, uses first URL segment. Default: current URL segment	`'users'`
make_rand_name	No	bool	Generate random 10-character alphanumeric filename while preserving extension. Default: false	`true`

Configuration Options Explained

destination

The target directory where the file will be stored. Behavior depends on upload_to_module:

When upload_to_module is false: Path relative to application root (e.g., 'public/uploads')
When upload_to_module is true: Path relative to module directory (e.g., 'documents' becomes 'modules/your_module/documents')

upload_to_module

Controls whether files are uploaded to a module directory or to the general application directory:

false (default): Uploads to path relative to application root
true: Uploads to path relative to the module directory

target_module

Specifies which module directory to use when upload_to_module is true:

If not set: Uses the first URL segment as the module name
If set: Uses the specified module name (useful for custom routing or cross-module uploads)

make_rand_name

Controls filename generation:

false (default): Preserves original filename (sanitized and made unique if needed)
true: Generates random 10-character alphanumeric filename, preserving extension

Return Value

Returns an associative array containing metadata about the successfully uploaded file:

Key	Type	Description
file_name	string	The final filename as stored on disk (may differ from original - see note below)
file_path	string	The complete filesystem path to the uploaded file
file_type	string	The detected MIME type (e.g., "application/pdf", "text/csv")
file_size	int	File size in bytes

Important: Understanding file_name

The returned file_name will often differ from the original uploaded filename due to security and uniqueness requirements:

Sanitization: Original names are processed by sanitize_filename(), which converts to lowercase, transliterates special characters (é → e), and replaces spaces/special characters with dashes
Uniqueness: If a file with the same name exists, a numeric suffix is added (e.g., document_2.pdf, document_3.pdf)
Randomization: When make_rand_name is true, the name becomes a random 10-character string (e.g., a7f9d2e1b4.pdf)

Always use the returned file_name value for database storage and file references - never assume the original filename was preserved.

Example #1

The code sample below demonstrates the most basic file upload operation.

The "Check Before You Act" Pattern: Always ensure the destination directory exists before calling upload(). Use $this->file->exists($directory) to check, and $this->file->create_directory($directory) to create if needed. This prevents upload failures due to missing directories.

Example #2

The example above shows how to upload files to a module directory with random filenames for security.

Random Filenames for Security: Setting make_rand_name to true prevents users from guessing file URLs and accessing other users' files. This is especially important for sensitive documents. Always store the returned file_name in your database so you can retrieve files later.

Example #3

The example above demonstrates organizing uploads into date-based subdirectories.

Using target_module: The target_module option is useful when you need to upload to a specific module directory regardless of the current URL structure. This is particularly valuable when using custom routing or when an admin module needs to upload files to other module directories.

Example #4

The example above shows a complete file upload workflow with backup and cleanup.

public function process_cv_upload(): void {
    $user_id = segment(3, 'int');
    
    // Verify user exists
    $user = $this->db->get_where($user_id, 'users');
    if ($user === false) {
        redirect('users/not_found');
    }
    
    // Validate CV file
    $this->validation->set_rules('userfile', 'CV/Resume', 'required|allowed_types[pdf,doc,docx]|max_size[5000]');
    
    if ($this->validation->run() === true) {
        // If user already has a CV, back it up before replacing
        if (!empty($user->cv_filename)) {
            $old_cv_path = 'modules/users/cvs/' . $user->cv_filename;
            if ($this->file->exists($old_cv_path)) {
                $backup_dir = 'modules/users/cvs/backups';
                if (!$this->file->exists($backup_dir)) {
                    $this->file->create_directory($backup_dir, 0755);
                }
                $backup_path = $backup_dir . '/' . date('Ymd_His') . '_' . $user->cv_filename;
                $this->file->copy($old_cv_path, $backup_path);
            }
        }
        
        // Ensure CV directory exists
        $cv_dir = 'modules/users/cvs';
        if (!$this->file->exists($cv_dir)) {
            $this->file->create_directory($cv_dir, 0755);
        }
        
        // Configure and execute upload
        $config['destination'] = 'cvs';
        $config['upload_to_module'] = true;
        $config['target_module'] = 'users';
        $config['make_rand_name'] = true;
        
        $file_info = $this->file->upload($config);
        
        // Update user record with new CV
        $update_data = [
            'cv_filename' => $file_info['file_name'],
            'cv_uploaded_at' => date('Y-m-d H:i:s')
        ];
        $this->model->update($user_id, $update_data, 'users');
        
        // Delete old CV file (after successful upload and DB update)
        if (!empty($user->cv_filename)) {
            $old_cv_path = 'modules/users/cvs/' . $user->cv_filename;
            if ($this->file->exists($old_cv_path)) {
                $this->file->delete($old_cv_path);
            }
        }
        
        set_flashdata('CV uploaded successfully');
        redirect('users/profile/' . $user_id);
    } else {
        // Validation failed - show form with errors
        $data['user'] = $user;
        $this->view('cv_upload_form', $data);
    }
}

Automatic Security Validation: The upload() method performs several security checks automatically: path validation prevents directory traversal attacks, MIME verification confirms file types match their extensions, content scanning checks for dangerous PHP patterns and executable code, filename sanitization removes dangerous characters, and memory checks verify sufficient system resources. These checks run automatically with no additional configuration required.