☰
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 Management Beyond Uploads

Uploading files is just the beginning. Once files are on your server, you need to manage them.

Trongate's File module provides methods for all common file operations:

  • Checking if files exist
  • Deleting files
  • Copying files
  • Moving/renaming files
  • Reading file contents
  • Writing to files
  • Getting file information

Before proceeding: This page assumes you understand how file paths work in Trongate. All examples use relative paths for PHP operations.

The Pattern: Check Before You Act

All file management methods follow a simple calling pattern:

PHP
$this->file->method_name($path, $parameters...);

The methods introduced on this page throw exceptions for genuine errors (permission denied, disk full, file locked) - not for expected conditions that you should handle in advance.

It's highly recommended to make sure appropriate conditions are met before trying to invoke file management methods.

Make sure files exist before calling file management methods:

PHP
// ✅ GOOD: Check first, then act
if ($this->file->exists($file_path)) {
    $this->file->delete($file_path);
    set_flashdata('File deleted successfully');
    redirect('files/manage');
} else {
    redirect('files/not_found');
}

// ❌ BAD: Don't rely on exceptions for validation
try {
    $this->file->delete($file_path);
    set_flashdata('File deleted successfully'); // Wrong use of flashdata
} catch (Exception $e) {
    set_flashdata('Failed: ' . $e->getMessage()); // Wrong use of flashdata
}

1. Checking File Existence

Use to make sure a file exists before operating on it:

PHP
/**
 * @param string $path File or directory path
 * @return bool True if exists, false otherwise
 */
public function exists(string $path): bool

Example: Verify Before Deletion

PHP
public function remove_user_file($file_id): void {
    // Get the database record
    $file_record = $this->db->get_where($file_id, 'user_files');
    
    if ($file_record === false) {
        redirect('files/not_found');
    }
    
    // Reconstruct the relative file path
    $file_path = '../modules/users/uploads/' . $file_record->filename;
    
    // Check if file exists before attempting deletion
    if ($this->file->exists($file_path)) {
        $this->file->delete($file_path);
        $this->db->delete($file_id, 'user_files');
        set_flashdata('File removed successfully');
        redirect('files/manage');
    } else {
        redirect('files/not_found');
    }
}

2. Deleting Files

The method removes files from the file system:

PHP
/**
 * @param string $file_path Path to the file
 * @return bool True if deleted successfully
 * @throws Exception If file doesn't exist or can't be deleted
 */
public function delete(string $file_path): bool

Example: Clean Up Old Uploads

PHP
public function cleanup_old_files(): void {
    // Find files older than 30 days
    $cutoff_date = date('Y-m-d H:i:s', strtotime('-30 days'));
    $sql = 'SELECT id, filename FROM temp_uploads WHERE created_at < ?';
    $old_files = $this->db->query($sql, [$cutoff_date], 'object');
    
    $deleted_count = 0;
    
    foreach ($old_files as $file) {
        $file_path = 'public/temp/' . $file->filename;
        
        if ($this->file->exists($file_path)) {
            $this->file->delete($file_path);
            $this->db->delete($file->id, 'temp_uploads');
            $deleted_count++;
        }
    }
    
    set_flashdata("Cleaned up $deleted_count old files");
    redirect('admin/maintenance');
}

3. Copying Files

The method copies a file from one location to another.

PHP
/**
 * @param string $source_path Original file location
 * @param string $destination_path Copy target location
 * @return bool True if copied successfully
 * @throws Exception If source doesn't exist or copy fails
 */
public function copy(string $source_path, string $destination_path): bool

Example: Create Document Backup

