Last indexed: 31 January 2026 (cf9511)

Node Types (File and Folder)

Purpose and Scope

This document describes the Node interface and its two implementations: File and Folder classes. These classes provide a unified abstraction for filesystem entities, enabling polymorphic operations across files and directories regardless of the underlying storage backend. For information about the filesystem architecture and MountManager pattern, see 7.1. For storage backend configuration, see 7.3.

The Node abstraction allows GraphQL clients to query filesystem hierarchies without knowledge of whether a given path refers to a file or directory. All node types expose common properties (name, path, lastModified, location) while providing type-specific operations through the GraphQL union type system.

Node Interface

The Node interface defines the common contract that all filesystem entities must implement. It is declared at src/Filesystem/Node/Node.php10-24 and marked with the GraphQLite #[Type()] attribute to expose it as a GraphQL interface type.

Common Fields

All Node implementations must provide four fields:

Field	Return Type	Description
`getName()`	`string`	Base name without directory path
`getPath()`	`string`	Relative path excluding scheme prefix
`getLastModified()`	`int`	Unix timestamp of last modification
`getLocation()`	`string`	Full location string with scheme

Each method is annotated with #[Field()] for GraphQL exposure. The getLastModified() method accepts the MountManager via dependency injection using #[Autowire], allowing the implementation to query the underlying filesystem.

Sources: src/Filesystem/Node/Node.php10-24

File Class

The File class represents individual files and is implemented at src/Filesystem/Node/File.php12-97 It provides access to file content, metadata, and public URLs.

Class Structure

Sources: src/Filesystem/Node/Node.php10-24 src/Filesystem/Node/File.php12-97 src/Filesystem/Node/Folder.php12-95

Constructor and Metadata

The File constructor accepts a location string and optional metadata array src/Filesystem/Node/File.php16-21:

The metadata parameter allows pre-fetched filesystem attributes to be cached, avoiding redundant calls to the MountManager. When listing directory contents, the system populates this array with size and last_modified values obtained during the initial scan src/Type/Filesystem.php167-170

Location and Path Methods

getLocation() returns the full location string including the scheme prefix src/Filesystem/Node/File.php41-45:

Example: "s3://uploads/documents/report.pdf"

getPath() extracts the relative path by removing the scheme prefix src/Filesystem/Node/File.php29-39:

Result: "uploads/documents/report.pdf"

getName() returns only the filename using basename() src/Filesystem/Node/File.php23-27:

Result: "report.pdf"

Sources: src/Filesystem/Node/File.php23-45

Content Access

The File class provides multiple methods for retrieving file content:

Method	Description	Implementation
`getContent()`	Returns raw file content as string	`$mountManager->read($this->location)`
`getBase64Content()`	Returns base64-encoded content	`base64_encode($this->getContent())`

The getContent() method is implemented at src/Filesystem/Node/File.php56-60 and delegates directly to the MountManager. The getBase64Content() method at src/Filesystem/Node/File.php92-96 wraps the content in base64 encoding, useful for transferring binary files through GraphQL JSON responses.

Sources: src/Filesystem/Node/File.php56-96

Metadata Retrieval

File metadata is retrieved through the MountManager with caching support:

getSize() src/Filesystem/Node/File.php47-54 returns file size in bytes. If metadata['size'] was provided in the constructor, it returns the cached value; otherwise, it calls $mountManager->fileSize().

getLastModified() src/Filesystem/Node/File.php62-69 returns the Unix timestamp of the last modification. It checks for a cached metadata['last_modified'] value before querying the MountManager.

getMimeType() src/Filesystem/Node/File.php71-79 attempts to detect the MIME type via $mountManager->mimeType(). If detection fails, it returns the fallback value 'application/octet-stream'.

Sources: src/Filesystem/Node/File.php47-79

Public URL Generation

The getPublicUrl() method src/Filesystem/Node/File.php81-89 generates a publicly accessible URL for the file:

This method first attempts to retrieve a native public URL from the storage backend (e.g., S3 pre-signed URLs). If the backend does not support public URLs or an error occurs, it falls back to constructing a path through the application's upload endpoint at /api/uploads/.

Sources: src/Filesystem/Node/File.php81-89

Folder Class

The Folder class represents directories and is implemented at src/Filesystem/Node/Folder.php12-95 It provides directory traversal capabilities and recursive size calculation.

Constructor

The constructor mirrors the File class structure src/Filesystem/Node/Folder.php14-17:

The optional metadata array can cache last_modified timestamps to reduce filesystem queries during bulk operations.

Sources: src/Filesystem/Node/Folder.php14-17

Path Methods

