PHPackages sukohi/surpass - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Image & Media](/categories/media) 4. / 5. sukohi/surpass ActiveLibrary[Image & Media](/categories/media) sukohi/surpass ============== A PHP package mainly developed for Laravel to manage uploading images using Ajax and displaying thumbnail. 2.0.7(9y ago)283.8k8[6 issues](https://github.com/SUKOHI/Surpass/issues)MITPHP Since Aug 5Pushed 9y ago4 watchersCompare [ Source](https://github.com/SUKOHI/Surpass)[ Packagist](https://packagist.org/packages/sukohi/surpass)[ RSS](/packages/sukohi-surpass/feed)WikiDiscussions master Synced 1w ago READMEChangelogDependencies (1)Versions (19)Used By (0)Security (1) Surpass ======= [](#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](https://github.com/SUKOHI/Surpass/tree/1.0)) **[Demo](http://demo-laravel52.capilano-fw.com/surpass)** (Example) [!['Kitsilano'](https://camo.githubusercontent.com/0e1af6818eb60138d09188d92953266432ef596c1cbfc1cae7867c054978f53b/687474703a2f2f692e696d6775722e636f6d2f634a36743530472e706e67)](https://camo.githubusercontent.com/0e1af6818eb60138d09188d92953266432ef596c1cbfc1cae7867c054978f53b/687474703a2f2f692e696d6775722e636f6d2f634a36743530472e706e67) Requirements ============ [](#requirements) - [jQuery](https://jquery.com/) - [jQuery UI](https://jqueryui.com/) - [blueimp/jQuery-File-Upload](https://github.com/blueimp/jQuery-File-Upload) Installation ============ [](#installation) 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 ``` Usage ===== [](#usage) **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('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') {!! $surpass->html('preview') !!} @stop @section('script') {!! $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](#rename_files) 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)** ``` // 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()](#image_file_id)** and **[imageFileIds()](#image_file_id)** 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) ``` {!! $surpass_x->html('preview') !!} {!! $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) Drop images here! ``` **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. ``` Methods ======= [](#methods) - 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. - input - preview 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](https://github.com/blueimp/JavaScript-Load-Image#options). 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. - 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' \]) 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. - maxWidth - maxHeight See [here](https://github.com/blueimp/jQuery-File-Upload/wiki/Options#imageminwidth). - If $force\_crop is true, imageCrop added. See [here](https://github.com/blueimp/jQuery-File-Upload/wiki/Options#imagecrop). 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. Drop Zone 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) - 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`. ``` $surpass = Surpass::path('YOUR_PATH'); $surpass->renameFiles(false); if($surpass->save()) { // Something.. } ``` Configuration ============= [](#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. **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](https://laravel.com/docs/master/migrations#renaming-and-dropping-tables)or `examples/migrations/2016_04_03_063049_rename_image_files_to_thumbnail_files.php`. Special thanks ============== [](#special-thanks) Thank you guys for your contributions! - [dsfser](https://github.com/dsfser) - [Marco Mazzocchi](https://github.com/marco-mazzocchi) - [nmfzone](https://github.com/nmfzone) License ======= [](#license) This package is licensed under the MIT License. Copyright 2014 Sukohi Kuhoh ### Health Score 36 — LowBetter than 82% of packages Maintenance16 Infrequent updates — may be unmaintained Popularity29 Limited adoption so far Community12 Small or concentrated contributor base Maturity72 Established project with proven stability Bus Factor1 Top contributor holds 100% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~32 days Recently: every ~92 days Total 18 Last Release 3393d ago Major Versions 1.0.0 → 2.0.02015-08-06 1.0.1 → 2.0.32015-09-25 1.0.4 → 2.0.42016-01-27 1.0.7 → 2.0.52016-01-28 ### Community Maintainers ![](https://www.gravatar.com/avatar/2980d59b309d45df3f2e6e51b1d336614da063240b8f76f873f287cd745ec5db?d=identicon)[Sukohi](/maintainers/Sukohi) --- Top Contributors [![SUKOHI](https://avatars.githubusercontent.com/u/5362394?v=4)](https://github.com/SUKOHI "SUKOHI (3 commits)") ### Embed Badge ![Health badge](/badges/sukohi-surpass/health.svg) ``` [![Health](https://phpackages.com/badges/sukohi-surpass/health.svg)](https://phpackages.com/packages/sukohi-surpass) ``` ### Alternatives [spatie/laravel-image-optimizer Optimize images in your Laravel app 1.3k6.5M43](/packages/spatie-laravel-image-optimizer)[justbetter/statamic-image-optimize Image optimization after upload 1315.2k](/packages/justbetter-statamic-image-optimize)[folour/flavy FFmpeg layer for Laravel 5.2-5.4, this is a fork of rafasamp/sonus package 279.6k](/packages/folour-flavy) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)