PHP
public function backup_document($document_id): void {
    $document = $this->db->get_where($document_id, 'documents');
    
    if ($document === false) {
        redirect('documents/not_found');
    }
    
    // Original file location
    $source_path = '../modules/documents/storage/' . $document->filename;
    
    // Check source exists
    if (!$this->file->exists($source_path)) {
        redirect('documents/not_found');
    }
    
    // Create dated backup directory if needed
    $backup_dir = '../modules/documents/backups/' . date('Y-m-d');
    if (!$this->file->exists($backup_dir)) {
        $this->file->create_directory($backup_dir, 0755, true);
    }
    
    // Create backup
    $backup_path = $backup_dir . '/' . $document->filename;
    $this->file->copy($source_path, $backup_path);
    
    set_flashdata('Backup created successfully');
    redirect('documents/view/' . $document_id);
}

4. Moving Files

With you can relocate or rename files in a single operation:

PHP
/**
 * @param string $source_path Current file location
 * @param string $destination_path New file location
 * @return bool True if moved successfully
 * @throws Exception If source doesn't exist or move fails
 */
public function move(string $source_path, string $destination_path): bool

Example: Organize Files by Date

PHP
public function organize_by_date($file_id): void {
    $file = $this->db->get_where($file_id, 'uploads');
    
    if ($file === false) {
        redirect('uploads/not_found');
    }
    
    // Current location
    $current_path = '../modules/uploads/incoming/' . $file->filename;
    
    if (!$this->file->exists($current_path)) {
        redirect('uploads/not_found');
    }
    
    // Organize into year/month structure
    $year_month = date('Y/m', strtotime($file->created_at));
    $organized_dir = '../modules/uploads/organized/' . $year_month;
    
    // Create directory structure if needed
    if (!$this->file->exists($organized_dir)) {
        $this->file->create_directory($organized_dir, 0755, true);
    }
    
    // Move the file
    $new_path = $organized_dir . '/' . $file->filename;
    $this->file->move($current_path, $new_path);
    
    // Update database with new path
    $data['file_path'] = $new_path;
    $this->db->update($file_id, $data, 'uploads');
    
    set_flashdata('File organized successfully');
    redirect('uploads/manage');
}

5. Reading Files

The method returns complete file contents as a string:

PHP
/**
 * @param string $file_path Path to the file
 * @return string Complete file contents
 * @throws Exception If file doesn't exist or can't be read
 */
public function read(string $file_path): string

Example: Process CSV Data

PHP
public function import_contacts($file_id): void {
    $import = $this->db->get_where($file_id, 'imports');
    
    if ($import === false) {
        redirect('imports/not_found');
    }
    
    $file_path = '../modules/imports/uploads/' . $import->filename;
    
    if (!$this->file->exists($file_path)) {
        redirect('imports/not_found');
    }
    
    // Read the CSV file
    $csv_content = $this->file->read($file_path);
    $rows = array_map('str_getcsv', explode("\n", $csv_content));
    
    // Skip header row and process
    $imported = 0;
    for ($i = 1; $i < count($rows); $i++) {
        if (count($rows[$i]) >= 3) {
            $data = [
                'name' => $rows[$i][0],
                'email' => $rows[$i][1],
                'phone' => $rows[$i][2]
            ];
            $this->db->insert($data, 'contacts');
            $imported++;
        }
    }
    
    set_flashdata("Imported $imported contacts");
    redirect('contacts/manage');
}

6. Writing Files

With the method, you can create new files or update existing ones:

PHP
/**
 * @param string $file_path Path where file should be written
 * @param mixed $data Content to write
 * @param bool $append If true, append instead of overwrite (default: false)
 * @return bool True if written successfully
 * @throws Exception If write operation fails
 */
public function write(string $file_path, $data, bool $append = false): bool

Example: Generate Export File

PHP
public function export_users(): void {
    // Get all users
    $users = $this->db->get('users', 'object');
    
    // Create CSV content
    $csv = "Name,Email,Joined\n";
    foreach ($users as $user) {
        $csv .= "{$user->name},{$user->email},{$user->created_at}\n";
    }
    
    // Write to exports directory
    $filename = 'users_export_' . date('Y-m-d_His') . '.csv';
    $file_path = '../modules/users/exports/' . $filename;
    
    $this->file->write($file_path, $csv);
    
    set_flashdata('Export file created');
    redirect('users/manage');
}

Example: Append to Log File

