Rename Files

To rename an uploaded file use the upload.before event:

$handler->on('upload.before', function ($file) {
    $file->save = 'myfile';
    // OR
    $file->saveWithExtension = 'myfile.txt';

Protect Files

If you use Filepicker in a application with users you may want to protect the files directory from users that are not logged in.

First create a .htaccess file inside the files directory containing:

Deny from all 

Next edit uploader/index.php and enable the php_download option:

$config['php_download'] = true;

Now in before any other event listeners register one with these events: upload.before, files.fetch,, file.delete, crop.before:

$handler->on(array('upload.before', 'files.fetch', '', 'file.delete', 'crop.before'), 
    function () {
    // If the user is Unauthorized, then:
    throw new \Hazzard\Filepicker\Exception\AbortException('Unauthorized');

To check if the user is authorized you may include a library from your app, call a function, check if a specific session is set, etc.

Fetch Files

By default all files will be returned, but you may want to return just some files, for example the ones that belong to a specific user. To do that use the files.fetch event.

$handler->on('files.fetch', function (&$files) {
    // Here you may fetch just some files from the database based on the current user, etc.

    // $files = array('file1.txt', 'file2.jpg', '');

Filter Files

Instead of returning the files you want to show, you can use the files.filter event to filter the files.

The $files is an array of file instances and $total is the number of files. You may iterate through the files and unset some.

$handler->on('files.filter', function (&$files, &$total) {
    foreach ($files as $index => $file) {
        if ($index % 2 == 0) { 

Send Data to Server

To send data to the server use the data option. You can either pass an object or a function that returns an object.

// Example 1

    // ... 
    data: {
        paramA: 'value1',
        paramB: 'value2',

// Example 2

    // ... 
    data: function() { 
        // Grab the value from an input.
        var val = $('#myinput').val();

        // Return the object.
        return {
            paramA: 'value 1',
            paramB: val,

On the server side in any of the handler events you can access the data with from the request:

$handler->on('upload.before', function ($file) use ($handler) {
    $valueA = $handler->request()->get('paramA'); // <=> $_POST['paramA']
    $valueB = $handler->request()->get('paramB'); // <=> $_POST['paramB']

$handler->on('files.fetch', function (&$files) use ($handler) {
    $valueA = $handler->request()->get('paramA'); // <=> $_GET['paramA']
    $valueB = $handler->request()->get('paramB'); // <=> $_GET['paramB']

Make sure you add use ($handler) to use the $handler variable inside the scope of the function.

Insert Watermark

To insert a watermark, in the after option callback use the insert method on the $image object (and don't forget to save it):

 * Insert watermark.
 * @param  \Intervention\Image\Image $image
 * @param  string $filename
 * @param  string $version
$watermark = function ($image, $filename, $version) {
    $image->insert(__DIR__.'/watermark.jpg', 'bottom-left')->save();

// Add watermark to the default image version.
$config['image_versions..after'] = $watermark;

// Add watermark to the "thumb" image version.
$config['image_versions.thumb.after'] = $watermark;

If you want to position the watermark somewhere else make sure to read the docs for the insert method.