File Storage System

A file storage system is a system used to store and manage files. It's a crucial part of most applications, as it helps you create, read, update, store and delete files effectively. Leaf provides a simple and easy-to-use file storage system that allows you to work with files on your server or in the cloud.

Docs version

This documentation covers FS v2 and above. If you're using an older version, you can check the documentation hosted here.

Installation

You can quickly install Leaf's file storage system through composer or the leaf cli.

Leaf CLI

leaf install fs

Composer

composer require leafs/fs

That's it! You can now use the storage()/path() functions from anywhere in your app to interact with your files.

Working with file paths

File paths are the locations of files on your server. They help you locate and interact with files effectively. While they are essential for working with files, they can be a bit tricky to work with. Leaf provides a simple way to work with file paths using the path() function.

Getting information out of a path

Given a path, you can extract information out of it using those methods:

• dirname(): gets the parent folder of a file
• basename(): gets the filename part
• extname(): gets the file extension

$path = path('path/to/file.txt');

$path->dirname(); // path/to
$path->basename(); // file.txt
$path->extname(); // txt

Joining paths

You can join paths together using the join() method.

$path = path('path')->join('to', 'file.txt');

echo $path; // path/to/file.txt

Normalizing paths

When working with paths, we usually tend to do things like path/to/parent/..//file.txt or path\to\file.txt. Leaf provides a way to "fix" these paths using the normalize() method.

$path = path('path/to/parent/..//file.txt')->normalize();

echo $path; // path/to/file.txt

Working with Files

Working with files is a crucial part of most applications. Leaf provides a simple and easy-to-use file system that allows you to create, read, update, and delete files effectively using the storage() function.

Creating Files

You can create files using the createFile() method. It takes in 3 arguments:

• the file path
• the content to set or a function that returns the file content (optional)
• an array of configuration options (optional)
  • overwrite: whether to overwrite the file if it already exists
  • rename: whether to rename the file if it already exists

If you don't provide the file content, Leaf will create an empty file for you.

storage()->createFile('path/to/file.txt');

storage()->createFile('path/to/file.txt', function () {
  return 'Hello, world!';
});

storage()->createFile('path/to/file.txt', 'Hello, world!', [
  'overwrite' => true
]);

The createFile() method returns a boolean indicating whether the file was created successfully. If the file was not created successfully, you can get the errors using the errors() method.

$created = storage()->createFile('path/to/file.txt');

if ($created) {
  echo 'File created successfully';
} else {
  $errors = storage()->errors();
}

Reading Files

Reading files means getting the content of a file. You can read files using the read() method. It takes in the file path and returns the file content.

$content = storage()->read('path/to/file.txt');

echo $content;

Updating Files

You can update files using the writeFile() method. It takes in the file path and the content to set or a function that returns the file content.

storage()->writeFile('path/to/file.txt', 'Hello, world!');

storage()->writeFile('path/to/file.txt', function () {
  return 'Hello, world!';
});

If the file is a readable file, the writeFile() method will provide the current content of the file to the function.

storage()->writeFile('path/to/file.txt', function ($content) {
  return $content . ' Hello, world!';
});

Getting File Information

You can get information like the file size, file type, and last modified time of a file using the fileInfo() method.

$info = storage()->fileInfo('path/to/file.txt');

Or by using more specific methods:

$size = storage()->size('path/to/file.txt'); // in bytes
$type = storage()->type('path/to/file.txt'); // file type
$lastModified = storage()->lastModified('path/to/file.txt'); // last modified time
$extension = storage()->extension('path/to/file.txt'); // txt
$basename = storage()->basename('path/to/file.txt'); // file.txt
$dirname = storage()->dirname('path/to/file.txt'); // path/to

File Uploads

File uploads are a common feature in most applications. Users can upload files like images, videos, and documents to your server. Leaf provides a simple way to handle file uploads using the upload() method.

$uploaded = storage()->upload('fileToUpload', 'path/to/uploads');

if ($uploaded) {
  echo 'File uploaded successfully';
} else {
  $errors = storage()->errors();
}

The upload() method automatically grabs the file from the request, so you don't have to worry about all of that.

One amazing thing about the upload() method is that it can detect the file type and automatically handle any associated configuration. If you need to customize the upload configuration, you can pass an array of configuration options as the third parameter.

$uploaded = storage()->upload('fileToUpload', 'path/to/uploads', [
  'maxSize' => 1024 * 1024, // 1MB
  'allowedTypes' => ['image'],
  'allowedExtensions' => ['jpg', 'png', 'gif'],
  'validate' => true,
  'mode' => 0777,
  'rename' => false,
  'recursive' => false,
  'overwrite' => false,
]);

This is a list of config options for the upload() method:

Config Name	Description	Possible Values
mode	Permissions to create your destination folder if it doesn't exist	Any permissions accepted by mkdir()
overwrite	If true, Leaf will overwrite the file if it already exists	true, false
rename	If true, Leaf will rename the file if it already exists	true, false
validate	If true, Leaf will validate the file before uploading	true, false
maxSize	The maximum file size allowed in bytes	int
allowedTypes	The allowed file types	image, video, audio, presentation, compressed, spreadsheet, application, custom

This is a list of values Leaf uses to check for file types:

