Laravel ImageUp

To customize global settings, publish the configuration file to config/imageup.php using the following artisan command:

php artisan vendor:publish --provider="QCod\ImageUp\ImageUpServiceProvider" --tag="config"

The package registers itself automatically. If manual registration is required, add the provider to the providers array in config/app.php.

QCod\ImageUp\ImageUpServiceProvider::class

To enable automatic image handling, add the HasImageUploads trait to your Eloquent model and define the $imageFields property. The package hooks into the Model::saved() event to handle uploads, database updates, and old file deletion.

Note: Database columns for image fields must be of type VARCHAR to store the file path. Ensure you have run php artisan storage:link to access files via the public disk.

<?php
namespace App;

use QCod\ImageUp\HasImageUploads;
use Illuminate\Database\Eloquent\Model;

class User extends Model {
    use HasImageUploads;
    
    // Mark columns as image fields
    protected static $imageFields = [
        'cover', 'avatar'
    ];
}

Install the package using composer to enable auto-upload, resize, and crop features for images in your Laravel application.

$ composer require qcod/laravel-imageup

The package configuration file controls global behavior for uploads, storage, and deletions. Key options include:

• upload_disk: The default Laravel storage disk (e.g., public).
• upload_directory: The directory within the disk where files are stored.
• auto_upload_images: Whether to automatically upload files from the request if field names match (default: true).
• auto_delete_images: Whether to automatically delete files from disk when the database record is deleted (default: true).
• resize_image_quality: The default JPEG/WebP quality for resized images.

return [
    'upload_disk' => 'public',
    'upload_directory' => 'uploads',
    'auto_upload_images' => true,
    'auto_delete_images' => true,
    'resize_image_quality' => 80
];

By default, files are saved using $file->hashName(). To use a custom naming convention, implement a method in your model following the pattern {fieldName}UploadFilePath.

Important: The method must return only the relative path from the disk. The method receives the uploaded $file object as an argument.

class User extends Model {
    use HasImageUploads;
    
    protected static $imageFields = ['cover', 'avatar'];
    
    // Override cover file name
    protected function coverUploadFilePath($file) {
        // Example: saves as 'uploads/1-cover-image.jpg'
        return $this->id . '-cover-image.jpg';
    }

    // Example using original filename
    protected function avatarUploadFilePath($file) {
        return $this->id . '-' . $file->getClientOriginalName();
    }
}

If you have disabled auto-upload (via protected $autoUploadImages = false;, $model->disableAutoUpload(), or field-specific settings), you can manually handle uploads using the following methods:

• $model->uploadImage($imageFile, $field = null): Uploads an image to the specified field. If $field is null, it uploads to the first image option defined in the model.
• $model->uploadFile($docFile, $field = null): Uploads a file to the specified field.

Important: If auto-upload is enabled, manual uploads may be overwritten by the auto-upload process during model save.

$user = User::findOrFail($id);
$user->uploadImage(request()->file('cover'), 'cover');
$user->uploadFile(request()->file('resume'), 'resume');

To display uploaded assets in your application:

• $model->imageUrl($field): Returns the URL string for the image in the specified field.
• $model->fileUrl($field): Returns the URL string for the file in the specified field.
• $model->imageTag($field, $attribute = ''): Returns a complete HTML <img> tag. You can pass an optional $attribute string (e.g., CSS classes) to the tag.

// Get URL
<img src="{{ $user->imageUrl('cover') }}" alt="" />

// Get HTML Tag with classes
{!! $model->imageTag('avatar', 'class="float-left mr-3"') !!}

You can override the image or file fields defined on your model at runtime using these methods:

• $model->setImagesField($fieldsOptions): Replaces the image fields configuration.
• $model->setFilesField($fieldsOptions): Replaces the file fields configuration.

Example configuration options include width, height, crop, and path.

$user = User::findOrFail($id);

$fieldOptions = [
    'cover' => [ 'width' => 1000 ],
    'avatar' => [ 'width' => 120, 'crop' => true ],    
];
$user->setImagesField($fieldOptions);

$fileFieldOption = [
    'resume' => ['path' => 'resumes']
];
$user->setFilesField($fileFieldOption);

You can perform image manipulation outside of the automatic upload flow:

• $model->resizeImage($imageFile, $fieldOptions): Resizes an existing image file or an uploaded file using provided options (e.g., width, crop). Returns the Intervention Image instance.
• $model->cropTo($x, $y)->resizeImage($imageFile, $field = null): Sets specific X and Y coordinates for cropping (useful for frontend cropping libraries) before resizing or uploading.

// Resize an existing file
$image = $user->resizeImage('/images/some-big-image.jpg', [ 'width' => 120, 'crop' => true ]);

// Crop and upload using coordinates from request
$coords = request()->only(['crop_x', 'crop_y']);
$user->cropTo($coords)->uploadImage(request()->file('cover'), 'avatar');