2017 © Pedro Peláez
 

library surpass

A PHP package mainly developed for Laravel to manage uploading images using Ajax and displaying thumbnail.

image

sukohi/surpass

A PHP package mainly developed for Laravel to manage uploading images using Ajax and displaying thumbnail.

  • Tuesday, January 31, 2017
  • by Sukohi
  • Repository
  • 4 Watchers
  • 31 Stars
  • 2,617 Installations
  • PHP
  • 0 Dependents
  • 0 Suggesters
  • 8 Forks
  • 7 Open issues
  • 19 Versions
  • 2 % Grown

The README.md

Surpass

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), (*1)

Demo, (*2)

(Example)
'Kitsilano', (*3)

Requirements

Installation

Add this package name in composer.json, (*4)

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

Execute composer command., (*5)

composer update

Register the service provider in app.php, (*6)

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

Also alias, (*7)

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

And execute the next commands., (*8)

php artisan vendor:publish  
php artisan migrate

Note: If you get errors after updating, execute the next., (*9)

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

Usage

Basic Usage, (*10)

$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.), (*11)

Upload (in Controller), (*12)

$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., (*13)

Upload (in View), (*14)

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., (*15)

Note2:
Changed tags {{ and }} to {!! and !!} from the previous version., (*16)

@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

Upload (Ajax), (*17)

*Important: To save images you want, you need to make a specific dir which must be writable in advance., (*18)

// 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, (*19)

  1. result (true / false)
  2. insertId
  3. path
  4. dir
  5. filename
  6. file_path
  7. extension
  8. width
  9. height
  10. mime_type
  11. saveMode : (overwrite / insert)

Remove (Ajax), (*20)

// 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, (*21)

(in Contoller), (*22)

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

(in View) See above., (*23)

(in Upload Ajax), (*24)

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

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

return $surpass->result();

(in Remove Ajax), (*25)

$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., (*26)

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

Remove by ID, (*27)

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


// or


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

Load with validation, (*28)

$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, (*29)

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

About Saved IDs, (*30)

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., (*31)

Now You can use imageFileId() and imageFileIds() to get image ID(s) easily., (*32)

with Multiple file-inputs
(in Controller), (*33)

$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), (*34)

<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, (*35)

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

Insert, (*36)

Note:
This method is to save image(s) and their data directly like seeding.
So, in usual you should use save() method., (*37)

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

Drop Zone, (*38)

If you'd like to upload images through Drop Zone(using Drag and Drop), add a div-tag like the below., (*39)

(in Controller)

$surpass->dropZone('drop_zone_id');


(in View)

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

Save Attributes, (*40)

$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.

Methods

  • path($path), (*41)

    The path to save images., (*42)

  • dir($dir), (*43)

    The directory to save images. (The actual image file path is $path .'.'. $dir .'*******.***'), (*44)

  • ids($ids), (*45)

    The IDs that you'd like to set for HTML input tags. You can set the following ID names., (*46)

    • input
    • preview

    This method is optional. (If you need multiple image uploads, use this method.) (Default: input -> image_upload, preview -> preview_images), (*47)

    e.g.) \Surpass::ids([ 'input' => 'image_upload', 'preview' => 'preview_images' ]);, (*48)

  • maxFiles($max_file), (*49)

    The maximum number of image files to upload. This method is optional.(Default: 5), (*50)

  • alert($message), (*51)

    The message for when the count of the number of the images uploaded reach a maximum., (*52)

    e.g) \Surpass::alert('You can upload up to %d files.'); This method is optional.(Default: "You can upload up to %d files."), (*53)

  • formData($values), (*54)

    The additional data that will be included uploading request through Ajax., (*55)

    e.g) \Surpass::formData([ 'key_1' => 'value_1', 'key_2' => 'value_2', 'key_3' => 'value_3' ]);, (*56)

    This method is optional., (*57)

  • preview($preview_options), (*58)

    The options for preview like width, height and so on. See here., (*59)

    e.g) \Surpass::preview(['maxHeight' => 120]);, (*60)

    This method is optional., (*61)

  • css($css_values), (*62)

    The css values that will be set to specific elements. You can set the following types., (*63)

    • preview : for div element containing all elements.
    • div : for div element containing an individual image preview.
    • loading : for div element containing a loading message.
    • button : for button element to remove or overwrite.

    e.g.) css([ 'div' => 'div_class', 'button' => 'button_class', 'preview' => 'preview_class', 'loading' => 'loading_class' ]), (*64)

    This method is optional., (*65)

  • progress($loading_message), (*66)

    The content displayed when uploading an image., (*67)

    e.g.) \Surpass::progress('Uploading..'), (*68)

    This method is optional.(If you skip this method, loading message not displayed.), (*69)

  • callback($callbacks), (*70)

    The callback values for JavaScript. You can set the following callbacks., (*71)

    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., (*72)

    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);' ]);, (*73)

    Except "remove" can use "console.log(e);" This method is optional., (*74)

  • timeout($seconds), (*75)

    The seconds for timeout. This method is optional., (*76)

    e.g.) \Surpass::timeout(3000);, (*77)

  • overwrite($boolean), (*78)

    A setting whether to use overwrite-mode. In overwrite-mode you can't remove images. This method is optional., (*79)

  • resize($options, $force_crop = false), (*80)

    Settings for client resizing. You can set the following types., (*81)

    • maxWidth
    • maxHeight

    See here., (*82)

    • If $force_crop is true, imageCrop added.

    See here., (*83)

    This method is optional., (*84)

  • dropZone($drop_zone_id), (*85)

    If you'd like to upload by drag-and-drop. $drop_zone_id refers to ID of HTML element like the following., (*86)

    Drop Zone

    This method is optional., (*87)

  • button($label), (*88)

    The text that will be displayed on the Remove(Overwrite) button. This method is optional.(Default: Remove), (*89)

  • load($ids), (*90)

    (In a case of that $ids is empty), (*91)

    This method will automatically display previews using Input::old('***') when redirecting with input data., (*92)

    (In a case that $ids is not empty), (*93)

    If you'd like to display specific preview(s) by default, use this method. $ids refers to IDs of image_files from DB., (*94)

