README

一个主要为 Laravel 开发的 PHP 包，用于使用 Ajax 管理上传图像并显示缩略图。
(这是为 Laravel 5+ 开发的。针对 Laravel 4.2)

(示例)

需求

安装

在 composer.json 中添加此包名

"require": {
  "sukohi/surpass": "2.*"
}

执行 composer 命令。

composer update

在 app.php 中注册服务提供者

'providers' => [
    ...Others...,  
    Sukohi\Surpass\SurpassServiceProvider::class,
]

同时别名

'aliases' => [
    ...Others...,  
    'Surpass'   => Sukohi\Surpass\Facades\Surpass::class
]

然后执行以下命令。

php artisan vendor:publish  
php artisan migrate

注意：如果在更新后出现错误，请执行以下操作。

php artisan vendor:publish --force
php artisan migrate:rollback
php artisan migrate

使用方法

基本用法

$path = 'img/uploads'; // The folder to save images.    
$dir = 'dir_name'; // The directory name to save images.  
$surpass = \Surpass::path($path)->dir($dir);

(请参阅名为 "exaple" 的文件夹，其中包含一些文件。)

上传 (在控制器中)

$surpass = \Surpass::path('img/uploads')
				->dir('dir_name')
				->ids([
					'input' => 'image_upload',
					'preview' => 'preview_images'
				])
				->maxFiles(5)
				->alert('You can upload up to %d files.')
				->formData([
					'key_1' => 'value_1', 
					'key_2' => 'value_2', 
					'key_3' => 'value_3'
				])
				->preview(['maxHeight' => 120])
				->css([
					'div' => 'div_class', 
					'button' => 'button_class', 
					'preview' => 'preview_class', 
					'loading' => 'loading_class'
				])
				->progress('<img src="http://example.com/img/ajax-loader.gif"><br>Uploading..')
				->callback([
					'upload' => 'alert("Uploading..");', 
					'done' => 'alert("Done.");',
					'failed' => 'alert("Failed..");', 
					'remove' => 'alert("Removed");', 
					'load' => 'alert("Loading..");',
                    'timeout' => 'alert("Timeout..");',
                    'file_type_error' => 'alert("Only image files are allowed");'
				])
				->timeout(3000) // 3 seconds
				->overwrite(false)   // When using overwriting-mode
				->resize(['maxWidth' => '100', 'maxHeight' => '50'], $force_crop = false)   // Client Resizing(See "About resizing")
				->dropZone('drop_zone_id')  // See "Drop Zone"
				->button('Remove');
$surpass->load([1, 2, 3]);    // These are IDs of DB that you saved image(s) in the past.

return view('surpass', [
		
	'surpass' => $surpass
		
]);

*注意：方法 dir('dir_name') 不能再接收 "/" 和 "." 以防止目录遍历攻击。

上传 (在视图中)

注意1
需要加载 jQuery、jQuery UI 和 jQuery-File-Upload。 (加载顺序很重要。见下文)
如果可以使用 bower，请使用 bower install blueimp-file-upload --save-dev 命令轻松安装所有包。

注意2
将前一个版本中的标签 {{ 和 }} 改为 !!{ 和 !!}。

@section('content')

    <form>
    	<input 
    		id="image_upload" 
    		name="image_upload" 
    		title="Select Image" 
    		data-url="http://example.com/upload" 
    		data-remove-url="http://example.com/remove" 
    		accept="image/*" 
    		type="file" multiple>
    		
        <!-- Preview(s) will be displayed here -->
        {!! $surpass->html('preview') !!}
    </form>
@stop

@section('script')

    <!-- Load required JS libraries. -->
    <script src="bower_components/jquery/dist/jquery.min.js"></script>
    <script src="bower_components/blueimp-file-upload/js/vendor/jquery.ui.widget.js"></script>
    <script src="bower_components/blueimp-load-image/js/load-image.all.min.js"></script>
    <script src="bower_components/blueimp-canvas-to-blob/js/canvas-to-blob.js"></script>
    <script src="bower_components/blueimp-file-upload/js/jquery.iframe-transport.js"></script>
    <script src="bower_components/blueimp-file-upload/js/jquery.fileupload.js"></script>
    <script src="bower_components/blueimp-file-upload/js/jquery.fileupload-process.js"></script>
    <script src="bower_components/blueimp-file-upload/js/jquery.fileupload-image.js"></script>
    <script src="bower_components/blueimp-tmpl/js/tmpl.min.js"></script>

    <!-- JS code (including <script></script> tag) will be displayed here. -->
    {!! $surpass->html('js') !!}
@stop

上传 (Ajax)

*重要：要保存您想要的图像，您需要提前创建一个特定的目录，该目录必须是可写的。

// To save an image and its data into DB