PHP
public function log_activity($message): void {
    $log_entry = date('[Y-m-d H:i:s] ') . $message . "\n";
    $log_path = '../modules/admin/logs/activity.log';
    
    // Append to existing log file
    $this->file->write($log_path, $log_entry, true);
}

7. Getting File Information

The method can be used to retrieve comprehensive metadata about a file:

PHP
/**
 * @param string $file_path Path to the file
 * @return array Associative array with file metadata
 * @throws Exception If file doesn't exist
 */
public function info(string $file_path): array

Returns an array containing:

  • file_name - The filename
  • size - Size in bytes
  • human_readable_size - Size formatted (e.g., "2.4 MB")
  • modified_time - Unix timestamp of last modification
  • permissions - File permissions
  • readable_permissions - Formatted permissions (e.g., "0644")
  • mime_type - MIME type of the file

Example: Display File Details

PHP
public function view_file_info($file_id): void {
    $file = $this->db->get_where($file_id, 'documents');
    
    if ($file === false) {
        redirect('documents/not_found');
    }
    
    $file_path = '../modules/documents/storage/' . $file->filename;
    
    if ($this->file->exists($file_path)) {
        $info = $this->file->info($file_path);
        
        $data['file_record'] = $file;
        $data['file_info'] = $info;
        $data['view_file'] = 'file_details';
        
        $this->view('file_details', $data);
    } else {
        redirect('documents/not_found');
    }
}

Quick Reference Table

Method Purpose Example
Check if file exists if ($this->file->exists($path))
Remove a file $this->file->delete($file_path)
Duplicate a file $this->file->copy($source, $destination)
Relocate/rename a file $this->file->move($old_path, $new_path)
Get file contents $content = $this->file->read($file_path)
Create or update file $this->file->write($path, $data)
Get file metadata $info = $this->file->info($file_path)

Common Patterns and Best Practices

Pattern 1: Store Relative Paths in Database

PHP
// During upload, store the relative path
$file_info = $this->file->upload($config);

$data['filename'] = $file_info['file_name'];
$data['file_path'] = $file_info['file_path'];  // Store the relative path
$this->db->insert($data, 'documents');

// Later, use the stored path directly
$doc = $this->db->get_where($id, 'documents');

if ($doc === false) {
    redirect('documents/not_found');
}

if ($this->file->exists($doc->file_path)) {
    $this->file->delete($doc->file_path);
    $this->db->delete($id, 'documents');
    set_flashdata('Document deleted');
    redirect('documents/manage');
} else {
    redirect('documents/not_found');
}

Pattern 2: Store Filename, Reconstruct Path

PHP
// During upload, store just the filename
$file_info = $this->file->upload($config);

$data['filename'] = $file_info['file_name'];
$this->db->insert($data, 'documents');

// Later, reconstruct the relative path
$doc = $this->db->get_where($id, 'documents');

if ($doc === false) {
    redirect('documents/not_found');
}

$file_path = '../modules/documents/storage/' . $doc->filename;

if ($this->file->exists($file_path)) {
    $this->file->delete($file_path);
    $this->db->delete($id, 'documents');
    set_flashdata('Document deleted');
    redirect('documents/manage');
} else {
    redirect('documents/not_found');
}

Pattern 3: Complete Validation Flow

PHP
public function process_file($file_id): void {
    // 1. Validate database record
    $file = $this->db->get_where($file_id, 'uploads');
    
    if ($file === false) {
        redirect('uploads/not_found');
    }
    
    // 2. Build relative file path
    $file_path = '../modules/uploads/storage/' . $file->filename;
    
    // 3. Validate file exists
    if (!$this->file->exists($file_path)) {
        redirect('uploads/not_found');
    }
    
    // 4. Now safe to perform operations
    $content = $this->file->read($file_path);
    
    // Process content...
    $processed = strtoupper($content);
    
    // Write back to file
    $this->file->write($file_path, $processed);
    
    set_flashdata('File processed successfully');
    redirect('uploads/manage');
}

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