VOOZH about

URL: https://deepwiki.com/mathsgod/light/4.3.3-filesystemcontroller

⇱ FileSystemController | mathsgod/light | DeepWiki

Loading...
Loading...
Last indexed: 31 January 2026 (cf9511)
Menu

FileSystemController

Purpose and Scope

The FileSystemController class provides GraphQL mutations for performing file system operations across multiple storage backends. It serves as the primary API interface for creating, deleting, renaming, and moving files and folders, as well as uploading files and managing filesystem configurations.

This document covers the file and folder operation mutations, upload mechanisms, security validation, event dispatching, and filesystem configuration CRUD operations. For details on the underlying filesystem architecture and MountManager pattern, see Filesystem Architecture. For information about File and Folder node types, see Node Types. For storage backend configuration details, see Storage Backends.

Sources: src/Controller/FileSystemController.php1-364

Overview

The FileSystemController exposes 13 GraphQL operations organized into five functional categories:

CategoryOperationsPermission Required
Folder OperationslightFSCreateFolder, lightFSDeleteFolder, lightFSRenameFolderfs.folder:create, fs.folder:delete, fs.folder:rename
File OperationslightFSWriteFile, lightFSDeleteFile, lightFSRenameFilefs.file:write, fs.file:delete, fs.file:rename
Move OperationslightFSMovefs.node:move
Upload OperationslightFSUploadFile, lightFSUploadBase64fs.file:write
Configuration ManagementlightFSadd, lightFSupdate, lightFSdelete, listFileSystemfilesystem.add, filesystem.update, filesystem.delete, filesystem.list

All operations are protected by @Right annotations that enforce role-based access control. Each operation validates inputs, dispatches pre-operation events for extensibility, and executes the operation through the Flysystem MountManager.

Sources: src/Controller/FileSystemController.php31-364

Architecture Diagram



Sources: src/Controller/FileSystemController.php1-364




Folder Operations


lightFSCreateFolder


Creates a new folder at the specified location.


GraphQL Signature:




Parameters:


    

  • location: Flysystem location string (e.g., "s3://bucket/path/newfolder")
    • 



Permission: fs.folder:create


Validation:


    

  1. Basename cannot start with a dot (prevents hidden folders)
    2. 



Event: Dispatches FolderCreating event before creation, allowing listeners to modify the location or perform additional validation.


Implementation: src/Controller/FileSystemController.php36-51




Sources: src/Controller/FileSystemController.php36-51




lightFSDeleteFolder


Deletes a folder at the specified location.


GraphQL Signature:




Permission: fs.folder:delete


Validation:


    

  1. Basename cannot start with a dot
    2. 



Event: Dispatches FolderDeleting event before deletion.


Implementation: src/Controller/FileSystemController.php53-68


Sources: src/Controller/FileSystemController.php53-68




lightFSRenameFolder


Renames a folder by moving it to a new path with the new name.


GraphQL Signature:




Parameters:


    

  • location: Current folder location
    • 

  • newName: New folder name (basename only, not full path)
    • 



Permission: fs.folder:rename


Validation:


    

  1. New name cannot start with a dot
    2. 



Event: Dispatches FolderRenaming event before rename operation.


Implementation Details:


    

  • Extracts dirname from current location using pathinfo()
    • 

  • Handles special case where dirname ends with : (root of a mount) by appending /
    • 

  • Constructs new location as dirname/newName
    • 

  • Uses MountManager->move() to perform the rename
    • 



Implementation: src/Controller/FileSystemController.php70-91


Sources: src/Controller/FileSystemController.php70-91




File Operations


lightFSWriteFile


Writes content to a file at the specified location, creating it if it doesn't exist or overwriting it if it does.


GraphQL Signature:




Permission: fs.file:write


Validation:


    

  1. Basename cannot start with a dot
    2. 



Event: Dispatches FileWriting event with location and content, allowing modification before write.


Implementation: src/Controller/FileSystemController.php93-108


Sources: src/Controller/FileSystemController.php93-108




lightFSDeleteFile


Deletes a file at the specified location.


GraphQL Signature:




Permission: fs.file:delete


Validation:


    

  1. Basename cannot start with a dot
    2. 



Event: Dispatches FileDeleting event before deletion.


Implementation: src/Controller/FileSystemController.php110-125


Sources: src/Controller/FileSystemController.php110-125




lightFSRenameFile


Renames a file by moving it to a new path with the new name.


GraphQL Signature:




Parameters:


    

  • location: Current file location
    • 

  • newName: New filename including extension
    • 



Permission: fs.file:rename