$surpass = \Surpass::path('img/uploads')->id('input', 'image_upload');
$attributes = array('alt' => 'alt_value', 'title' => 'title_value');  // Optional
$save_dir = $surpass->saveDir();    // The directory you want to save.(Optional)
$surpass->renameFiles(true);    // If you'd like to use the original filename, set false.(Optional)

if($surpass->save($attributes = array())) {

    // You can get the data of saved image like this.

	$load_item = $surpass->loadSaved();
	$id = $load_item->id;
	$dir = $load_item->dir;
	$filename = $load_item->filename;
	$path = $load_item->path;
	$url = $load_item->url;
	$attributes = $load_item->attributes;
	$tag = $load_item->tag;
	
	// You can save attributes also here. (Of course you can do that at other places.)
	
	$id = $load_item->id;
	$surpass->saveAttributes($id, array(
	    'key_1' => 'value_1',
	    'key_2' => 'value_2',
	    'key_3' => 'value_3'
	));
	
}

return $surpass->result();  // This will return json.

*注意1：如果上传完成，结果数据(json)有以下值。
*注意2：有关 renameFiles()，请参阅详细信息

result (true / false)
insertId
path
dir
filename
file_path
extension
width
height
mime_type
saveMode : (overwrite / insert)

删除 (Ajax)

// To remove an image and the data into DB

$surpass = \Surpass::path('img/uploads');

if($surpass->remove()) {
	// Something..
}

return $surpass->result();  // This will return json.

最简单的方法

(在控制器中)

$surpass = \Surpass::path('img/uploads')->dir('dir_name');
$surpass->load([1, 2, 3]);

(在视图中) 请参阅上方。

(在上传 Ajax 中)

$surpass = \Surpass::path('img/uploads');
$dir = $surpass->requestDir();

if($surpass->save()) {
	// Something..
}

return $surpass->result();

(在删除 Ajax 中)

$surpass = \Surpass::path('img/uploads');

if($surpass->remove()) {
	// Something..
}

return $surpass->result();

刷新
此方法将删除所有已存在的数据和图像。

$surpass = \Surpass::path('img/uploads');
$surpass->refresh();

通过 ID 删除

$surpass = \Surpass::path('img/uploads')->removeById(1);


// or


$surpass = \Surpass::path('img/uploads')->removeById([1, 2, 3]);

带验证加载

$ids = [1, 2, 3];
$surpass->load($ids, $old_flag = true);
// If $old_flag is true, $ids will be replaced with Input::old() value(s) automatically.

在提交时获取图像文件 ID(s)

\Surpass::imageFileId('dir_name');
\Surpass::imageFileIds('dir_name');

关于已保存的 ID

在使用 Ajax 上传图像(s)之后，预览(s)中隐藏的输入标签名称为 "surpass_ids[]" (当然，值是当时在数据库中保存的 ID)。
因此，在提交时，您可以将这些数据作为数组接收。

现在，您可以使用 imageFileId() 和 imageFileIds() 简单地获取图像 ID(s)。

使用多个文件输入
(在控制器中)

$surpass = \Surpass::path('img/uploads');
$surpass_x = clone $surpass->dir('xxx')
				->ids([
					'input' => 'input-xxx',
					'preview' => 'preview-xxx'
				]);
$surpass_y = clone $surpass->dir('yyy')
				->ids([
					'input' => 'input-yyy',
					'preview' => 'preview-yyy'
				]);
return view('view', [
	'surpass_x' => $surpass_x,
	'surpass_y' => $surpass_y
]);

(在视图中)

<input 
	id="input-xxx" 
	name="input-xxx" 
	title="Select Image" 
	data-url="http://example.com/upload" 
	data-remove-url="http://example.com/remove" 
	accept="image/*" 
	type="file" multiple>
{!! $surpass_x->html('preview') !!}  

<input 
	id="input-yyy" 
	name="input-yyy" 
	title="Select Image" 
	data-url="http://example.com/upload" 
	data-remove-url="http://example.com/remove" 
	accept="image/*" 
	type="file" multiple>
{!! $surpass_y->html('preview') !!}  

// JS
{!! $surpass_x->html('js') !!}
{!! $surpass_y->html('js') !!}

设置文件名长度

\Surpass::filenameLength(10);    // Default: 10

插入

注意
此方法是将图像及其数据直接保存，类似于播种。
因此，通常您应使用 save() 方法。

$insert_id = \Surpass::path('path')
                ->dir('dir')
                ->insert('file_path', $attributes = []);

拖放区域

如果您想通过拖放上传图像，请添加以下 div 标签。

(in Controller)

$surpass->dropZone('drop_zone_id');


(in View)

<div id="drop_zone_id">Drop images here!</div>

保存属性

$id = 1;    // Here means ID of "image_files" table.
$surpass->saveAttributes($id, [
    'key_1' => 'value_1',
    'key_2' => 'value_2',
    'key_3' => 'value_3'
]);

