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 let you 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'll use the static method local.

Explaining the concept

We'll call the various specified folders 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 path list.

use Bow\Storage\Storage;

Storage::local('public');     // named disk
Storage::local();             // default disk (`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 via the service method. This method lets you select the type of external storage you want to use. You'll find the necessary service configuration 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 in 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.

Retrieving the content of a file

The get method is used to retrieve the content of a file. 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.

Adding/Modifying the content of a file

The put method lets you add to or modify the content of a file:

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

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

Adding content to the beginning or end of a file

The prepend and append methods let you add content to the beginning or 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');

Deleting a file

The delete method lets you delete a file.

$local_storage = app_storage('public');

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

Copying or moving 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

Listing files and folders

To enumerate the contents of a folder:

$local_storage = app_storage('public');

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

Storing 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

Creating 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's no need for a dedicated flag to create a tree like 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

Checking whether a file exists

$local_storage = app_storage('public');

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

Checking whether the parameter is a file

$local_storage = app_storage('public');

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

Checking whether the parameter is a folder

$local_storage = app_storage('public');

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

Getting 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.