Download the PHP package codewiser/simple-files without Composer

Simple lightweight storage

No database, only the filesystem.

Every model keeps its files isolated from one another. The path to a file is built from the model's morph name and its primary key.

Remember to call enforceMorphMap in AppServiceProvider!

Define storage

Implement the Attachmentable contract on your model.

In the example below the model keeps its files on the public disk, under the post/{id} path.

The disk argument is optional and defaults to the filesystems.default config value.

Uploading files

You may store an UploadedFile, a path to a local file, an instance of File kept on any disk, or — when allow_url_fopen is enabled — a remote URL. Several files may be uploaded at once.

The owner must be saved first: storing files to an unsaved model throws a LogicException, because such a model has no mount point of its own yet.

Listening to uploads

Every stored file dispatches a FileWasStored event:

Removing files

The path attribute of a file is its relative path on the disk, for example post/1/test.png. Use it to delete files; you may delete several at once.

To remove all files, call flush() on the storage. When the mount point gets empty, it is dropped too:

List files

To get a collection with all files, call files() on the storage:

Storage is Arrayable too and returns the same thing:

File serialization

The File object mirrors the Laravel Storage facade: exists, size, lastModified, delete, checksum, url and so on.

Every stored file is represented by such an array:

File implements Responsable and Attachable, so you may use it as a Response and in a Notification or a Mailable.

Singular storage

Sometimes a model needs to have only one file. We may create such a storage:

When you upload the next file to this storage, all previous files are removed.

A singular storage holds at most one element in its files collection, so you may prefer the file() method:

Storage pool

A model may have several storages at the same time. Storages must have unique names, also known as buckets. A bucket keeps its files in a subdirectory.

Then we may ask for an exact bucket:

Prune files with the owner

Register AttachmentableObserver on the owner model to unlink its files when the owner is destroyed:

Files are unlinked on the deleted event. An owner with the SoftDeletes trait keeps its files until forceDelete is called.

The observer flushes the default bucket and every bucket declared as a backed enum case in the storage method argument:

The observer reflects that argument, resolves every Bucket case, and flushes post/1, post/1/cover, post/1/docs and so on.

If buckets are defined as plain strings, the observer cannot enumerate them.

Pool response

You may add a method to a model that returns a Pool object with all buckets defined:

Then you may use this method in an API resource:

The Pool::toArray() method returns an array with every bucket and its file or files. A singular storage provides a file entry, which is an empty array when no file has been uploaded; a base storage provides a files array, which may be empty.

Downloading files

A file is directly accessible only when it is published on a public local filesystem. In every other case — a private or a cloud filesystem — the application needs a controller that serves files to its users.

Let's say we have such a private disk in config/filesystems.php:

A file on this disk is addressed as private/post/1/test.png for the default bucket and as private/post/1/docs/test.png for a named bucket.

The package ships an invokable StorageController for this purpose. All you need is to declare a route:

When a file belongs to the default bucket, the {bucket} segment carries the filename, and the controller shifts the parameters for you.

The {model} segment must be a registered morph alias, so enforceMorphMap() is required here as well: an unknown alias becomes a BadRequest.

The {bucket} segment is matched against the argument of your storage() method: a plain string is handed over as it is, while an enum-typed one is resolved to its case.

The controller resolves the storage from the route parameters, authorizes the owner model with the view policy, and returns the matched file as a streamed response. Resolution failures are turned into HTTP BadRequest exceptions, and a missing file becomes NotFound.