Associate files with Eloquent models

This is a simple package to associate files with your eloquent model in laravel.

Installation

You can install the package via composer:

composer require ssntpl/laravel-files

Run the migrations with:

php artisan migrate

Optionally, You can publish and run the migrations with:

php artisan vendor:publish --tag="laravel-files-migrations"
php artisan migrate

You can publish the config file with:

php artisan vendor:publish --tag="laravel-files-config"

This is the contents of the published config file:

return [
    /*
     * When using the "HasFiles" trait from this package, we need to know which
     * Eloquent model should be used to retrieve your files. Of course, it
     * is often just the "File" model but you may use whatever you like.
     *
     * The model you want to use as a File model needs to implement the
     * `Ssntpl\LaravelFiles\Contracts\File` contract.
     */

    'model' => Ssntpl\LaravelFiles\Models\File::class,

    /*
     * When using the "HasFiles" trait from this package, we need to know which
     * table should be used to retrieve your files. We have chosen a basic
     * default value but you may easily change it to any table you like.
     */

    'table' => 'files',

    /*
     * Define the hashing algorithm to calculate the checksum of the file content.
     * Most commonly used hashing algorithm are md5, sha1, sha256. For a complete
     * list of supported hashing algorithms, check hash_algos().
     */

    'checksum' => 'md5',
];

Usage

Add the HasFiles trait to your model.

use Illuminate\Foundation\Auth\User as Authenticatable;
use Ssntpl\LaravelFiles\Traits\HasFiles;

class User extends Authenticatable
{
    use HasFiles;
}

Add new file to the model.

$model = User::find(1);

$file = $model->createFile([
    
    // type: Optional. If missing, the deault type of the model is used.
    'type' => 'avatar', 

    // name: Optional. Represents the file name. If missing, a random uuid is generated.
    'name' => 'my_avatar.png',  

    // key: Optional. If missing the key is auto-generated from FilePrefix attribute and name of the file.
    'key' => 'avatar/user/1/my_avatar.png', 

    // disk: Optional. Represents the disk on which the file is stored. If missing the default disk is used.   
    'disk' => 's3', 

    // base64: Optional. If present the string is decoded and written to disk.
    'base64' => 'base64 encoded string of the content of the file.',

    // contents: Optional. base64 takes precedence over contents key. If both base64 and contents key are missing then you can add the contents to the file later.
    'contents' => 'you can directly provide the contents instead of the base64 string',
]);

Defining the FilePrefix for the model.

class Flight extends Model 
{
    HasFiles;

    Protected $file_prefix = 'flights';
}

Defining FilePrefix dynamically. Sometimes we don't need a fixed path to store all the files of the model. You can use the FilePrefix attribute to create dynamic file prefix.

class Flight extends Model 
{
    HasFiles;

    public function getFilePrefixAttribute()
    {
        return 'flights/' . $this->id;       
    }
}

Accessing the File model.

$file->url; // Returns the url() of the file.

$file->exists(); // Boolean. Checks if the file exists on the disk.

echo $file; // Prints the url of the file.

echo $file->base64; // Prints the base64 encoded string of the file contents.

$file->base64 = 'base64 contents'; // Writes the content to the disk.

echo $file->contents; // Print the file contents.

$file->contents = 'file contents'; // Writes the contents to the disk.

Fetch single file. An excpeption is thrown if none, or more than one file is available.

$model->file;           // Fetches single file of default type. 

$model->file();         // Fetches single file of default type.

$model->file($type);    // Fetches single file of $type type.

Fetch multiple file relation.

$files = $model->files();   // Fetches relation to all the files belonging to the model.

$files->get(); // Fetches all the files of any type that belong to the model.

$files = $model->files($type);   // Fetches relation to all the files of type $type that belong to the model.

$files->get(); // Fetches all the files of type $type.

Testing

composer test

TODO

• Declare the Ssntpl\LaravelFiles\Contracts\File contract

Changelog

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

Security Vulnerabilities

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

Credits

• Sam
• All Contributors

License

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