thrive/laravel-model-storage

Manejo de archivos orientado a modelos Eloquent con soporte S3, CloudFront y storage local

v1.0.0 2026-05-10 01:21 UTC

Requires

• php: ^8.2
• illuminate/database: ^10.0|^11.0|^12.0
• illuminate/filesystem: ^10.0|^11.0|^12.0
• illuminate/http: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0

Requires (Dev)

• orchestra/testbench: ^8.0|^9.0
• phpunit/phpunit: ^10.0|^11.0

Suggests

• league/flysystem-aws-s3-v3: Requerido para usar el driver S3 (^3.0)

MIT

• Thrive Coding

• storage
• s3
• cloudfront
• laravel
• eloquent
• file-upload

README

Manejo de archivos orientado a modelos Eloquent con soporte para S3, CloudFront y storage local.

Instalación

composer require thrive/laravel-model-storage

Publicar la configuración:

php artisan vendor:publish --tag="model-storage"

Configuración

El archivo config/model-storage.php permite definir:

return [
    'default' => [
        'disk' => env('MODEL_STORAGE_DISK', 'local'),
    ],

    'url_resolvers' => [
        'cloudfront' => [
            'enabled' => env('MODEL_STORAGE_CLOUDFRONT_ENABLED', false),
            'url'     => env('MODEL_STORAGE_CLOUDFRONT_URL'),
            'prefix'  => env('MODEL_STORAGE_CLOUDFRONT_PREFIX', '/'),
        ],
        's3_direct' => [
            'enabled' => env('MODEL_STORAGE_S3_DIRECT_ENABLED', true),
        ],
    ],

    'extra_mime_types' => [],
];

Uso

Trait HasStorage

Agrega el trait al modelo Eloquent:

use Thrive\Laravel\ModelStorage\HasStorage;

class Noticia extends Model
{
    use HasStorage;
}

Almacenar un archivo subido

$noticia->storeFile($uploadedFile);
$noticia->storeFile($uploadedFile, 'thumbnail');

Almacenar contenido string

$noticia->storeStringContent($content, '.pdf', 'default');

Obtener la URL pública

$url = $noticia->getStorageUrl('.jpg');
$url = $noticia->getStorageUrl('.jpg', 'thumbnail');

Obtener la ruta de almacenamiento

$path = $noticia->getStoragePath('.jpg');

StorageHelper (uso directo sin trait)

use Thrive\Laravel\ModelStorage\StorageHelper;

StorageHelper::storeUploadedFile($model, $file, 'thumbnail');
StorageHelper::getModelStorageUrl($model, '.jpg', 'thumbnail');
StorageHelper::getFile($path);

Validación de tipos de archivo

use Thrive\Laravel\ModelStorage\MimeType\FileTypeValidator;

FileTypeValidator::validateImage($uploadedFile);
FileTypeValidator::validatePdf($uploadedFile);
FileTypeValidator::validateSpreadsheet($uploadedFile);
FileTypeValidator::validate($uploadedFile, ['image/png', 'image/jpeg']);
FileTypeValidator::validateAny($uploadedFile, FileTypeValidator::IMAGES, FileTypeValidator::DOCUMENTS);

Resolución de URLs

La librería usa una cadena de resolvers con prioridad:

1. CloudFront (si está habilitado en config)
2. S3 directo (si el disco no es local)
3. Local (fallback)

Estructura de paths

Los archivos se particionan cada 2 dígitos del ID del modelo:

ID 216599 → {tabla}/21/65/99/216599
ID 216599 con sufijo "thumbnail.jpg" → {tabla}/21/65/99/216599_thumbnail.jpg

Testing

composer install
vendor/bin/phpunit

Requisitos

• PHP 8.2+
• Laravel 10.x / 11.x / 12.x

Licencia

MIT