File Operations API

This document describes the GraphQL mutations and supporting infrastructure for file and folder operations provided by FileSystemController. These operations enable creation, deletion, renaming, moving, and uploading of files and folders across any configured storage backend.

For information about the underlying Node types and their properties, see Node Types (File and Folder). For storage backend configuration, see Storage Backends. For managing filesystem drives themselves, see Drive Management.

---

GraphQL Mutations Overview

The FileSystemController exposes the following GraphQL mutations for file operations:

Mutation Name	Permission Required	Purpose
lightFSCreateFolder	fs.folder:create	Create a new folder at specified location
lightFSDeleteFolder	fs.folder:delete	Delete a folder and its contents
lightFSRenameFolder	fs.folder:rename	Rename an existing folder
lightFSWriteFile	fs.file:write	Write content to a file (create or overwrite)
lightFSDeleteFile	fs.file:delete	Delete a file
lightFSRenameFile	fs.file:rename	Rename an existing file
lightFSMove	fs.node:move	Move a file or folder to a different location
lightFSUploadBase64	fs.file:write	Upload file from base64-encoded content
lightFSUploadFile	fs.file:write	Upload file from multipart form data

All mutations are protected by RBAC permissions via the @Right annotation. See Permission Checking for details on authorization flow.

Sources: src/Controller/FileSystemController.php36-262

---

Operation Flow Architecture

The following diagram shows how file operations flow through the system layers:

Sources: src/Controller/FileSystemController.php36-51

---

Folder Operations

Creating Folders

The createFolder mutation creates a new directory at the specified location.

GraphQL Signature:

Implementation Details:

• Location format: "drive://path/to/folder" (e.g., "local://uploads/images")
• Dispatches FolderCreating event before creation
• Event allows modification of target location
• Returns true on success

Validation:

• Folder name cannot start with a dot (.)
• Parent directory must exist

Sources: src/Controller/FileSystemController.php36-51

Deleting Folders

The deleteFolder mutation recursively deletes a directory and all its contents.

GraphQL Signature:

Implementation Details:

• Dispatches FolderDeleting event before deletion
• Recursively removes all files and subdirectories
• Returns true on success

Validation:

• Folder name cannot start with a dot (.)
• Location must exist and be a directory

Sources: src/Controller/FileSystemController.php53-68

Renaming Folders

The renameFolder mutation renames a folder in place.

GraphQL Signature:

Implementation Details:

• Constructs new location: dirname(location) + "/" + newName
• Dispatches FolderRenaming event with both location and new name
• Uses MountManager::move() to perform rename operation
• Handles edge case where dirname ends with : (root of drive)

Validation:

• New name cannot start with a dot (.)
• New name must not conflict with existing folder

Sources: src/Controller/FileSystemController.php70-91

---

File Operations

Writing Files

The writeFile mutation creates a new file or overwrites an existing file with the provided content.

GraphQL Signature:

Implementation Details:

• Content is written as UTF-8 string
• Dispatches FileWriting event with location and content
• Event allows modification of both location and content before writing
• Returns true on success

Validation:

• File name cannot start with a dot (.)
• No extension validation (use upload methods for extension checks)

Sources: src/Controller/FileSystemController.php93-108

Deleting Files

The deleteFile mutation removes a file from the filesystem.

GraphQL Signature:

Implementation Details:

• Dispatches FileDeleting event before deletion
• Returns true on success
• Does not fail if file doesn't exist (idempotent)

Validation:

• File name cannot start with a dot (.)

Sources: src/Controller/FileSystemController.php110-125

Renaming Files

The renameFile mutation renames a file, optionally changing its extension.

GraphQL Signature:

Implementation Details:

• Constructs new location: dirname(location) + "/" + newName
• Dispatches FileRenaming event with both location and new name
• Uses MountManager::move() to perform rename operation
• Extension is validated against blacklist

Validation:

• New name cannot start with a dot (.)
• Extension must not be in DISALLOW_EXT list
• New name must not conflict with existing file

Sources: src/Controller/FileSystemController.php127-155

---

Node Move Operation

The moveNode mutation moves a file or folder to a different location, potentially across filesystems.

GraphQL Signature:

Implementation Details:

