A PHP package mainly developed for Laravel to manage uploading images using Ajax and displaying thumbnails.
(This is for Laravel 5+. For Laravel 4.2)
(Example)
Add this package name in composer.json
"require": {
"sukohi/surpass": "2.*"
}
Execute composer command.
composer update
Register the service provider in app.php
'providers' => [
...Others...,
Sukohi\Surpass\SurpassServiceProvider::class,
]
Also alias
'aliases' => [
...Others...,
'Surpass' => Sukohi\Surpass\Facades\Surpass::class
]
And execute the next commands.
php artisan vendor:publish
php artisan migrate
Note: If you get errors after updating, execute the next.
php artisan vendor:publish --force
php artisan migrate:rollback
php artisan migrate
Basic Usage
$path = 'img/uploads'; // The folder to save images.
$dir = 'dir_name'; // The directory name to save images.
$surpass = \Surpass::path($path)->dir($dir);
(See also a folder named "exaple" which has some files.)
Upload (in Controller)
$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
]);
*Note: method dir('dir_name') can no longer receive "/" and "." to protect from directory traversal attack.
Upload (in View)
Note1:
Need to load jQuery, jQuery UI and jQuery-File-Upload. (Loading order is important. See the below)
If you can use bower, use bower install blueimp-file-upload --save-dev
to install all of the packages easily.
Note2:
Changed tags {{
and }}
to {!!
and !!}
from the previous version.
@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="https://github.com/SUKOHI/Surpass/raw/master/bower_components/jquery/dist/jquery.min.js"></script>
<script src="https://github.com/SUKOHI/Surpass/raw/master/bower_components/blueimp-file-upload/js/vendor/jquery.ui.widget.js"></script>
<script src="https://github.com/SUKOHI/Surpass/raw/master/bower_components/blueimp-load-image/js/load-image.all.min.js"></script>
<script src="https://github.com/SUKOHI/Surpass/raw/master/bower_components/blueimp-canvas-to-blob/js/canvas-to-blob.js"></script>
<script src="https://github.com/SUKOHI/Surpass/raw/master/bower_components/blueimp-file-upload/js/jquery.iframe-transport.js"></script>
<script src="https://github.com/SUKOHI/Surpass/raw/master/bower_components/blueimp-file-upload/js/jquery.fileupload.js"></script>
<script src="https://github.com/SUKOHI/Surpass/raw/master/bower_components/blueimp-file-upload/js/jquery.fileupload-process.js"></script>
<script src="https://github.com/SUKOHI/Surpass/raw/master/bower_components/blueimp-file-upload/js/jquery.fileupload-image.js"></script>
<script src="https://github.com/SUKOHI/Surpass/raw/master/bower_components/blueimp-tmpl/js/tmpl.min.js"></script>
<!-- JS code (including <script></script> tag) will be displayed here. -->
{!! $surpass->html('js') !!}
@stop
Upload (Ajax)
*Important: To save images you want, you need to make a specific dir which must be writable in advance.
// 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.
Note 1: If uploading completed, the result data(json) has the following values.
Note 2: About renameFiles(), See the details
Remove (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.
Minimal Way
(in Contoller)
$surpass = \Surpass::path('img/uploads')->dir('dir_name');
$surpass->load([1, 2, 3]);
(in View) See above.
(in Upload Ajax)
$surpass = \Surpass::path('img/uploads');
$dir = $surpass->requestDir();
if($surpass->save()) {
// Something..
}
return $surpass->result();
(in Remove Ajax)
$surpass = \Surpass::path('img/uploads');
if($surpass->remove()) {
// Something..
}
return $surpass->result();
Refresh
This method will remove all data and images that don't already exist.
$surpass = \Surpass::path('img/uploads');
$surpass->refresh();
Remove by ID
$surpass = \Surpass::path('img/uploads')->removeById(1);
// or
$surpass = \Surpass::path('img/uploads')->removeById([1, 2, 3]);
Load with validation
$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.
Get image file id(s) when submitting
\Surpass::imageFileId('dir_name');
\Surpass::imageFileIds('dir_name');
About Saved IDs
Afeter uploading image(s) with Ajax, the preview(s) have hidden-input-tag(s) named "surpass_ids[]" (and of course the value(s) are ID of DB saved at the time).
So when submitting, you can receive those data as array.
Now You can use imageFileId() and imageFileIds() to get image ID(s) easily.
with Multiple file-inputs
(in Controller)
$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
]);
(in View)
<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') !!}
Set filename length
\Surpass::filenameLength(10); // Default: 10
Insert
Note:
This method is to save image(s) and their data directly like seeding.
So, in usual you should use save() method.
$insert_id = \Surpass::path('path')
->dir('dir')
->insert('file_path', $attributes = []);
Drop Zone
If you'd like to upload images through Drop Zone(using Drag and Drop), add a div-tag like the below.
(in Controller)
$surpass->dropZone('drop_zone_id');
(in View)
<div id="drop_zone_id">Drop images here!</div>
Save Attributes
$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)
The path to save images.
dir($dir)
The directory to save images. (The actual image file path is $path .'.'. $dir .'****.')
ids($ids)
The IDs that you'd like to set for HTML input tags. You can set the following ID names.
This method is optional. (If you need multiple image uploads, use this method.) (Default: input -> image_upload, preview -> preview_images)
e.g.) \Surpass::ids([ 'input' => 'image_upload', 'preview' => 'preview_images' ]);
maxFiles($max_file)
The maximum number of image files to upload. This method is optional.(Default: 5)
alert($message)
The message for when the count of the number of the images uploaded reach a maximum.
e.g) \Surpass::alert('You can upload up to %d files.'); This method is optional.(Default: "You can upload up to %d files.")
formData($values)
The additional data that will be included uploading request through Ajax.
e.g) \Surpass::formData([ 'key_1' => 'value_1', 'key_2' => 'value_2', 'key_3' => 'value_3' ]);
This method is optional.
preview($preview_options)
The options for preview like width, height and so on. See here.
e.g) \Surpass::preview(['maxHeight' => 120]);
This method is optional.
css($css_values)
The css values that will be set to specific elements. You can set the following types.
e.g.) css([ 'div' => 'div_class', 'button' => 'button_class', 'preview' => 'preview_class', 'loading' => 'loading_class' ])
This method is optional.
progress($loading_message)
The content displayed when uploading an image.
e.g.) \Surpass::progress('Uploading..')
This method is optional.(If you skip this method, loading message not displayed.)
callback($callbacks)
The callback values for JavaScript. You can set the following callbacks.
upload : called when uploading an image. done : called when uploading completed. failed : called when uploading failed. remove : called when an preview removed. load : called when loading an image. timeout : called when uploading is timeout. file_type_error : called when selected file is not image.
e.g.)
\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);'
]);
Except "remove" can use "console.log(e);" This method is optional.
timeout($seconds)
The seconds for timeout. This method is optional.
e.g.) \Surpass::timeout(3000);
overwrite($boolean)
A setting whether to use overwrite-mode. In overwrite-mode you can't remove images. This method is optional.
resize($options, $force_crop = false)
Settings for client resizing. You can set the following types.
See here.
See here.
This method is optional.
dropZone($drop_zone_id)
If you'd like to upload by drag-and-drop. $drop_zone_id refers to ID of HTML element like the following.
This method is optional.
button($label)
The text that will be displayed on the Remove(Overwrite) button. This method is optional.(Default: Remove)
load($ids)
(In a case of that $ids
is empty)
This method will automatically display previews using Input::old('***') when redirecting with input data.
(In a case that $ids
is not empty)
If you'd like to display specific preview(s) by default, use this method. $ids refers to IDs of image_files from DB.
Surpass::renameFiles($bool = true)
By this method, you can choose whether file name will be decided randomly or not when saving.(Optional)
true
, file name will be decided randomly.false
, file name will be the same with the original file name. However, if the same file already exists, incremental number will be added like filename-1.jpg
.
$surpass = Surpass::path('YOUR_PATH');
$surpass->renameFiles(false);
if($surpass->save()) {
// Something..
}
After executing vendor:publish
, you have a configuration file called surpass.php
in /config.
In there, you can change table name that Surpass will use.
Note: For stable DB design, the actual table name in your database will NOT be changed automatically.
So, in order to rename, you need to generate a migration file and to execute it after setting the new table name in the configuration file.
For more details, see Renaming / Dropping Tables
or
examples/migrations/2016_04_03_063049_rename_image_files_to_thumbnail_files.php
.
Thank you guys for your contributions!
This package is licensed under the MIT License.
Copyright 2014 Sukohi Kuhoh