, (*95)

  • Surpass::renameFiles($bool = true)
    By this method, you can choose whether file name will be decided randomly or not when saving.(Optional), (*96)

    • If $bool is true, file name will be decided randomly.
    • If $bool is 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., (*97)

    $surpass = Surpass::path('YOUR_PATH');
$surpass->renameFiles(false);

if($surpass->save()) {

    // Something..

}

Configuration

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., (*98)

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., (*99)

Special thanks

Thank you guys for your contributions!, (*100)

License

This package is licensed under the MIT License., (*101)

Copyright 2014 Sukohi Kuhoh, (*102)

The Versions

31/01 2017

dev-master

9999999-dev

A PHP package mainly developed for Laravel to manage uploading images using Ajax and displaying thumbnail.

  Sources   Download

MIT

The Requires

 

by Avatar Sukohi

31/01 2017

2.0.x-dev

2.0.9999999.9999999-dev

A PHP package mainly developed for Laravel to manage uploading images using Ajax and displaying thumbnail.

  Sources   Download

MIT

The Requires

 

by Avatar Sukohi

31/01 2017

2.0.7

2.0.7.0

A PHP package mainly developed for Laravel to manage uploading images using Ajax and displaying thumbnail.

  Sources   Download

MIT

The Requires

 

by Avatar Sukohi

03/04 2016

2.0.6

2.0.6.0

A PHP package mainly developed for Laravel to manage uploading images using Ajax and displaying thumbnail.

  Sources   Download

MIT

The Requires

 

by Avatar Sukohi

28/01 2016

2.0.5

2.0.5.0

A PHP package mainly developed for Laravel to manage uploading images using Ajax and displaying thumbnail.

  Sources   Download

MIT

The Requires

 

by Avatar Sukohi

28/01 2016

1.0.x-dev

1.0.9999999.9999999-dev

A PHP package mainly developed for Laravel to manage uploading images using Ajax and displaying thumbnail.

  Sources   Download

MIT

The Requires

 

by Avatar Sukohi

28/01 2016

1.0.7

1.0.7.0

A PHP package mainly developed for Laravel to manage uploading images using Ajax and displaying thumbnail.

  Sources   Download

MIT

The Requires

 

by Avatar Sukohi

28/01 2016

1.0.6

1.0.6.0

A PHP package mainly developed for Laravel to manage uploading images using Ajax and displaying thumbnail.

  Sources   Download

MIT

The Requires

 

by Avatar Sukohi

28/01 2016

1.0.5

1.0.5.0

A PHP package mainly developed for Laravel to manage uploading images using Ajax and displaying thumbnail.

  Sources   Download

MIT

The Requires

 

by Avatar Sukohi

27/01 2016

2.0.4

2.0.4.0

A PHP package mainly developed for Laravel to manage uploading images using Ajax and displaying thumbnail.

  Sources   Download

MIT

The Requires

 

by Avatar Sukohi

27/01 2016

1.0.4

1.0.4.0

A PHP package mainly developed for Laravel to manage uploading images using Ajax and displaying thumbnail.

  Sources   Download

MIT

The Requires

 

by Avatar Sukohi

25/09 2015

2.0.3

2.0.3.0

A PHP package mainly developed for Laravel to manage uploading images using Ajax and displaying thumbnail.

  Sources   Download

MIT

The Requires

 

by Avatar Sukohi

19/08 2015

1.0.1

1.0.1.0

A PHP package mainly developed for Laravel to manage uploading images using Ajax and displaying thumbnail.

  Sources   Download

MIT

The Requires

 

by Avatar Sukohi

19/08 2015

1.0.2

1.0.2.0

A PHP package mainly developed for Laravel to manage uploading images using Ajax and displaying thumbnail.

  Sources   Download

MIT

The Requires

 

by Avatar Sukohi

19/08 2015

1.0.3

1.0.3.0

A PHP package mainly developed for Laravel to manage uploading images using Ajax and displaying thumbnail.

  Sources   Download

MIT

The Requires

 

by Avatar Sukohi

06/08 2015

2.0.2

2.0.2.0

A PHP package mainly developed for Laravel to manage uploading images using Ajax and displaying thumbnail.

  Sources   Download

MIT

The Requires

 

by Avatar Sukohi

06/08 2015

2.0.1

2.0.1.0

A PHP package mainly developed for Laravel to manage uploading images using Ajax and displaying thumbnail.

  Sources   Download

MIT

The Requires

 

by Avatar Sukohi

06/08 2015

2.0.0

2.0.0.0

A PHP package mainly developed for Laravel to manage uploading images using Ajax and displaying thumbnail.

  Sources   Download

MIT

The Requires

 

by Avatar Sukohi

05/08 2015

1.0.0

1.0.0.0

A PHP package mainly developed for Laravel to manage uploading images using Ajax and displaying thumbnail.

  Sources   Download

MIT

The Requires

 

by Avatar Sukohi