Page Contents

Examples

Basic example

Note: You may want to define the Upload behavior before the core Translate Behavior as they have been known to conflict with each other.

CREATE table users (
    id int(10) unsigned NOT NULL auto_increment,
    username varchar(20) NOT NULL,
    photo varchar(255)
);

/*
   In the present example, these changes would be made in:
   src/Model/Table/UsersTable.php
*/
declare(strict_types=1);

namespace App\Model\Table;
use Cake\ORM\Table;

class UsersTable extends Table
{
    public function initialize(array $config): void
    {
        $this->setTable('users');
        $this->setDisplayField('username');
        $this->setPrimaryKey('id');

        $this->addBehavior('Josegonzalez/Upload.Upload', [
            // You can configure as many upload fields as possible,
            // where the pattern is `field` => `config`
            //
            // Keep in mind that while this plugin does not have any limits in terms of
            // number of files uploaded per request, you should keep this down in order
            // to decrease the ability of your users to block other requests.
            'photo' => [],
        ]);
    }
}

/*
   In the present example, these changes would be made in:
   templates/Users/add.php
   templates/Users/edit.php
*/
echo $this->Form->create($user, ['type' => 'file']);
    echo $this->Form->control('username');
    echo $this->Form->control('photo', ['type' => 'file']);
echo $this->Form->end();

Note: If you used *bake* to generate MVC structure after creating
the users table, you will need to remove the default scalar validation
for the photos field.

public function validationDefault(Validator $validator): void
{
    $validator
        ->integer('id')
        ->allowEmptyString('id', 'create');

    $validator
        ->scalar('username')
        ->allowEmptyString('username');

    $validator
        // remove ->scalar('photo')
        ->allowEmptyFile('photo');

    return $validator;
}

Deleting files

Using the setup from the previous example, uploaded files can only be deleted as long as the path is configured to use static tokens. As soon as dynamic tokens are incorporated, like for example {day}, the generated path will change over time, and files cannot be deleted anymore at a later point.

In order to prevent such situations, a field must be added to store the directory of the file as follows:

CREATE table users (
    `id` int(10) unsigned NOT NULL auto_increment,
    `username` varchar(20) NOT NULL,
    `photo` varchar(255) DEFAULT NULL,
    `photo_dir` varchar(255) DEFAULT NULL,
    PRIMARY KEY (`id`)
);

/*
   In the present example, these changes would be made in:
   src/Model/Table/UsersTable.php
*/
declare(strict_types=1);

namespace App\Model\Table;
use Cake\ORM\Table;

class UsersTable extends Table
{
    public function initialize(array $config): void
    {
        $this->setTable('users');
        $this->setDisplayField('username');
        $this->setPrimaryKey('id');

        $this->addBehavior('Josegonzalez/Upload.Upload', [
            'photo' => [
                'fields' => [
                    // if these fields or their defaults exist
                    // the values will be set.
                    'dir' => 'photo_dir', // defaults to `dir`
                    'size' => 'photo_size', // defaults to `size`
                    'type' => 'photo_type', // defaults to `type`
                ],
            ],
        ]);
    }
}

/*
   In the present example, these changes would be made in:
   templates/Users/add.php
   templates/Users/edit.php
*/

echo $this->Form->create($user, ['type' => 'file']);
    echo $this->Form->control('username');
    echo $this->Form->control('photo', ['type' => 'file']);
echo $this->Form->end();

Using such a setup, the behavior will use the stored path value instead of generating the path dynamically when deleting files.

Advanced example

In this example we’ll cover: - custom database fields - a nameCallback which makes the filename lowercase only - a custom transformer where we generate a thumbnail of the uploaded image - delete the related files when the database record gets deleted - a deleteCallback to ensure the generated thumbnail gets removed together with the original

This example uses the Imagine library. It can be installed through composer:

composer require imagine/imagine

CREATE table users (
    id int(10) unsigned NOT NULL auto_increment,
    username varchar(20) NOT NULL,
    photo varchar(255),
    photo_dir varchar(255),
    photo_size int(11),
    photo_type varchar(255)
);

/*
   In the present example, these changes would be made in:
   src/Model/Table/UsersTable.php
*/
declare(strict_types=1);

namespace App\Model\Table;
use Cake\ORM\Table;

class UsersTable extends Table
{
    public function initialize(array $config): void
    {
        $this->setTable('users');
        $this->setDisplayField('username');
        $this->setPrimaryKey('id');

        $this->addBehavior('Josegonzalez/Upload.Upload', [
            'photo' => [
                'fields' => [
                    'dir' => 'photo_dir',
                    'size' => 'photo_size',
                    'type' => 'photo_type',
                ],
                'nameCallback' => function ($table, $entity, $data, $field, $settings) {
                    return strtolower($data->getClientFilename());
                },
                'transformer' => function ($table, $entity, $data, $field, $settings, $filename) {
                    $extension = pathinfo($filename, PATHINFO_EXTENSION);

                    // Store the thumbnail in a temporary file
                    $tmp = tempnam(sys_get_temp_dir(), 'upload') . '.' . $extension;

                    // Use the Imagine library to DO THE THING
                    $size = new \Imagine\Image\Box(40, 40);
                    $mode = \Imagine\Image\ImageInterface::THUMBNAIL_INSET;
                    $imagine = new \Imagine\Gd\Imagine();

                    // Save that modified file to our temp file
                    $imagine->open($data->getStream()->getMetadata('uri'))
                        ->thumbnail($size, $mode)
                        ->save($tmp);

                    // Now return the original *and* the thumbnail
                    return [
                        $data->getStream()->getMetadata('uri') => $filename,
                        $tmp => 'thumbnail-' . $filename,
                    ];
                },
                'deleteCallback' => function ($path, $entity, $field, $settings) {
                    // When deleting the entity, both the original and the thumbnail will be removed
                    // when keepFilesOnDelete is set to false
                    return [
                        $path . $entity->{$field},
                        $path . 'thumbnail-' . $entity->{$field},
                    ];
                },
                'keepFilesOnDelete' => false,
            ]
        ]);
    }
}

/*
   In the present example, these changes would be made in:
   templates/Users/add.php
   templates/Users/edit.php
*/

echo $this->Form->create($user, ['type' => 'file']);
    echo $this->Form->control('username');
    echo $this->Form->control('photo', ['type' => 'file']);
echo $this->Form->end();