Directory Management

Directories are the foundation of a clean and organized file system. Trongate's File module provides a streamlined interface for managing folders, handling path validation and recursive creation automatically.

The Two Core Methods

All directory operations are accessed via $this->file from within your controllers:

• included-file-create_directory() - Creates directories with specified permissions.
• included-file-list_directory() - Returns a structured array of files and subdirectories.

Understanding Directory Permissions

Permissions control who can read, write, or enter your directories. In a web environment, your PHP code typically runs as the www-data or apache user. If this user does not have the correct permissions, your application will fail.

Understanding Octal Permissions: Read (4) + Write (2) + Execute (1)

Unix/Linux file permissions are represented numerically in octal format. Each permission level is calculated by adding three base values to create a single digit (0–7):

By adding these values together, you determine the permission level for a category. Common examples:

• 4 (Read) + 1 (Execute) = 5 - Can list contents and enter the directory, but cannot modify anything.
• 4 (Read) + 2 (Write) + 1 (Execute) = 7 - Full control (read, write, and execute).
• 4 (Read) + 2 (Write) = 6 - Can read and modify contents, but not execute/traverse.

Note: The meaning of "execute" differs slightly between files and directories:

• On directories: Allows traversal and access to contents (required for cd and most operations inside).
• On files: Allows running the file as a program/script.

The Full Octal Code: Owner, Group, and Others

We combine three (or four) digits to set permissions separately for the owner, group, and others:

0755
 │││
 ││└─ Others (everyone else on the server): 5 → Read + Execute
 │└── Group (users in the same group): 5 → Read + Execute
 └─── Owner (you or the web server/PHP process): 7 → Full access (Read + Write + Execute)

Creating Directories

The included-file-create_directory() method ensures your target folder exists and applies your chosen permissions.

// Create a directory inside modules/your_module/uploads
$this->file->create_directory('uploads');

// Create nested directories (e.g., uploads/2024/05)
$this->file->create_directory('uploads/2024/05', 0755, true);

Listing Directories

The included-file-list_directory() method returns a flat array of filenames. With the optional $recursive parameter set to true, subdirectories appear as keys containing their own nested arrays.

// Non-recursive: flat array of filenames
$contents = $this->file->list_directory('uploads');

/*
$contents structure (non-recursive):
[
    'report.pdf',
    'invoice_2024.csv',
    'avatars',       // directories are just names in the flat list
    'profile.jpg'
]
*/

// Recursive: subdirectories become keys
$all = $this->file->list_directory('uploads', true);

/*
$all structure (recursive):
[
    'report.pdf',
    'invoice_2024.csv',
    'avatars' => [
        'user_1.jpg',
        'user_2.jpg'
    ],
    'profile.jpg'
]
*/

Example: Iterating the Results

$items = $this->file->list_directory('uploads');

foreach ($items as $key => $value) {
    if (is_array($value)) {
        // $key is a subdirectory name, $value is its file list
        echo 'Directory: ' . out($key) . '';
        foreach ($value as $file) {
            echo '- ' . out($file) . '';
        }
    } else {
        // $value is a filename
        echo out($value) . '';
    }
}

Deleting Directories

The included-file-delete_directory() method recursively removes a directory and all of its contents - files, subdirectories, everything.

// Remove a temporary processing directory
$this->file->delete_directory('temp/import_67f3a2');

// Check existence first, then delete
if ($this->file->exists('old_backups/january')) {
    $this->file->delete_directory('old_backups/january');
}

There is no “empty directory” requirement - included-file-delete_directory() handles all contents recursively. If you only need to clear a directory without removing the directory itself, use included-file-list_directory() with a loop of included-file-delete() calls instead.

Troubleshooting Ownership

If your code has 0755 permissions but still fails, the directory is likely owned by root instead of the web server. You can fix this via the terminal:

# Give ownership to the web server user
sudo chown -R www-data:www-data modules/your_module/uploads