README

qcod/laravel-imageup 是一个特质，它为您提供了自动上传、缩放和裁剪图像功能，具有众多自定义选项。

安装

您可以通过 composer 安装此包

$ composer require qcod/laravel-imageup

包将自动注册自身。如果需要手动注册，可以在 config/app.php 提供者数组中添加它

QCod\ImageUp\ImageUpServiceProvider::class

您可以选择通过以下方式发布配置文件

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

它将创建包含所有设置的 config/imageup.php

入门

要使用此特质，只需在 Eloquent 模型上添加 use HasImageUploads 并定义所有需要存储在数据库中的图像字段。

模型

<?php
namespace App;

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

class User extends Model {
    use HasImageUploads;
    
    // assuming `users` table has 'cover', 'avatar' columns
    // mark all the columns as image fields 
    protected static $imageFields = [
        'cover', 'avatar'
    ];
}

一旦您在模型中标记了所有图像字段，它将在您通过 Model::saved() 事件保存模型时自动上传图像。它还将更新数据库中的新存储文件路径，如果在上传新图像后发现旧图像，则旧图像将被删除。

图像字段应在数据库表中以 VARCHAR 格式存储上传图像的路径。

控制器中

<?php
namespace App;
use App\Http\Controllers\Controller;

class UserController extends Controller {
    public function store(Request $request){
        return User::create($request->all());
    }
}

请确保运行 php artisan storage:link 以查看公共存储磁盘中的图像

就是这样，通过上述设置，当您通过 POST 请求调用 store 方法，并且请求中存在名为 cover 或 avatar 的文件时，它将自动上传。

上传字段选项

ImageUp 允许您在定义的字段选项中自定义上传和缩放的处理方式，以下是可以自定义的内容

<?php
namespace App;

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

class User extends Model {
    
    use HasImageUploads;
    
    // which disk to use for upload, can be override by field options 
    protected $imagesUploadDisk = 'local';
    
    // path in disk to use for upload, can be override by field options 
    protected $imagesUploadPath = 'uploads';
    
    // auto upload allowed 
    protected $autoUploadImages = true;
    
    // all the images fields for model
    protected static $imageFields = [
        'avatar' => [
            // width to resize image after upload
            'width' => 200,
            
            // height to resize image after upload
            'height' => 100,
            
            // set true to crop image with the given width/height and you can also pass arr [x,y] coordinate for crop.
            'crop' => true,
            
            // what disk you want to upload, default config('imageup.upload_disk')
            'disk' => 'public',
            
            // a folder path on the above disk, default config('imageup.upload_directory')
            'path' => 'avatars',
            
            // placeholder image if image field is empty
            'placeholder' => '/images/avatar-placeholder.svg',
            
            // validation rules when uploading image
            'rules' => 'image|max:2000',
            
            // override global auto upload setting coming from config('imageup.auto_upload_images')
            'auto_upload' => false,
            
            // if request file is don't have same name, default will be the field name
            'file_input' => 'photo',
            
            // if field (here "avatar") don't exist in database or you wan't this field in database
            'update_database' => false,
            
            // a hook that is triggered before the image is saved
            'before_save' => BlurFilter::class,
            
            // a hook that is triggered after the image is saved
            'after_save' => CreateWatermarkImage::class
        ],
        'cover' => [
            //...    
        ]
    ];
    
    // any other than image file type for upload
    protected static $fileFields = [
            'resume' => [
                // what disk you want to upload, default config('imageup.upload_disk')
                'disk' => 'public',
                
                // a folder path on the above disk, default config('imageup.upload_directory')
                'path' => 'docs',
                
                // validation rules when uploading file
                'rules' => 'mimes:doc,pdf,docx|max:1000',
                
                // override global auto upload setting coming from config('imageup.auto_upload_images')
                'auto_upload' => false,
                
                // if request file is don't have same name, default will be the field name
                'file_input' => 'cv',
                
                // a hook that is triggered before the file is saved
                'before_save' => HookForBeforeSave::class,
                
                // a hook that is triggered after the file is saved
                'after_save' => HookForAfterSave::class
            ],
            'cover_letter' => [
                //...    
            ]
        ];
}

