File storage

Introduction

info

BowPHP includes a file management system that lets you manipulate files with great simplicity.

Configuration

The configuration file for the file management system is located at config/resource.php.

How it works

You can either use services or work with your local disk. The static methods local and service allow you to manipulate the disk system and the storage services respectively, currently ftp and s3.

Local file system

To manage your local file system with BowPHP, you will use the static method local.

Concept explanation

We will refer to the various specified folders as disk.

Consider the following configuration:

'disk' =>[
  'mount' => 'storage',
  'path' => [
    'storage' => __DIR__.'/../var/app',
    'public' => __DIR__.'/../public',
  ]
];

Note

You can specify as many disks as you want.

The Storage class exposes the static method local, which allows file manipulation. The value passed to local must be a valid disk name specified in the list of path.

use Bow\Storage\Storage;

Storage::local('public');     // named disk
Storage::local();             // default disk (the `mount` key)

// `Storage::disk()` is an alias of `Storage::local()`
Storage::disk('public');

Information

If the local method (or its alias disk) is called without a parameter, it will default to the value of the mount key.

You can also use the app_storage() helper, which works in exactly the same way:

app_storage('public');
// Or
app_storage()->get('app.js');

The S3 and FTP services

To use an external storage system, you do so through the service method. This method lets you select the type of external storage you want to use. You will find the required configuration for the services in the configuration file, in the services section of config/resource.php.

Example with the ftp service:

$service = Storage::service('ftp');
$service->get('app.js');

Manipulating files

This section describes the various methods available for manipulating files and how to use them.

Let's assume we have the file app.txt on the public disk:

// content of the app.txt file
Hello, world

Important

Note that these methods (except the get method) return true or false respectively on success or failure.

Retrieve a file's content

The get method is used to retrieve a file's content. It takes the file name as a parameter.

$local_storage = app_storage('public');
$content = $local_storage->get("app.txt");

// With a service
$service = Storage::service('ftp');
$content = $service->get("app.txt");

echo $content;
// => Hello, world

Compatibility

service and local use the same manipulation interface. This means that the methods available for local also exist for service.

Add/Modify a file's content

The put method lets you add or modify a file's content:

$local_storage = app_storage('public');
$content = 'console.log("Hello, world")';

$local_storage->put('app.js', $content );

Add content to the beginning or end of a file

The prepend and append methods let you add content to the beginning or the end of a file respectively:

$local_storage = app_storage('public');

$local_storage->prepend('app.txt', 'Content added at the beginning');
$local_storage->append('app.txt', 'Content added at the end');

Delete a file

The delete method lets you delete a file.

$local_storage = app_storage('public');

$local_storage->delete('app.js');

Copy or move a file

$local_storage = app_storage('public');

$local_storage->copy('app.txt', 'sous-dossier/app.txt');
$local_storage->move('app.txt', 'archive/app.txt'); // copy + delete the source

List files and folders

To enumerate the content of a folder:

$local_storage = app_storage('public');

$files = $local_storage->files('uploads');         // files in a folder
$subdirs = $local_storage->directories('uploads'); // subfolders

Store an uploaded file

To persist a file coming from $request->file(...):

$file = request()->file('avatar');

$path = app_storage('public')->store($file, 'avatars');
// path: relative path of the stored file

Create a folder

You can create a new folder using the makeDirectory method:

Prototype

makeDirectory(string $dirname, int $mode = 0777): bool

Parameter	Type	Description
dirname	string	The path of the folder to create
mode	int	UNIX mode, defaults to 0777

Automatic recursive creation

Bow calls mkdir($dirname, $mode, true) internally — recursive creation is always enabled. There is no need for a dedicated flag to create a tree such as chemin/vers/un/dossier.

$local_storage = app_storage('public');

$local_storage->makeDirectory('dossier');
$local_storage->makeDirectory('chemin/vers/un/dossier'); // recursive
$local_storage->makeDirectory('private', 0750);          // custom mode

Check whether a file exists

$local_storage = app_storage('public');

if ($local_storage->exists('app.txt')) {
  echo $local_storage->get('app.txt');
}

Check whether the parameter is a file

$local_storage = app_storage('public');

if ($local_storage->isFile('app.txt')) {
  echo "It's a file";
}

Check whether the parameter is a folder

$local_storage = app_storage('public');

if ($local_storage->isDirectory('nom_du_dossier')) {
  echo "It's a folder";
}

Get the absolute path of a file or folder

$local_storage = app_storage('public');

$path = $local_storage->path('app.txt');

echo $path;
// => /chemin/absolu/vers/le/fichier/app.txt

Is something missing?

If you run into problems with the documentation or have suggestions to improve the documentation or the project in general, please open an issue for us, or send a tweet mentioning the Twitter account @bowframework or directly on github.