• Automatically appends source basename to target if target ends with /
• Example: moving "local://file.txt" to "s3://backup/" results in "s3://backup/file.txt"
• Dispatches NodeMoving event with from and to locations
• Supports cross-filesystem moves (e.g., local to S3)
• Returns true on success

Validation:

• Source name cannot start with a dot (.)
• Target directory must exist
• Source must exist

Exception Handling:

• Catches all exceptions and re-throws as GraphQL errors
• Common errors: source not found, target already exists, permission denied

Sources: src/Controller/FileSystemController.php157-186

---

Upload Operations

Upload Operation Comparison

Feature	uploadBase64	uploadFile
Input Format	Base64 string	Multipart form data
Data URI Support	Yes (strips header)	No
File Size Limit	Memory limit	PHP upload limit
Return Type	File object	Boolean
Rename on Conflict	No (overwrites)	Optional parameter
Use Case	Small files, inline data	Large files, browser uploads

Base64 Upload

The uploadBase64 mutation uploads a file from base64-encoded content.

GraphQL Signature:

Implementation Details:

1. Accepts full Data URI (e.g., "data:image/png;base64,iVBOR...") or raw base64
2. Strips Data URI header if present (splits on ,)
3. Decodes base64 to binary string using base64_decode($data, true)
4. Validates decoded content (fails if base64 is invalid)
5. Dispatches FileUploading event with location and filename
6. Writes binary content to filesystem
7. Returns File object representing uploaded file

Validation:

• Extension must not be in DISALLOW_EXT list (60+ blocked extensions)
• File name cannot start with a dot (.)
• Base64 string must be valid

Error Cases:

• "Invalid base64 string provided." if decode fails
• "File type not allowed" if extension is blacklisted
• "File name cannot start with a dot" if hidden file

Sources: src/Controller/FileSystemController.php189-229

Multipart File Upload

The uploadFile mutation uploads a file from HTTP multipart form data.

GraphQL Signature:

Implementation Details:

1. Extracts original filename from UploadedFileInterface
2. Constructs target location: location + "/" + filename
3. Checks if file already exists at target
4. If exists and rename=true: generates unique filename using pattern "name (n).ext"
5. If exists and rename=false: throws error
6. Dispatches FileUploading event
7. Writes stream contents to filesystem
8. Returns true on success

Auto-Rename Logic:

Original: "document.pdf"
If exists: "document (1).pdf"
If exists: "document (2).pdf"
... continues incrementing until unique name found

Validation:

• Extension must not be in DISALLOW_EXT list
• File must be uploaded via proper multipart request

Error Cases:

• "File type not allowed" if extension is blacklisted
• "File already exists" if conflict and rename=false

Sources: src/Controller/FileSystemController.php231-275

---

Security Validation

Extension Blacklist

The FileSystemController::DISALLOW_EXT constant defines 60+ file extensions that are blocked for security reasons:

Blocked Extensions (partial list):

• Executable: exe, application, gadget, hta, cpl, msc, jar
• Scripts: php, php3-5, phps, phtml, js, jsp, py, pl, sh, cgi
• System: dll, msi, vbs, bat, com, pif, cmd, vxd, scr
• Web: mhtml, mht, xhtml, jhtml, shtml
• Config: htpasswd, htaccess, inf, reg, scf
• Archives: zip (due to zip slip vulnerabilities)

Implementation:

Sources: src/Controller/FileSystemController.php34 src/Controller/FileSystemController.php134-136 src/Controller/FileSystemController.php194-195 src/Controller/FileSystemController.php239-240

Hidden File Protection

All file and folder operations validate against hidden files (names starting with .):

Operation	Validation Point	Error Message
Create Folder	Basename of location	"Folder name cannot start with a dot"
Delete Folder	Basename of location	"Folder name cannot start with a dot"
Rename Folder	New name parameter	"Folder name cannot start with a dot"
Write File	Basename of location	"File name cannot start with a dot"
Delete File	Basename of location	"File name cannot start with a dot"
Rename File	New name parameter	"File name cannot start with a dot"
Move Node	Basename of source	"File/Folder name cannot start with a dot"
Upload Base64	Basename of location	"File name cannot start with a dot"

Implementation Pattern:

Rationale:

• Prevents manipulation of system files (.htaccess, .env, etc.)
• Blocks creation of hidden files that could bypass security scans
• Protects against directory traversal attempts using . and ..