自定义文件名

在某些情况下，您可能需要自定义保存的文件名。默认情况下，它将是 $file->hashName() 生成的哈希。

您可以通过在模型上添加一个方法来实现，该方法的命名规范为 {fieldName}UploadFilePath

class User extends Model {
    use HasImageUploads;
    
    // assuming `users` table has 'cover', 'avatar' columns
    // mark all the columns as image fields 
    protected static $imageFields = [
        'cover', 'avatar'
    ];
    
    // override cover file name
    protected function coverUploadFilePath($file) {
        return $this->id . '-cover-image.jpg';
    }
}

上述方法将始终将上传的封面图像保存为 uploads/1-cover-image.jpg。

请确保仅从覆盖方法返回相对路径。

请求文件将通过 $file 参数传递到该方法中，因此您可以根据需要获取扩展名或原始文件名等来构建文件名。

    // override cover file name
    protected function coverUploadFilePath($file) {
        return $this->id .'-'. $file->getClientOriginalName();
    }
    
    /** Some of methods on file */
    // $file->getClientOriginalExtension()
    // $file->getRealPath()
    // $file->getSize()
    // $file->getMimeType()

可用方法

您不仅限于使用自动上传图像功能。此特质还将提供以下方法，您可以使用它们来手动上传和缩放图像。

注意：请确保您已禁用自动上传，方法是在模型中设置 protected $autoUploadImages = false; 或动态调用 $model->disableAutoUpload()。您还可以通过调用 $model->setImagesField(['cover' => ['auto_upload' => false]]) 禁用特定字段的自动上传，否则您将看不到手动上传的图像，因为在模型保存时自动上传将覆盖它们。

$model->uploadImage($imageFile, $field = null) / $model->uploadFile($docFile, $field = null)

为给定的 $field 上传图像/文件，如果 $field 为空，则上传到数组中定义的第一个图像/文件选项。

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

$model->setImagesField($fieldsOptions) / $model->setFilesField($fieldsOptions)

您还可以通过调用 $model->setImagesField($fieldsOptions) / $model->setFilesField($fieldsOptions) 并传递字段选项动态设置图像/文件字段，这将替换在模型属性上定义的字段。

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

$fieldOptions = [
    'cover' => [ 'width' => 1000 ],
    'avatar' => [ 'width' => 120, 'crop' => true ],    
];

// override image fields defined on  model 
$user->setImagesField($fieldOptions);

$fileFieldOption = [
    'resume' => ['path' => 'resumes']
];

// override file fields defined on  model
$user->setFilesField($fileFieldOption);

$model->hasImageField($field) / $model->hasFileField($field)

检查字段是否定义为图像/文件字段。

$model->deleteImage($filePath) / $model->deleteFile($filePath)

删除任何存在的图像/文件。

$model->resizeImage($imageFile, $fieldOptions)

如果您已经有了图片，可以使用这个方法来使用与图片字段相同的选项来调整图片大小。

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

// resize image, it will give you resized image, you need to save it  
$imageFile = '/images/some-big-image.jpg';
$image = $user->resizeImage($imageFile, [ 'width' => 120, 'crop' => true ]);

// or you can use uploaded file
$imageFile = request()->file('avatar');
$image = $user->resizeImage($imageFile, [ 'width' => 120, 'crop' => true ]);

$model->cropTo($x, $y)->resizeImage($imageFile, $field = null)

您可以使用这个cropTo()方法来设置裁剪的x和y坐标。如果您从某种前端图片裁剪库中获取坐标，这将非常有用。

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

// uploaded file from request
$imageFile = request()->file('avatar');

// coordinates from request
$coords = request()->only(['crop_x', 'crop_y']);

// resizing will give you intervention image back
$image = $user->cropTo($coords)
    ->resizeImage($imageFile, [ 'width' => 120, 'crop' => true ]);

// or you can do upload and resize like this, it will override field options crop setting
$user->cropTo($coords)
    ->uploadImage(request()->file('cover'), 'avatar');