File Type	Common Extensions
image	'jpg', 'jpeg', 'png', 'gif', 'webp', 'apng', 'tif', 'tiff', 'svg', 'pjpeg', 'pjp', 'jfif', 'cur', 'ico'
video	'mp4', 'webm', 'swf', 'flv'
audio	'wav', 'mp3', 'ogg', 'm4a'
text	'txt', 'log', 'xml', 'doc', 'docx', 'odt', 'wpd', 'rtf', 'tex', 'pdf'
presentation	'ppsx', 'pptx', 'ppt', 'pps', 'ppsm', 'key', 'odp'
compressed	'zip', 'rar', 'bz', 'gz', 'iso', 'tar.gz', 'tgz', 'zipx', '7z', 'dmg'
spreadsheet	'ods', 'xls', 'xlsx', 'xlsm'
application	'apk', 'bat', 'cgi', 'pl', 'com', 'exe', 'gadget', 'jar', 'msi', 'py', 'wsf'

Working with Folders

Working with folders is an essential part of most applications. Leaf provides a simple and easy-to-use file system that allows you to create, read, update, and delete folders effectively using the storage() function.

Creating Folders

You can create folders using the createFolder() method. It takes in 2 parameters:

• the folder path
• an array of configuration options.
  • recursive: whether to create the folder recursively
  • rename: whether to rename the folder if a folder with the same name already exists

storage()->createFolder('path/to/folder');

storage()->createFolder('path/to/folder', [
  'recursive' => true
]);

It returns a boolean indicating whether the folder was created successfully.

$created = storage()->createFolder('path/to/folder', [
  'rename' => true
]);

if ($created) {
  echo 'Folder created successfully';
} else {
  $errors = storage()->errors();
}

Checking Folder Contents

You can check if a folder is empty using the isEmpty() method. It takes in the folder path and returns a boolean indicating whether the folder is empty.

$isEmpty = storage()->isEmpty('path/to/folder');

You can also get the contents of a folder using the list() method. It takes in the folder path and a key to sort the contents by. It returns an array of the folder contents.

$contents = storage()->list('path/to/folder');
$phpFiles = storage()->list('path/to/folder', '*.php');

If you need to do more complex filtering, you can pass a function as the second parameter to the list() method.

$contents = storage()->list('path/to/folder', function ($file) {
  // if true, the file will be included in the results
  return storage()->isFile($file) && storage()->extension($file) === 'php';
});

File/Folder permissions

You can set file/folder permissions using the chmod() method. It takes in the file/folder path and the permissions to set.

storage()->chmod('path/to/file.txt', 0777);

If you are not sure of the current permissions of a file/folder, you can get them using the same method.

$permissions = storage()->chmod('path/to/file.txt');

Checking if a file exists

You can check if a file or folder exists using the exists() method. It takes in the file path and returns a boolean indicating whether the file exists.

$exists = storage()->exists('path/to/file.txt');

This will return true if the path matches an existing folder or file, but if you want to get more specific, you can use the isFile() and isFolder() methods to check if a path is a file or folder.

$isFile = storage()->isFile('path/to/file.txt');
$isFolder = storage()->isFolder('path/to/folder');

Renaming Files and Folders

There are instances where you might need to rename files or folders. Leaf provides a simple way to rename files and folders using the rename() method. It takes in 2 parameters:

• the current file/folder path
• the new file/folder path

storage()->rename('path/to/file.txt', 'path/to/new-file.txt');

storage()->rename('path/to/folder', 'path/to/new-folder');

It returns a boolean indicating whether the file/folder was renamed successfully.

$renamed = storage()->rename('path/to/file.txt', 'path/to/new-file.txt');

if ($renamed) {
  echo 'File renamed successfully';
} else {
  $errors = storage()->errors();
}

Deleting Files and Folders

When you no longer need a file or folder, you can delete it using the delete() method. It takes in the file/folder path and returns a boolean indicating whether the file/folder was deleted successfully.

$deleted = storage()->delete('path/to/file.txt');

if ($deleted) {
  echo 'File deleted successfully';
} else {
  $errors = storage()->errors();
}

Copying Files and Folders

When you need to duplicate a file or folder, you can copy it using the copy() method. It takes in 2 parameters:

• the current file/folder path
• the new file/folder path

storage()->copy('path/to/file.txt', 'path/to/new-file.txt');

storage()->copy('path/to/folder', 'path/to/new-folder');

It returns a boolean indicating whether the file/folder was copied successfully.

$copied = storage()->copy('path/to/file.txt', 'path/to/new-file.txt');

if ($copied) {
  echo 'File copied successfully';
} else {
  $errors = storage()->errors();
}

Moving Files and Folders

This is similar to copying files and folders, but instead of duplicating the file/folder, it moves it to a new location. You can move files and folders using the move() method. It takes in 2 parameters:

• the current file/folder path
• the new file/folder path

storage()->move('path/to/file.txt', 'path/to/new-file.txt');

storage()->move('path/to/folder', 'path/to/new-folder');

It returns a boolean indicating whether the file/folder was moved successfully.

$moved = storage()->move('path/to/file.txt', 'path/to/new-file.txt');

if ($moved) {
  echo 'File moved successfully';
} else {
  $errors = storage()->errors();
}

Symlinks/Shortcuts

Symlinks are shortcuts to files or folders. They allow you to access a file or folder from a different location. Leaf provides a simple way to create symlinks using the symlink() method. It takes in 2 parameters:

• the target file/folder path
• the symlink path

storage()->link('path/to/file.txt', 'path/to/symlink.txt');
storage()->link('path/to/folder', 'path/to/symlink');

It returns a boolean indicating whether the symlink was created successfully.

$linked = storage()->link('path/to/file.txt', 'path/to/symlink.txt');

if ($linked) {
  echo 'Symlink created successfully';
}