README

FileManagerSystem is a Symfony bundle that provides easy and intuitive management of files and directories: creation, deletion, moving, MIME type handling, image resizing, and more.

It is designed to simplify file management within any Symfony application.

⚠️ State Management

This bundle is stateful: it maintains a navigation context (e.g. current directory, browsing state) across requests.

The state is securely isolated per user session, ensuring that each user interacts with their own file system context without interference.

🚀 Installation

Install the bundle via Composer:

composer require anfallnorr/file-manager-system

⚙️ Configuration

1. Register the Bundle

Add the bundle to your config/bundles.php file:

return [
    // ...
    Anfallnorr\FileManagerSystem\FileManagerSystem::class => ['all' => true],
];

2. AssetMapper Configuration (Optional)

Warning

If you want to use the built-in controller and assets provided by the bundle, create the following configuration files.

Create config/packages/file_manager_system.yaml:

framework:
    asset_mapper:
        paths:
            - '%kernel.project_dir%/vendor/anfallnorr/file-manager-system/assets'

Create config/routes/file_manager_system.yaml:

file_manager_system:
    resource: '../../vendor/anfallnorr/file-manager-system/src/Controller/'
    type: attribute
    prefix: /files-manager 

💡 Usage

Service Injection

Inject the FileManagerService into your controller or service:

public function __construct(
    private FileManagerService $fmService
) {
    $this->fmService->setDefaultDirectory('/var/uploads');
}

For convenience in examples below:

$fmService = $this->fmService;

📂 1. Directory Management

📌 Get the Default Upload Directory

$defaultDirectory = $fmService->getDefaultDirectory();
// Returns: /path/to/project/public/uploads

📌 Set a New Default Upload Directory

$directory = $fmService
    ->setDefaultDirectory('/var/uploads')
    ->getDefaultDirectory();
// Returns: /path/to/project/var/uploads

📁 1.1. Listing Directories

The getDirs() method allows you to explore the file system with support for exclusions, depth control, and relative paths.

Method Signature:

getDirs(
    string $path = '/', 
    string $excludeDir = '', 
    string|array|null $depth = '== 0'
): array

Parameters:

• $path — Base directory path to search within
• $excludeDir — Directory name pattern to exclude from results
• $depth — Depth filter using comparison operators (==, >, <)

Return Value:

• array — List of directories with absolute and relative paths

Examples

Basic usage:

$dirs = $fmService->getDirs();
// Returns directories found at depth 0 in the default directory

List directories inside a specific subfolder:

$dirs = $fmService->getDirs(path: 'uploads');
// Returns all directories inside /uploads at depth 0

Control search depth:

$dirs = $fmService->getDirs(path: 'uploads', depth: '== 1');
// Returns only directories exactly 1 level below /uploads

Exclude specific directories:

$dirs = $fmService->getDirs(path: 'uploads', excludeDir: 'temp');
// Returns all directories except those containing "temp" in their path

Combine all parameters:

$dirs = $fmService->getDirs(path: 'uploads', excludeDir: 'temp', depth: '== 1');
// Returns directories at depth 1 under "uploads", excluding folders containing "temp"

📁 1.2. Creating Directories

Create a new directory within the default directory.

Method Signature:

createDir(
    string $directory, 
    bool $returnDetails = false
): array

Parameters:

• $directory — Directory name (will be slugified automatically)
• $returnDetails — If true, returns detailed path information

Return Value:

• array — Directory details (if $returnDetails is true)

Examples

Simple directory creation:

$fmService->createDir(directory: 'Hello World!');
// Creates directory: /path/to/project/public/uploads/hello-world

Get detailed information:

$details = $fmService->createDir(directory: 'Hello World!', returnDetails: true);
// Returns:
// [
//     'absolute' => '/var/www/absolute/path/hello-world',
//     'relative' => '/path/hello-world',
//     'ltrimmed_relative' => 'path/hello-world',
//     'foldername' => 'hello-world'
// ]

📄 2. File Management

📄 2.1. Listing Files

The getFiles() method offers complete control over file search: depth, extension, folder filtering, and more.

Method Signature:

getFiles(
    string $path = '/', 
    string|array|null $depth = '== 0', 
    ?string $folder = null, 
    ?string $ext = null
): array|bool