Validation:


    

  1. New name extension must not be in DISALLOW_EXT array
    2. 

  2. New name cannot start with a dot
    3. 



Event: Dispatches FileRenaming event before rename operation.


Implementation: src/Controller/FileSystemController.php127-155


Sources: src/Controller/FileSystemController.php127-155




Move Operations


lightFSMove


Moves a file or folder from one location to another, potentially across different filesystems (if supported by the storage backend).


GraphQL Signature:




Parameters:


    

  • from: Source location
    • 

  • to: Destination directory path
    • 



Permission: fs.node:move


Behavior:


    

  • Automatically appends the source basename to the destination path
    • 

  • If to ends with /, appends basename directly
    • 

  • Otherwise, appends / then basename
    • 



Validation:


    

  1. Source basename cannot start with a dot
    2. 



Event: Dispatches NodeMoving event with from and computed to paths.


Error Handling: Catches exceptions from MountManager->move() and converts them to GraphQL errors.


Implementation: src/Controller/FileSystemController.php157-186




Sources: src/Controller/FileSystemController.php157-186




Upload Operations


lightFSUploadFile


Uploads a file via GraphQL multipart upload (PSR-7 UploadedFileInterface).


GraphQL Signature:




Parameters:


    

  • location: Destination directory path
    • 

  • file: Uploaded file (handled by GraphQL upload middleware)
    • 

  • rename: If true, automatically renames file if it exists (appends (1), (2), etc.)
    • 



Permission: fs.file:write


Validation:


    

  1. File extension must not be in DISALLOW_EXT array
    2. 



Behavior:


    

  • Extracts filename from uploaded file's getClientFilename()
    • 

  • Appends filename to location path
    • 

  • If file exists and rename=false, throws error
    • 

  • If file exists and rename=true, calls getNextFilename() to generate unique name
    • 

  • getNextFilename() appends (1), (2), etc. until a non-existent filename is found
    • 



Event: Dispatches FileUploading event with location and filename.


Implementation: src/Controller/FileSystemController.php231-275


Sources: src/Controller/FileSystemController.php231-275




lightFSUploadBase64


Uploads a file by decoding base64-encoded content.


GraphQL Signature:




Parameters:


    

  • location: Full destination path including filename
    • 

  • base64: Base64-encoded file content (supports Data URI format with prefix)
    • 



Returns: File object representing the uploaded file


Permission: fs.file:write


Validation:


    

  1. File extension must not be in DISALLOW_EXT array
    2. 

  2. Basename cannot start with a dot
    3. 

  3. Base64 string must be valid
    4. 



Data URI Handling:


    

  • Supports full Data URI format: data:image/png;base64,iVBORw0KGgo...
    • 

  • If comma is present, extracts content after the comma
    • 

  • Otherwise, treats entire string as base64 data
    • 



Event: Dispatches FileUploading event with location and basename.


Implementation: src/Controller/FileSystemController.php189-229




Sources: src/Controller/FileSystemController.php189-229




Filesystem Configuration Management


The controller provides CRUD operations for managing filesystem configurations stored in the Config model with name="fs". Each filesystem configuration is stored as a JSON object in an array, with a UUID for identification.


Configuration Structure


Filesystem configurations are stored in Config model with:


    

  • name: "fs"
    • 

  • value: JSON array of filesystem objects
    • 



Each filesystem object contains:


    

  • uuid: Unique identifier (auto-generated on creation)
    • 

  • Storage backend configuration (credentials, endpoints, etc.)
    • 



Sources: src/Controller/FileSystemController.php278-363




lightFSadd


Adds a new filesystem configuration.


GraphQL Signature:




Permission: filesystem.add


Behavior:


    

  1. Retrieves or creates Config with name="fs"
    2. 

  2. Decodes existing JSON array
    3. 

  3. Generates new UUID for the configuration
    4. 

  4. Appends configuration to array
    5. 

  5. Encodes array with JSON_UNESCAPED_UNICODE flag
    6. 

  6. Saves to database
    7. 



Implementation: src/Controller/FileSystemController.php313-331


Sources: src/Controller/FileSystemController.php313-331




lightFSupdate


Updates an existing filesystem configuration by UUID.


GraphQL Signature:




Parameters:


    

  • data: Object containing uuid field and updated configuration
    • 



Permission: filesystem.update


Behavior:


    

  1. Retrieves Config with name="fs"
    2. 

  2. Decodes JSON array
    3. 

  3. Iterates to find configuration with matching uuid
    4. 

  4. Replaces configuration object
    5. 

  5. Re-encodes and saves
    6. 



