Download the PHP package nadlambino/uploadable without Composer

Automatically handle the file uploads for your models.

Table of Contents

• Installation
• Usage
• Customization
• Manually Processing of File Uploads
• Temporarily Disable the File Uploads
• Uploading Files on Model Update
• Uploading Files that are NOT from the Request
• Relation Methods
• Lifecycle and Events
• Queueing
• Testing
• Changelog
• Contributing
• Security Vulnerabilities
• Credits
• License

Installation

You can install the package via composer:

Publish and run the migrations with:

[!IMPORTANT]

You can add more fields to the uploads table according to your needs, but the existing fields should remain.

Optionally, you can publish the Upload model using

You can publish the config file with:

This is the contents of the published config file:

Usage

Simply use the NadLambino\Uploadable\Concerns\Uploadable trait to your model that needs file uploads.

Now, everytime you create or update a post, it will automatically upload the files that are included in your request and it will save the details in uploads table.

Customization

1. Rules and Messages

Files from the request should have the following request names:

You can add more fields or override the default ones by defining the protected uploadRules method in your model.

To add or override the rules messages, you can define the protected uploadRuleMessages method in your model.

2. File Name and Upload Path

You can customize the file name and path by defining the public methods getUploadFilename and getUploadPath in your model.

[!IMPORTANT]

Make sure that the file name is completely unique to avoid overriding existing files.

3. Storage Options

When you're uploading your files on cloud storage, oftentimes you want to provide options like visibility, cache control, and other metadata. To do so, you can define the getUploadStorageOptions in your model.

4. Upload Disk

When you're uploading your files, sometimes you just upload it on your local disk. However for larger files, you may want to use s3. This can be with static method uploadDisk.

5. Grouping of Uploads

When uploading a files for your model, sometimes you can have multiple file uploads for different purposes. For example, a post could have a file upload for thumbnail, banners, and gallery. This can be achieve with uploadToCollection method.

Also, to retrieve file uploads of specific collection, you can use the scope query fromCollection.

Manually Processing of File Uploads

File upload happens when the model's created or updated event was fired. If you're creating or updating a model quietly, you can call the createUploads or updateUploads method to manually process the file uploads.

[!IMPORTANT]

Depending on your configuration, the createUploads will delete the model when the upload process fails, while updateUploads will update it to its original attributes.

Temporarily Disable the File Uploads

You can temporarily disable the file uploads by calling the static method disableUpload.

Caveat

When you are trying to create or update multiple models, the default behavior is that all of the files from the request will be uploaded and will be attached to all of these models. This is because these models are firing the created or updated event which triggers the upload process.

There are multiple ways to prevent this from happening such as:

• Silently create or update the models. By doing so, the created or updated event won't be fired which will not trigger the upload process. This may not be what you want if you have a model observer for these two events.
• Disable the upload process on the specific model by calling the disableUpload() method.

• Disable the upload process from the NadLambino\Uploadable\Actions\Upload action itself. The Upload::disableFor() method can accept a model class name, a model instance, or an array of each or both. See below example:

• Lastly, specifically instruct the NadLambino\Uploadable\Actions\Upload to process the upload only for the specific given model by calling the Upload::onlyFor method. This method has the same parameter signature as Upload::disableFor and ensure that only these given model classes or instances will be process.

Also, there is NadLambino\Uploadable\Actions\Upload::enableFor() method if you need to delist a model from the disabled list. It is different from onlyFor in a way that onlyFor method ensures that the files were only be uploaded to the given models while enableFor just simply removes the given models from the disabled list.

All of these methods could also work even when you are uploading on a queue.

[!NOTE]

When calling the disableFor method, it will remove the given model from the list of onlyFor models. Same goes when calling the onlyFor method, it will remove the given model from the list of disabled models.

Uploading files on model update

By default, when you update a model, the files from the request will add up to the existing uploaded files. If you want to replace the existing files with the new ones, you can configure it in the uploadable.php config file.

Or alternatively, you can call the static method replacePreviousUploads before updating the model.

[!NOTE]

The process of deleting the previous uploads will only happen when new files were successfully uploaded.

Uploading files that are NOT from the request

If you wish to upload a file that is NOT directly from the request, you can do so by calling the uploadFrom method. This method can accept an instance or an array of Illuminate\Http\UploadedFile or a string path of a file that is uploaded on your temporary_disk.

[!IMPORTANT]

Make sure that you've already validated the files that you're passing here as it does not run any validation like it does when uploading directly from the request.

Relation methods

There are already pre-defined relation method for specific upload type.

[!IMPORTANT]

MorphOne relation method sets a limit of one in the query.

Lifecycle and Events

During the entire process of uploading your files, events are being fired in each step. This comes very helpful if you need to do something in between these steps or just for debugging purposes.

If you want to do something before the file information is stored to the uploads table, you can define the beforeSavingUpload public method in your model. This method will be called after the file is uploaded in the storage and before the file information is saved in the database.

Alternatively, you can statically call the beforeSavingUploadUsing method and pass a closure. The closure will receive the same parameters as the beforeSavingUpload method. Just make sure that you call this method before creating or updating the model. Also, beforeSavingUploadUsing has the higher precedence than the beforeSavingUpload allowing you to override it when needed.

[!IMPORTANT]

Remember, when you're on a queue, you are actually running your upload process in a different application instance so you don't have access to the current application state like the request object. Also, make sure that the closure and its dependencies you passed to the beforeSavingUploadUsing method are serializable.

Queueing

You can queue the file upload process by defining the queue name in the config.

Alternatively, you can also call the static method uploadOnQueue.

Testing

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

• Ronald Lambino
• All Contributors

License

The MIT License (MIT). Please see License File for more information.