Parameters:

• $path — Base directory path to search within
• $depth — Depth filter using comparison operators (==, >, <)
• $folder — Filter files by folder name (partial match)
• $ext — Filter by file extension (without dot)

Return Value:

• array — List of files with paths and metadata
• false — If no files are found

Examples

Get files from default directory:

$files = $fmService->getFiles();
// Returns files at depth 0 from the default directory, or false if none found

Get files from a subfolder:

$files = $fmService->getFiles(path: 'uploads');
// Returns files from /uploads at depth 0

Limit search by depth:

$files = $fmService->getFiles(path: 'uploads', depth: '== 1');
// Returns files located exactly 1 level below /uploads

Filter by folder name:

$files = $fmService->getFiles(path: 'uploads', folder: 'images');
// Returns only files within folders containing "images"

Filter by file extension:

$files = $fmService->getFiles(path: 'uploads', ext: 'jpg');
// Returns only .jpg files

Combine all filters:

$files = $fmService->getFiles(
    path: 'uploads', 
    depth: '== 2', 
    folder: 'products', 
    ext: 'png'
);
// Returns .png files inside folders containing "products", at depth 2 under "uploads"

📄 2.2. Creating Files

Create a new file with optional content.

Method Signature:

createFile(
    string $filename, 
    string $content = '<!DOCTYPE html><html lang="en"><body style="background: #ffffff;"></body></html>'
): void

Parameters:

• $filename — File name (will be slugified automatically)
• $content — File content (defaults to basic HTML template)

Return Value:

• void

Examples

Create an HTML file with custom content:

$fmService->createFile(
    filename: 'Hello World.html',
    content: 'Hello World! I\'m Js Info'
);
// Creates: /path/to/project/public/uploads/hello-world.html

Create a file with default HTML template:

$fmService->createFile(filename: 'welcome.html');
// Creates file with default HTML content

📄 2.3. Uploading Files

The upload() method allows you to upload one or multiple files to a specific directory. It handles filename slugification, optional renaming, and automatically generates useful metadata (size, MIME type, dimensions, etc.).

Method Signature:

upload(
	UploadedFile|array $files,
	string $folder,
	string $newName = '',
	bool $returnDetails = false
): array|bool

Parameters:

• $files — A single UploadedFile instance or an array of files
• $folder — Target directory (absolute path recommended)
• $newName — Optional new filename (for multiple files, a numeric suffix will be added)
• $returnDetails — If true, returns detailed information about uploaded files

Return Value:

• array — Detailed information about uploaded files (if $returnDetails is true)
• true — If upload succeeds and $returnDetails is false

Examples

Upload a single file:

$fmService->upload($file, '/var/www/uploads');

Upload a file with a custom name and get details:

$uploaded = $fmService->upload(
	$file,
	'/var/www/uploads',
	'my-file',
	true
);

// Example result:
[
	[
		'absolute' => '/var/www/uploads/my-file.jpg',
		'relative' => 'uploads/my-file.jpg',
		'filename' => 'my-file.jpg',
		'filesize' => '1.2 MB',
		'filemtime' => 1698200000,
		'extension' => 'jpg',
		'mime' => 'image/jpeg',
		'dimensions' => ['width' => 800, 'height' => 600]
	]
]

🔧 3. Utilities

🧩 Retrieve All Available MIME Types

Get a complete list of supported MIME types.

$mimeTypes = $fmService->getMimeTypes();
// Returns: ['pdf' => 'application/pdf', 'jpg' => 'image/jpeg', ...]

🧩 Get MIME Type for Specific Extension

Retrieve the MIME type for a given file extension.

$mimeType = $fmService->getMimeType(key: 'pdf');
// Returns: 'application/pdf'

🧩 Create URL-Friendly Slugs

Convert any string into a URL-safe slug.

$slug = $fmService->createSlug('Hello World !');
// Returns: 'hello-world'

🎨 4. Optional: Twig Integration

If you are using Twig and want Bootstrap-styled forms, add the following to your Twig configuration.

Edit config/packages/twig.yaml:

twig:
    form_themes: ['bootstrap_5_layout.html.twig']

📚 Additional Resources

• Symfony Documentation
• AssetMapper Component

📝 License

This bundle is open-source and available under the MIT License.