Returns: false if config doesn't exist or UUID not found


Implementation: src/Controller/FileSystemController.php278-308


Sources: src/Controller/FileSystemController.php278-308




lightFSdelete


Deletes a filesystem configuration by UUID.


GraphQL Signature:




Permission: filesystem.delete


Behavior:


    

  1. Retrieves Config with name="fs"
    2. 

  2. Decodes JSON array
    3. 

  3. Filters out configuration with matching uuid
    4. 

  4. Re-encodes filtered array and saves
    5. 



Implementation: src/Controller/FileSystemController.php346-363


Sources: src/Controller/FileSystemController.php346-363




listFileSystem


Queries all filesystem configurations.


GraphQL Signature:




Permission: filesystem.list


Returns: Array of filesystem configuration objects


Deprecation: This query is deprecated. Use app { listFileSystem } instead (see Root Query Type).


Implementation: src/Controller/FileSystemController.php333-344


Sources: src/Controller/FileSystemController.php333-344




Security Features


Extension Blacklist


The controller maintains a constant DISALLOW_EXT containing 65 prohibited file extensions to prevent upload of potentially dangerous files.


Blacklisted Extensions:




Enforcement: Checked in lightFSRenameFile(), lightFSUploadFile(), and lightFSUploadBase64() before file operations.


Implementation: src/Controller/FileSystemController.php34


Sources: src/Controller/FileSystemController.php34




Hidden File Prevention


All operations validate that file and folder basenames do not start with a dot (.), preventing creation or manipulation of hidden files that could be used for attacks.


Validation Pattern:




Enforced In:


    

  • All folder operations
    • 

  • All file operations
    • 

  • All upload operations
    • 



Rationale: Hidden files (dot-prefixed) can be used to store malicious configuration files (.htaccess, .env) or bypass security restrictions.


Sources: src/Controller/FileSystemController.php40-45 src/Controller/FileSystemController.php97-102 src/Controller/FileSystemController.php197-201




Permission-Based Authorization


Every operation is protected by @Right annotations enforcing granular permissions:























































PermissionOperations
fs.folder:createCreating folders
fs.folder:deleteDeleting folders
fs.folder:renameRenaming folders
fs.file:writeWriting, uploading files
fs.file:deleteDeleting files
fs.file:renameRenaming files
fs.node:moveMoving files or folders
filesystem.addAdding filesystem configs
filesystem.updateUpdating filesystem configs
filesystem.deleteDeleting filesystem configs
filesystem.listListing filesystem configs


Sources: src/Controller/FileSystemController.php37 src/Controller/FileSystemController.php54 src/Controller/FileSystemController.php71 src/Controller/FileSystemController.php94 src/Controller/FileSystemController.php111 src/Controller/FileSystemController.php128 src/Controller/FileSystemController.php158 src/Controller/FileSystemController.php190 src/Controller/FileSystemController.php232 src/Controller/FileSystemController.php279 src/Controller/FileSystemController.php314 src/Controller/FileSystemController.php334 src/Controller/FileSystemController.php347




Event System


Before executing each file system operation, the controller dispatches events through App->eventDispatcher(). Event listeners can:


    

  • Modify operation parameters (location, content, filename)
    • 

  • Perform additional validation
    • 

  • Execute side effects (logging, notifications)
    • 

  • Cancel operations by throwing exceptions
    • 



Event Classes


All events are located in the Light\Filesystem\Event namespace:




















































Event ClassDispatched ByModifiable Properties
FolderCreatinglightFSCreateFolder()location
FolderDeletinglightFSDeleteFolder()location
FolderRenaminglightFSRenameFolder()location, newName
FileWritinglightFSWriteFile()location, content
FileDeletinglightFSDeleteFile()location
FileRenaminglightFSRenameFile()location, newName
NodeMovinglightFSMove()from, to
FileUploadinglightFSUploadFile(), lightFSUploadBase64()location, filename


Sources: src/Controller/FileSystemController.php10-17 src/Controller/FileSystemController.php48 src/Controller/FileSystemController.php65 src/Controller/FileSystemController.php80 src/Controller/FileSystemController.php105 src/Controller/FileSystemController.php122 src/Controller/FileSystemController.php144 src/Controller/FileSystemController.php177 src/Controller/FileSystemController.php221 src/Controller/FileSystemController.php256




Event Dispatch Pattern




Example Usage:




Event listeners can modify the $event->location or $event->content properties, and the controller uses the modified values.


Sources: src/Controller/FileSystemController.php48-49 src/Controller/FileSystemController.php105-106 src/Controller/FileSystemController.php177-180