PHPackages                             stechstudio/laravel-shuttle - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. stechstudio/laravel-shuttle

ActiveLibrary

stechstudio/laravel-shuttle
===========================

This is my package laravel-shuttle

v1.0.0(3y ago)0910[2 PRs](https://github.com/stechstudio/laravel-shuttle/pulls)MITBladePHP ^8.0|^8.1

Since Jul 12Pushed 2y ago3 watchersCompare

[ Source](https://github.com/stechstudio/laravel-shuttle)[ Packagist](https://packagist.org/packages/stechstudio/laravel-shuttle)[ Docs](https://github.com/stechstudio/laravel-shuttle)[ GitHub Sponsors](https://github.com/stechstudio)[ RSS](/packages/stechstudio-laravel-shuttle/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (12)Versions (5)Used By (0)

Laravel Shuttle
===============

[](#laravel-shuttle)

This package is designed to provide an amazingly simple way to get large-scale file uploading working in a TALL app, directly to S3.

- Simply integrate into your app using a single Blade component, that's it.
- UI ready. No need to implement in your UI at all. Users can drag-n-drop files anywhere on the page, and a fixed bottom-bar progress appears.
- Events are fired when files upload, so your app can react and update the UI accordingly.

Installation
------------

[](#installation)

### 1. Composer install this package

[](#1-composer-install-this-package)

```
composer require stechstudio/laravel-shuttle
```

### 2. Migrate the database

[](#2-migrate-the-database)

Shuttle sets up its own `uploads` table to store details of each file. Your app can then make use of these upload records, or you can move the file information to a different database table after the upload completes.

```
php artisan migrate
```

### 3. Add the routes

[](#3-add-the-routes)

Shuttle will create all the necessary routes for multipart uploads, you just have to tell Shuttle where to define the routes. This way you can wrap any middleware, route prefix, or other requirements.

```
Route::middleware(['auth'])->group(function() {
    Shuttle::routes();
});
```

### 4. Configure AWS

[](#4-configure-aws)

Make sure you have an `s3` disk properly configured in Laravel already. See the advanced config below if you want to change which disk or S3 client Shuttle uses.

The S3 bucket you decide to use needs CORS configured. Open the bucket in the AWS console, click on the permissions tab, scroll down to the CORS box, and paste this:

```
[
    {
        "AllowedHeaders": [
            "*"
        ],
        "AllowedMethods": [
            "POST",
            "PUT",
            "DELETE"
        ],
        "AllowedOrigins": [
            "*"
        ],
        "ExposeHeaders": [
            "ETag"
        ],
        "MaxAgeSeconds": 3000
    }
]

```

You can further restrict origins if desired.

> **Disclaimer**
> The CORS Everywhere plugin does not play nicely with this package. Make sure that you disable it when developing locally.

Implementation
--------------

[](#implementation)

Implementing Shuttle in your app is pretty simple, let's walk through it.

### 1. Implement the Blade component

[](#1-implement-the-blade-component)

It's time to drop Shuttle into your app. All you have to do is use the Blade component in your view where you want users to upload files. This should be a Livewire view file.

```

```

### 2. Add the upload context

[](#2-add-the-upload-context)

You Livewire component needs to expose a `$uploadContext` array, with any metadata about the uploaded files that you will need later on to determine ownership.

For example, let's say you have a simple folder/file app. When users upload files to, you will need to add the folder ID to each file upload, so you can determine how to relate the files in the database. Your `Folder` Livewire component class might look something like this:

```
class Folder extends Component {
    public $uploadContext = [];
    public $folder;

    public function mount(Folder $folder) {
        $this->folder = $folder;
        $this->uploadContext = ['folder_id' => $folder->id];
    }
```

### 3. Tell Shuttle how to relate files

[](#3-tell-shuttle-how-to-relate-files)

When a file is uploaded, Shuttle needs to know what the owner of the file is. We're not talking about the user that performed the upload, but rather *what model the file should be attached to.* This is commonly a folder, or a project.

In your `AppServiceProvider` `boot()` method, you will need to define a callback function that receives the file metadata (including the context information provided in the previous step). This will return a database model.

So for our folder example above, we might define a callback like this:

```
Shuttle::resolveOwnerWith(function(array $metadata) {
    return Folder::findOrFail($metadata['folder_id']);
});
```

Shuttle will now ensure the uploaded files have an `owner` relationship set to this folder.

You also need to add the `HasUploads` trait on the owning model. In our example above, this would be the `Folder` model.

> **Warning**
> This is a basic example to get things working. You will most likely want to perform some authorization check in that callback function to ensure the currently logged-in user has permission to upload files to the specified folder.

### 4. Add relationship to your owning models OR handle completed uploads yourself

[](#4-add-relationship-to-your-owning-models-or-handle-completed-uploads-yourself)

If you'd like to make use of the `uploads` database records directly, there's nothing more to do. You can access `$folder->uploads` with our previous example setup, and retrieve all uploaded files.

Alternatively, if you prefer to handle uploaded file data on your own, you can wire up a callback that Shuttle will execute when an upload completes. Do this in your `AppServiceProvider`:

```
Shuttle::whenComplete(function(Upload $upload) {
    // ...store the upload information somewhere else in your database
});
```

In this case, you probably want to treat `Upload` records as temporary, and execute a `$upload->delete()` in the above callback after handling.

Uploading files
---------------

[](#uploading-files)

At this point you should be able to visit page in your app where you have implemented the Shuttle Blade component and provide upload context in your Livewire component.

Drag some files onto the page, and you should see a translucent overlay appear, letting you know you can drop your files.

Once you drop the files, you should see a bar at the bottom of the page showing the status of your uploads. You can expand this bar to view the individual status of each file as it uploads.

The bar will turn green when all dropped files are successfully uploaded. It will turn red and auto-expand if any uploads fail, showing the error messages.

Events
======

[](#events)

We expose the following events that you can listen for.

EventPropertiesfileAdded$fileuploadProgress$file, $progressprogress$progressuploadSuccess$fileuploadError$filefileRemoved$filecomplete$resultCustomization
=============

[](#customization)

You are able to customise the colours of the UI. You just need to go ahead and publish the config file.

`php artisan vendor:publish --tag=shuttle-config`

```