*Note: The old attributes data will be removed.

方法

path($path)

保存图像的路径。
dir($dir)

保存图像的目录。 (实际图像文件路径为 $path .'.'. $dir .'****.')
ids($ids)

您希望为HTML输入标签设置的ID。您可以设置以下ID名称。
- input
- preview
此方法为可选。 (如果您需要多个图像上传，请使用此方法。) (默认：input -> image_upload, preview -> preview_images)

例如) \Surpass::ids([ 'input' => 'image_upload', 'preview' => 'preview_images' ]);
maxFiles($max_file)

上传的图像文件的最大数量。此方法为可选。(默认: 5)
alert($message)

当上传的图像数量达到最大值时的消息。

例如) \Surpass::alert('您可以上传最多 %d 个文件.'); 此方法为可选。(默认: "您可以上传最多 %d 个文件。")
formData($values)

将通过Ajax上传请求包含的附加数据。

例如) \Surpass::formData([ 'key_1' => 'value_1', 'key_2' => 'value_2', 'key_3' => 'value_3' ]);

此方法为可选。
preview($preview_options)

预览的选项，如宽度、高度等。请参阅这里。

例如) \Surpass::preview(['maxHeight' => 120]);

此方法为可选。
css($css_values)

将设置到特定元素的CSS值。您可以设置以下类型。
- preview : 包含所有元素的div元素。
- div : 包含单个图像预览的div元素。
- loading : 包含加载消息的div元素。
- button : 用于删除或覆盖的按钮元素。
例如) css([ 'div' => 'div_class', 'button' => 'button_class', 'preview' => 'preview_class', 'loading' => 'loading_class' ])

此方法为可选。
progress($loading_message)

上传图像时显示的内容。

例如) \Surpass::progress('上传中..')

此方法为可选。(如果您跳过此方法，则不显示加载消息。)
callback($callbacks)

JavaScript的回调值。您可以设置以下回调。

upload : 上传图像时调用。done : 上传完成后调用。failed : 上传失败时调用。remove : 删除预览时调用。load : 加载图像时调用。timeout : 上传超时时调用。file_type_error : 选择文件不是图像时调用。

例如)
\Surpass::callback([ 'upload' => 'console.log(data);', 'done' => 'console.log(data);', 'failed' => 'console.log(data);', 'remove' => 'console.log(data);', 'load' => 'console.log(data);', 'timeout' => 'console.log(data);', 'file_type_error' => 'console.log(data);' ]);

除了"remove"，可以使用"console.log(e);" 此方法为可选。
timeout($seconds)

超时的秒数。此方法为可选。

例如) \Surpass::timeout(3000);
overwrite($boolean)

是否使用覆盖模式的设置。在覆盖模式下，您不能删除图像。此方法为可选。
resize($options, $force_crop = false)

客户端缩放的设置。您可以设置以下类型。
- maxWidth
- maxHeight
请参阅这里。
- 如果$force_crop为true，则添加imageCrop。
请参阅这里。

此方法为可选。
dropZone($drop_zone_id)

如果您想要通过拖放上传。$drop_zone_id是指类似于以下HTML元素的ID。
拖放区域
此方法为可选。
button($label)

将显示在删除(覆盖)按钮上的文本。此方法为可选。(默认: 删除)
load($ids)

(如果$ids为空的情况)

此方法将在重定向输入数据时自动使用Input::old('***')显示预览。

(如果$ids不为空的情况)

如果您希望默认显示特定的预览，请使用此方法。$ids是指数据库中图像文件的ID。

Surpass::renameFiles($bool = true)
通过此方法，您可以选择在保存时文件名是否由随机决定。(可选)
- 如果 $bool 为 true，文件名将随机决定。
- 如果 $bool 为 false，文件名将与原始文件名相同。
然而，如果已存在相同的文件，将会添加增量数字，如 filename-1.jpg。
```
  $surpass = Surpass::path('YOUR_PATH');
  $surpass->renameFiles(false);
  
  if($surpass->save()) {
  
      // Something..
  
  }
```

配置

执行 vendor:publish 后，您在 /config 中将有一个名为 surpass.php 的配置文件。
在那里，您可以更改 Surpass 将使用的表名。

注意：为了稳定的数据库设计，您的数据库中的实际表名将不会自动更改。
因此，为了重命名，您需要生成一个迁移文件，并在配置文件中设置新的表名后执行它。
更多详细信息，请参阅重命名 / 删除表或 examples/migrations/2016_04_03_063049_rename_image_files_to_thumbnail_files.php。

特别感谢

感谢大家的贡献！

许可协议

本软件包采用 MIT 许可协议许可。

sukohi / surpass

维护者

详细信息

README

需求

安装

使用方法

方法

配置

特别感谢

许可协议