Sources: src/Controller/FileSystemController.php40-45 src/Controller/FileSystemController.php98-102 src/Controller/FileSystemController.php138-141 src/Controller/FileSystemController.php197-201

---

Event System

The file operations API uses an event-driven architecture that allows pre-operation validation, logging, and modification of parameters.

Event Flow Diagram

Available Events

Event Class	Dispatched By	Mutable Properties	Use Cases
FolderCreating	createFolder	location	Modify target path, prevent creation
FolderDeleting	deleteFolder	location	Audit logging, prevent deletion
FolderRenaming	renameFolder	location, newName	Validate names, modify target
FileWriting	writeFile	location, content	Content filtering, virus scan
FileDeleting	deleteFile	location	Audit logging, prevent deletion
FileRenaming	renameFile	location, newName	Validate names, modify target
NodeMoving	moveNode	from, to	Prevent cross-filesystem moves
FileUploading	uploadBase64, uploadFile	location, filename	Virus scanning, quota checks

Event Usage Pattern

Dispatching Events:

Event Listener Example:

Event Registration: Events are dispatched through App::eventDispatcher() which returns a PSR-14 compatible event dispatcher. Listeners must be registered during application initialization via the container or event dispatcher configuration.

Sources: src/Controller/FileSystemController.php47-49 src/Controller/FileSystemController.php104-106 src/Controller/FileSystemController.php143-144 src/Controller/FileSystemController.php220-221 src/Controller/FileSystemController.php255-256

---

Error Handling

Error Types and Codes

Exception Handling Patterns

Validation Errors (thrown explicitly):

Filesystem Errors (caught and wrapped):

Authorization Errors:

• Handled by GraphQLite's @Right annotation
• No explicit exception thrown in controller
• Returns standard GraphQL authorization error

Response Format

All mutations return either:

• Boolean success indicator (true on success)
• File object (for uploadBase64)
• GraphQL error object with message field

Success Response:

Error Response:

Sources: src/Controller/FileSystemController.php44 src/Controller/FileSystemController.php134-136 src/Controller/FileSystemController.php179-183 src/Controller/FileSystemController.php195 src/Controller/FileSystemController.php216-218 src/Controller/FileSystemController.php240 src/Controller/FileSystemController.php251

---

Integration with Other Components

Dependency Injection

All methods use parameter-level injection via the #[Autowire] attribute from GraphQLite:

Injected Service	Type	Purpose	Example Line
App	Light\App	Access to event dispatcher and mount manager	Line 38, 55, 72, 95, etc.
MountManager	League\Flysystem\MountManager	Direct filesystem operations	Line 72, 95, 112, 129, etc.

Pattern Used:

The #[Autowire] attribute tells GraphQLite to inject these dependencies from the DI container rather than requiring them as GraphQL arguments.

Sources: src/Controller/FileSystemController.php29 src/Controller/FileSystemController.php38 src/Controller/FileSystemController.php72 src/Controller/FileSystemController.php95

RBAC Integration

All mutations require specific permissions enforced via #[Right] annotations:

Permission Hierarchy:

• fs.folder:create, fs.folder:delete, fs.folder:rename - Folder operations
• fs.file:write, fs.file:delete, fs.file:rename - File operations
• fs.node:move - Move any node type

See Permission Checking for details on the authorization flow.

Sources: src/Controller/FileSystemController.php37 src/Controller/FileSystemController.php54 src/Controller/FileSystemController.php94 src/Controller/FileSystemController.php190 src/Controller/FileSystemController.php232

MountManager Integration

All operations use League\Flysystem\MountManager for backend-agnostic filesystem access:

Common Operations:

• createDirectory($location) - Create folder
• deleteDirectory($location) - Delete folder recursively
• write($location, $content) - Write file
• delete($location) - Delete file
• move($from, $to) - Move/rename node
• fileExists($location) - Check existence

See Storage Backends for information on how MountManager coordinates multiple storage systems.

Sources: src/Controller/FileSystemController.php49 src/Controller/FileSystemController.php106 src/Controller/FileSystemController.php123 src/Controller/FileSystemController.php153 src/Controller/FileSystemController.php180 src/Controller/FileSystemController.php225 src/Controller/FileSystemController.php259

---

Full Sources for This Document: src/Controller/FileSystemController.php1-364