getLocation() src/Filesystem/Node/Folder.php45-48 returns the full location string:

Example: "local://uploads/documents/"

getPath() src/Filesystem/Node/Folder.php39-43 extracts the relative path by splitting on :// and removing leading slashes:

getName() src/Filesystem/Node/Folder.php32-37 returns the directory name by removing trailing slashes before applying basename():

Sources: src/Filesystem/Node/Folder.php32-48

Directory Traversal

The getChildren() method src/Filesystem/Node/Folder.php55-85 returns an array of Node objects representing the folder's immediate children (non-recursive):

The method performs the following steps:

Calls $mountManager->listContents($this->location, false) to get immediate children (the false parameter disables recursion)
Iterates over each FileAttributes or DirectoryAttributes object
Filters out hidden files by checking if the basename starts with . src/Filesystem/Node/Folder.php67-69
Instantiates either a Folder or File object based on the attribute type
Populates the metadata array with cached size and last_modified values src/Filesystem/Node/Folder.php72-80

This approach minimizes filesystem queries by caching metadata during the initial directory listing operation.

Sources: src/Filesystem/Node/Folder.php55-85

Size Calculation

The getTotalSize() method src/Filesystem/Node/Folder.php20-30 calculates the cumulative size of all files within the folder recursively:

Key implementation details:

Uses listContents(..., true) with the recursive flag enabled to traverse subdirectories
Filters for FileAttributes instances (ignoring directory entries)
Accumulates the fileSize() of each file
Returns the total size in bytes

This operation can be expensive for large directory trees, as it must query metadata for every file in the hierarchy.

Sources: src/Filesystem/Node/Folder.php20-30

Location String Format

All Node objects use location strings that follow the scheme-based format established by Flysystem's MountManager:

<filesystem_name>://<path>

Examples:

local://uploads/images/logo.png
s3://documents/contracts/2024/contract.pdf
oss://backups/database/snapshot.sql

Location String Parsing

The parsing logic extracts components as follows:

The scheme prefix identifies which filesystem adapter in the MountManager should handle the operation. The path component specifies the location within that filesystem.

Sources: src/Filesystem/Node/File.php29-39 src/Filesystem/Node/Folder.php39-43

Node Instantiation

The Filesystem type at src/Type/Filesystem.php111-119 provides the node() query for retrieving a Node object from a location string:

This method:

Checks if the location refers to a directory using directoryExists()
Checks if the location refers to a file using fileExists()
Returns the appropriate Node type or null if the location does not exist

The find() method at src/Type/Filesystem.php131-176 demonstrates bulk node instantiation during filesystem searches, creating nodes with pre-fetched metadata to optimize performance.

Sources: src/Type/Filesystem.php111-176

Metadata Caching

Both File and Folder classes support metadata caching through their constructors. When performing operations that return multiple nodes (e.g., getChildren(), find()), the system pre-fetches metadata during the directory listing and passes it to the node constructors:

This pattern is evident in:

Folder::getChildren() src/Filesystem/Node/Folder.php72-80
Filesystem::find() src/Type/Filesystem.php166-171

When a metadata method (e.g., getSize(), getLastModified()) is called, the implementation first checks the cached metadata array. Only if the value is not cached does it query the MountManager. This reduces filesystem operations from O(n) to O(1) for bulk queries.

Sources: src/Filesystem/Node/File.php47-69 src/Filesystem/Node/Folder.php72-94 src/Type/Filesystem.php166-171

Hidden File Filtering

Both the Folder::getChildren() method and the Filesystem::find() method filter out hidden files (those starting with a dot):

In Folder::getChildren() src/Filesystem/Node/Folder.php67-69:

In Filesystem::find() src/Type/Filesystem.php145-148:

This ensures that system files like .DS_Store, .gitignore, and Unix hidden files are not exposed through the GraphQL API. Hidden file filtering is a security measure to prevent accidental exposure of sensitive configuration files.

Sources: src/Filesystem/Node/Folder.php67-69 src/Type/Filesystem.php145-148

GraphQL Type Union

The GraphQL schema exposes Node as an interface type with File and Folder as implementing types. This allows queries like:

The #[Type()] attribute on the interface and both classes at src/Filesystem/Node/Node.php10 src/Filesystem/Node/File.php11 and src/Filesystem/Node/Folder.php11 instructs GraphQLite to generate the appropriate union type structure.

Sources: src/Filesystem/Node/Node.php10 src/Filesystem/Node/File.php11 src/Filesystem/Node/Folder.php11

Refresh this wiki

URL: https://deepwiki.com/mathsgod/light/7.2-node-types-(file-and-folder)