Laravel Filer 1.0 Released

Written by Riari 1 year ago. Last updated 1 year ago.

Attachments Laravel-5

Laravel Filer is a small package that provides a simple way of attaching one or more URLs or system files to your models.

There are a few ORM-attachment solutions out in the wild, one of the most notable being stapler, which supports both Laravel 4 and 5; this is a well-matured project that integrates tools such as the imagine image library for image manipulation, making it an ideal solution to get up and running with ORM attachments as quickly as possible.

That said, Filer makes a good alternative for those who prefer to have total control over filesystem operations and image processing; it doesn't deal with either of those things. You can build out your file-related workflows however you want to, then plug Filer in to take care of associating files and URLs with your models:

Installation

Step 1: Install the package

Install the package via Composer:

composer require teamteatime/laravel-filer

Add the service provider to your config/app.php:

TeamTeaTime\Filer\FilerServiceProvider::class,

If your app defines a catch-all route, make sure you load this service provider before your app service providers.

Step 2: Publish the package files

Run the vendor:publish command to publish Filer's migrations:

php artisan vendor:publish

Step 3: Update your database

Run your migrations:

php artisan migrate

Step 4: Update your models

Add attachment support to your models by using the HasAttachments trait:

class ... extends Eloquent {
    use \TeamTeaTime\Filer\HasAttachments;
}

Configuration

Filer requires no configuration out of the box in most cases, but the following options are available to you in config/filer.php:

Option Description Default
routes Determines whether or not to automatically define Filer's routes. If you set this to false, you can optionally use \TeamTeaTime\Filer\Filer::routes($router, $namespace) in your routes.php. true
route_prefix If routes are enabled, this is used for all route prefixes. files
path Contains the relative and absolute paths to the directory where your attachment files are stored. storage_path('uploads')
append_querystring If enabled, attachment URLs include a querystring containing the attachment's updated_at timestamp. This prevents out of date attachments from being loaded by the browser. true
cleanup_on_delete If enabled, Filer will attempt to delete local files referenced by deleted attachments. true

Usage

To attach a file or URL, use the attach() method on your model. This method will accept any of the following:

...a local file path

$user->attach('avatars/1.jpg'); // path relative to your configured storage directory

...an instance of SplFileInfo

$photo = Request::file('photo')->move($destinationPath);
$user->attach($photo);

Symfony\Component\HttpFoundation\File\File, Symfony\Component\HttpFoundation\File\UploadedFile and Illuminate\Http\UploadedFile are extensions of SplFileInfo and Laravel Requests contain the latter by default.

...or a URL

$user->attach('http://www.analysis.im/uploads/seminar/pdf-sample.pdf');

You can also specify a key (which uniquely identifies the attachment), a title, and/or a description using the options array:

$user->attach('uploads/avatars/1.jpg', ['key' => 'avatar']);
$article->attach($pdf, ['title' => "Event 2015 Guide", 'description' => "The complete guide for this year's event."]);

By default, attachments are associated with user IDs using Auth::id(). You can override this at call time:

$user->attach($photo, ['user_id' => $user->id]);

Depending on what you pass to this method, the item will be stored as either a TeamTeaTime\Filer\LocalFile or a TeamTeaTime\Filer\Url. You can later call on attachments via the attachments relationship. Examples are provided below.

Displaying a list of attachments in a view

@foreach ($article->attachments as $attachment)
<a href="{{ $attachment->getDownloadUrl() }}">{{ $attachment->title }}</a>
<p class="description">{{ $attachment->description }}</p>
@endforeach

Retrieving an attachment by ID or key

$user->attachments()->find($attachmentId);
$user->findAttachmentByKey('avatar');

Accessing an attachment's properties and type-specific properties

$avatar = $user->findAttachmentByKey('avatar');
$avatar->getUrl();          // the URL to the file (see below)
$avatar->getDownloadUrl();  // the download URL to the file (see below)
$avatar->title;             // the attachment title, if any
$avatar->description;       // the attachment description, if any

// If the attachment is a LocalFile...
$avatar->item->filename;    // the filename, with its extension
$avatar->item->path;        // the path to the directory where the file exists
$avatar->item->mimetype;    // the file's detected MIME type
$avatar->item->size;        // the file size, in bytes
$avatar->item->getFile();   // the Symfony File representation of the file

Generating URLs

The getUrl() and getDownloadUrl() methods above will return different values based on the attachment type; if it's a local file, they will return the 'view' and 'download' routes respectively, otherwise they'll return the URL that was attached.

For local files, the provided routes can be generated with a file ID:

route('filer.file.view', $fileId);
route('filer.file.download', $fileId)

Note that depending on the file's MIME type, the browser may begin a download with both of these routes.


As always contributions are welcome!