File management for entity file assets. More...

#include <files.h>

Static Public Member Functions
static void	createDir (const std::string &entity_name)
	Create a directory for the given entity.

static void	renameDir (const std::string &old_entity_name, const std::string &new_entity_name)
	Rename an entity directory.

static void	deleteDir (const std::string &entity_name)
	Delete an entity directory and all its contents.

static std::string	dirPath (const std::string &entity_name, bool create_if_missing=false)
	Get the directory path for an entity.

static std::string	filePath (const std::string &entity_name, const std::string &filename)
	Get the absolute file path for an entity and filename.

static std::optional< std::string >	getFilePath (const std::string &entity_name, const std::string &filename)
	Get file path only if the file exists.

static bool	removeFile (const std::string &entity_name, const std::string &filename)
	Remove a file from an entity's directory.

static void	removeFiles (const std::string &entity_name, const std::vector< std::string > &files)
	Remove multiple files from an entity's directory.

static bool	fileExists (const std::string &entity_name, const std::string &filename)
	Check if a file exists in an entity's directory.

static fs::path	getCanonicalPath (const fs::path &path)
	Get canonical path and verify it's within the files base directory.

static bool	isCanonicalPath (const fs::path &path)
	Check if a path is canonical and within the files base directory.

static fs::path	filesBaseDir ()
	Get the base directory for all entity files.

Detailed Description

File management for entity file assets.

Handles file storage and retrieval for entities with file or files field types. Files are stored on disk in entity-specific directories, with filenames saved to the database.

Security features:

Entity name validation to prevent SQL injection
Path canonicalization to prevent directory traversal attacks
Automatic sanitization of filenames

The class handles:

Creating and deleting entity directories
Creating and deleting file resources
Updating folder names when entities are renamed
Deleting folder contents when entities are dropped

// Create directory for an entity
Files::createDir("products");
 
// Get file path (validates entity name and prevents path traversal)
std::string path = Files::filePath("products", "image.jpg");
 
// Check if file exists
if (Files::fileExists("products", "image.jpg")) {
    // File exists
}

Member Function Documentation

◆ createDir()

void mb::Files::createDir ( const std::string & entity_name )

static

Create a directory for the given entity.

Validates the entity name and creates the directory if it doesn't exist. Throws MantisException if entity name is invalid.

Parameters

entity_name Entity/table name (must be valid alphanumeric + underscore)

Exceptions

MantisException if entity name is invalid

◆ deleteDir()

void mb::Files::deleteDir ( const std::string & entity_name )

static

Delete an entity directory and all its contents.

Parameters

entity_name Entity/table name

◆ dirPath()

std::string mb::Files::dirPath	(	const std::string &	entity_name,
		bool	create_if_missing = `false`
	)

static

Get the directory path for an entity.

Returns the absolute path to the entity's file directory. Validates entity name and checks for path traversal attacks before returning the path.

Parameters

entity_name	Entity/table name (must be valid)
create_if_missing	If true, creates the directory if it doesn't exist

Returns: Absolute path string to the entity's file directory

Exceptions

MantisException if entity name is invalid or path traversal is detected

◆ fileExists()

bool mb::Files::fileExists	(	const std::string &	entity_name,
		const std::string &	filename
	)

static

Check if a file exists in an entity's directory.

Parameters

entity_name	Entity/table name
filename	File name to check

Returns: true if file exists, false otherwise

◆ filePath()

std::string mb::Files::filePath	(	const std::string &	entity_name,
		const std::string &	filename
	)

static

Get the absolute file path for an entity and filename.

Constructs and canonicalizes the file path, ensuring it's within the entity's directory to prevent path traversal attacks. Validates entity name and filename.

Parameters

entity_name	Entity/table name (must be valid)
filename	File name (must not be empty)

Returns: Absolute canonical path string to the file

Exceptions

MantisException if entity name is invalid, filename is empty, or path traversal is detected

◆ filesBaseDir()

fs::path mb::Files::filesBaseDir ( )

static

Get the base directory for all entity files.

Returns the path to the files directory (typically <dataDir>/files).

Returns: Filesystem path to the base files directory

◆ getCanonicalPath()

fs::path mb::Files::getCanonicalPath ( const fs::path & path )

static

Get canonical path and verify it's within the files base directory.

Canonicalizes the given path (resolves symlinks, removes "..", etc.) and verifies that it's within the files base directory to prevent path traversal attacks.

Parameters

path	Path to canonicalize and validate

Returns: Canonical path if valid

Exceptions

MantisException if path traversal is detected (400 status)

◆ getFilePath()

std::optional< std::string > mb::Files::getFilePath	(	const std::string &	entity_name,
		const std::string &	filename
	)

static

Get file path only if the file exists.

Returns the file path if the file exists on disk, otherwise returns std::nullopt. Validates entity name before checking file existence.

Parameters

entity_name	Entity/table name
filename	File name

Returns: Absolute file path if file exists, std::nullopt otherwise

Exceptions

MantisException if entity name is invalid

◆ isCanonicalPath()

bool mb::Files::isCanonicalPath ( const fs::path & path )

static

Check if a path is canonical and within the files base directory.

Canonicalizes the path and checks if it's within the files base directory without throwing an exception.

Parameters

path	Path to check

Returns: true if path is canonical and within base directory, false otherwise

◆ removeFile()

bool mb::Files::removeFile	(	const std::string &	entity_name,
		const std::string &	filename
	)

static

Remove a file from an entity's directory.

Parameters

entity_name	Entity/table name
filename	File name to remove

Returns: true if file was successfully removed, false otherwise

◆ removeFiles()

void mb::Files::removeFiles	(	const std::string &	entity_name,
		const std::vector< std::string > &	files
	)

static

Remove multiple files from an entity's directory.

Parameters

entity_name	Entity/table name
files	Vector of file names to remove

◆ renameDir()

void mb::Files::renameDir	(	const std::string &	old_entity_name,
		const std::string &	new_entity_name
	)

static

Rename an entity directory.

Renames the directory if it exists, otherwise creates a new one. Validates both old and new entity names.

Parameters

old_entity_name	Current entity name
new_entity_name	New entity name

Exceptions

MantisException if either entity name is invalid

The documentation for this class was generated from the following files:

/home/runner/work/mantisbase/mantisbase/include/mantisbase/core/files.h
/home/runner/work/mantisbase/mantisbase/src/core/files.cpp

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ createDir()

◆ deleteDir()

◆ dirPath()

◆ fileExists()

◆ filePath()

◆ filesBaseDir()

◆ getCanonicalPath()

◆ getFilePath()

◆ isCanonicalPath()

◆ removeFile()

◆ removeFiles()

◆ renameDir()