$model->imageUrl($field) / $model->fileUrl($field)

为指定的图片/文件字段提供上传文件的URL。

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

// in your view 
<img src="{{ $user->imageUrl('cover') }}" alt="" />
// http://www.example.com/storage/uploads/iGqUEbCPTv7EuqkndE34CNitlJbFhuxEWmgN9JIh.jpeg

$model->imageTag($field, $attribute = '')

它为您提供一个字段的<img />标签。

{!! $model->imageTag('avatar') !!}
<!-- <img src="http://www.example.com/storage/uploads/iGqUEbCPTv7EuqkndE34CNitlJbFhuxEWmgN9JIh.jpeg" /> -->

{!! $model->imageTag('avatar', 'class="float-left mr-3"') !!}
<!-- <img src="http://www.example.com/storage/uploads/iGqUEbCPTv7EuqkndE34CNitlJbFhuxEWmgN9JIh.jpeg" class="float-left mr-3 /> -->

钩子

钩子允许您在图片保存之前或之后应用不同的自定义或任何其他逻辑。

定义类型

您可以通过指定一个类名来定义钩子。

protected static $imageFields = [
    'avatar' => [
        'before_save' => BlurFilter::class,
    ],
    'cover' => [
        //...    
    ]
];

钩子类必须有一个名为handle的方法，当钩子被触发时将调用此方法。干预图像的一个实例将被传递给handle方法。

class BlurFilter {
    public function handle($image) {
        $image->blur(10);
    }
}

基于类的钩子通过Laravel ioc容器解析，这允许您通过构造函数注入任何依赖。

请注意，如果您已定义带有width或height的字段选项，您将在before和after保存钩子处理程序中获取调整大小后的图片。当然，您可以在任何需要时从request()->file('avatar')获取原始图片。

钩子定义的另一种类型是回调钩子。

$user->setImagesField([
    'avatar' => [
        'before_save' => function($image) {
            $image->blur(10);
        },
    ],
    'cover' => [
        //...    
    ]
]);

回调将接收干预图像实例参数。

钩子类型

有两种类型的钩子：before_save和after_save钩子。

before_save钩子在图片保存到磁盘之前被调用。在钩子内对干预图像实例所做的任何更改都将应用于输出图片。

$user->setImagesField([
    'avatar' => [
        'width' => 100,
        'height' => 100,
        'before_save' => function($image) {
            // The image will be 50 * 50, this will override the 100 * 100 
            $image->resize(50, 50);
        },
    ]
]);

after_save钩子在图片保存到磁盘后立即被调用。

$user->setImagesField([
    'logo' => [
        'after_save' => function($image) {
            // Create a watermark image and save it
        },
    ]
]);

配置文件

<?php

return [

    /**
     * Default upload storage disk
     */
    'upload_disk' => 'public',

    /**
     * Default Image upload directory on the disc
     * eg. 'uploads' or 'user/avatar'
     */
    'upload_directory' => 'uploads',

    /**
     * Auto upload images from incoming Request if same named field or
     * file_input field on option present upon model update and create.
     * can be override in individual field options
     */
    'auto_upload_images' => true,

    /**
     * It will auto delete images once record is deleted from database
     */
    'auto_delete_images' => true,

    /**
     * Set an image quality
     */
    'resize_image_quality' => 80
];

变更日志

有关最近更改的更多信息，请参阅CHANGELOG。

测试

该包包含一些集成/烟雾测试，使用Orchestra设置，可以通过phpunit运行这些测试。

$ composer test

贡献

有关详细信息，请参阅CONTRIBUTING。

安全性

如果您发现任何安全相关的问题，请通过电子邮件saquibweb@gmail.com报告，而不是使用问题跟踪器。

鸣谢

• Mohd Saqueib Ansari
• Melek Rebai aka shadoWalker89
• João Roberto P. Borges

关于QCode.in

QCode.in (https://www.qcode.in) 是Saqueib的博客，涵盖关于全栈Web开发的各个方面。

许可证

MIT许可证（MIT）。有关更多信息，请参阅许可证文件。