☰
Trongate PHP Framework Docs
Introduction
Quick Start
Basic Concepts
Understanding Routing
Intercepting Requests
Module Fundamentals
Database Operations
Templates
Helpers
Form Handling
Form Validation
Working With Files
Image Manipulation
Working With Dates & Times
Language Control
Security
Tips And Best Practices

File Handling Quick Reference

This reference lists all methods available in Trongate's File module when calling $this->file->method_name().

Note: All file operations include automatic security validation to prevent directory traversal attacks and unauthorized access to restricted areas (config, engine).

File Upload

Method Parameters Returns Description
array $config array Uploads a file to the specified destination with security validation and optional random naming.

Configuration Array Keys

Key Type Default Description
destination string required Target directory path (relative to application root or module).
upload_to_module bool false If true, uploads to the module directory.
target_module string current segment Specifies which module to upload to when upload_to_module is true.
make_rand_name bool false If true, generates a secure random 10-character alphanumeric filename.

Example Usage

PHP
$config = [
    'destination' => 'uploads',
    'upload_to_module' => true
];

$file_info = $this->file->upload($config);

/* Returns:
[
    'file_name' => 'document.pdf',
    'file_path' => 'modules/your_module/uploads/document.pdf',
    'file_type' => 'application/pdf',
    'file_size' => 245760
]
*/

File Operations

Method Parameters Returns Description
string $file_path bool Deletes the specified file. Returns true on success.
string $source
string $destination		 bool Copies a file from source to destination. Returns true on success.
string $source
string $destination		 bool Moves a file from source to destination. Returns true on success.
string $file_path string Reads and returns the entire contents of a file.
string $file_path
mixed $data
bool $append = false		 bool Writes content to a file. Set $append to true to add to existing content.
string $file_path
bool $as_attachment = true		 void Initiates file download or displays inline. Calls exit after sending file.

File Information & Directories

Method Parameters Returns Description
string $file_path array Returns detailed metadata about a file (size, MIME type, permissions, etc.).
string $file_path bool Checks if a file or directory exists at the specified path.
string $path
int $perms = 0755
bool $recursive = true		 bool Creates a directory with specified permissions. Returns true if created or already exists.
string $directory_path bool Recursively deletes a directory and all of its contents. Use with caution.
string $path
bool $recursive = false		 array Lists all files/directories within the specified path. Returns nested array if recursive.

Validation Rules

Use these rules with $this->validation->set_rules() during file uploads.

Rule Parameter Description
allowed_types extensions Comma-separated extensions (e.g., allowed_types[jpg,png]).
max_size KB Maximum file size in kilobytes (e.g., max_size[2048]).
max_width / max_height Pixels Maximum image dimensions.
min_width / min_height Pixels Minimum image dimensions.
square None Validates that the image has a 1:1 aspect ratio.

Common Patterns

Pattern 1: Basic Upload with Validation

The simplest complete upload workflow following the three-method pattern.

PHP
// Step 1: Display form
function upload_form() {
    $this->view('upload_form');
}

// Step 2: Process upload
function submit_upload() {
    $this->validation->set_rules('userfile', 'File', 'required|allowed_types[pdf]|max_size[5000]');
    
    $result = $this->validation->run();
    
    if ($result === true) {
        $config['destination'] = 'uploads';
        $config['upload_to_module'] = true;
        
        $file_info = $this->file->upload($config);
        
        set_flashdata('File uploaded successfully');
        redirect('documents/success/' . $file_info['file_name']);
    } else {
        $this->upload_form();
    }
}

// Step 3: Show success
function success() {
    $filename = segment(3);
    $data['filename'] = $filename;
    $this->view('upload_success', $data);
}

The Three-Method Pattern: This clean pattern separates concerns - one method displays the form, one processes the upload, and one shows success. When validation fails, we call $this->upload_form() to redisplay the form with errors. When validation succeeds, we redirect to prevent duplicate submissions.

Pattern 2: Temporary File Processing with Cleanup

When you need to process a file temporarily before moving it to permanent storage, use this pattern with automatic cleanup.

PHP
function process_import() {
    // Validate the uploaded file
    $this->validation->set_rules('userfile', 'CSV File', 'required|allowed_types[csv]|max_size[5000]');
    
    $result = $this->validation->run();
    
    if ($result === true) {
        // Create temporary directory for processing
        $temp_dir = 'temp/import_' . uniqid();
        $this->file->create_directory($temp_dir, 0700);
        
        try {
            // Upload to temporary location
            $config['destination'] = $temp_dir;
            $file_info = $this->file->upload($config);
            
            // Process the file
            $content = $this->file->read($file_info['file_path']);
            // ... process CSV data ...
            
            // Move to permanent storage
            $permanent_dir = 'uploads/imports';
            $this->file->create_directory($permanent_dir, 0755);
            $this->file->move($file_info['file_path'], $permanent_dir . '/' . $file_info['file_name']);
            
            set_flashdata('Import completed');
            redirect('imports/success');
            
        } finally {
            // Cleanup: always remove temporary directory
            if ($this->file->exists($temp_dir)) {
                $items = $this->file->list_directory($temp_dir);
                foreach ($items as $item) {
                    $this->file->delete($temp_dir . '/' . $item);
                }
                rmdir($temp_dir);
            }
        }
    } else {
        $this->import_form();
    }
}

Why Use a finally Block: The finally block ensures temporary files are always cleaned up, even if an error occurs during processing. This prevents orphaned temporary files from accumulating on your server. The cleanup code runs whether the upload succeeds or fails.

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.

Leave Feedback About This Page