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:
- - Creates directories with specified permissions.
- - 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):
| Permission | Value | Description |
|---|---|---|
| Read | 4 | Allows listing the contents of the directory (e.g., seeing file names with ls). |
| Write | 2 | Allows creating, deleting, or renaming files inside the directory. |
| Execute | 1 | Allows entering the directory (cd into it) and accessing files/subdirectories inside (traversing the directory). |
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
cdand most operations inside). - On files: Allows running the file as a program/script.
0755 for directories and 0644 for files.
The Full Octal Code: Owner, Group, and Others
We combine three (or four) digits to set permissions separately for the owner, group, and others:
Security Warning: Never use 0777 in a production environment. This gives everyone on the server full read/write/execute access to your files and directories, creating a major security risk. Stick to 0755 for directories and 0644 for files in most cases.
Creating Directories
The method ensures your target folder exists and applies your chosen permissions.
Listing Directories
The method returns an associative array containing two keys: directories and files.
Example: File Browser View
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:
The "Check Before You Act" Pattern
Professional file management relies on defensive programming. You should never assume a directory exists just because you created it earlier in the script. Server configurations, automated cleanup tasks, or manual changes by an administrator can remove directories without warning.
Always verify existence using immediately before performing operations like listing files or uploading data. This ensures your application can handle missing paths gracefully - perhaps by recreating them or showing a helpful message - rather than crashing with a fatal system error.