File Handling Fundamentals
Many web applications need to work with files - whether that means accepting user uploads, processing CSV imports, storing documents, serving media assets, or managing generated files such as reports and invoices. When they do, file handling should be predictable, secure, and easy to understand.
Trongate handles file operations with zero abstraction and no unnecessary ceremony.
The Trongate Approach
No bloated file managers. No configuration-heavy services. No opaque layers that make debugging harder than it needs to be.
Instead, Trongate comes with a single, focused File module that gives you direct control over common file handling tasks.
What's Coming Up
In this chapter, you'll learn how to handle file management tasks like a pro. By the end of this chapter, you'll be able to do all of the following:
- Upload files with validation and security checks
- Manage files - delete, copy, move, rename, read, write
- Work with directories - create, list, and organize
- Protect downloads - prevent traversal and unauthorized access
Everything is built using Native PHP, so what you see is exactly what runs.
Your Swiss Army Knife: The File Module
All file management operations in Trongate are handled by the File module - a module that can be called from any controller using the syntax $this->file.
The pattern is intentionally simple: $this->file->method(). No service containers. No dependency injection. No additional setup.
The method, within the File module, is used for merely uploading of files. In the strictest sense this means, "moving a file from 'point A' to 'point B'.
This is important because picture uploading usually requires some kind of processing - such as resizing. For this reason, it's advisible to not use the File module for uploading of pictures.
For picture uploading, use the Image module.
A Simple Upload Flow
File uploads in Trongate follow a clear, three-step pattern that mirrors how real applications are built:
Each method does one thing. There is no shared state, no hidden behavior, and no guesswork.
How This Differs From Other Frameworks
| Typical frameworks | Trongate |
|---|---|
| Layered upload services with complex APIs | A single upload() call with clear parameters |
| Separate validation and file handling systems | Validation works seamlessly with files |
| External packages for basic file operations | Everything included out of the box |
| Abstracted file systems that hide behavior | Direct, readable PHP code |
| Over-engineered exception hierarchies | Clear errors and predictable outcomes |
Security Built In
File handling is a common attack surface, so Trongate applies security checks automatically:
- Path validation to prevent directory traversal
- MIME verification to confirm file types
- Content inspection to detect malicious payloads
- File size limits enforced per upload
There is nothing to enable and no security plumbing to wire up. Safe defaults are applied automatically, and you remain fully in control through explicit, readable configuration — no hidden behavior, no guesswork.
What’s Next
The following page walks through the simplest possible file uploader, using production-ready code you can apply immediately. You will learn:
- How to build an upload form with correct encoding
- How file validation integrates with the validation module
- How to handle success and failure cleanly
- How to present uploaded files to users