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)
);

<?php
class User extends AppModel {
    public $actsAs = array(
        'Upload.Upload' => array(
            'photo'
        )
    );
}
?>

<?php echo $this->Form->create('User', array('type' => 'file')); ?>
<?php echo $this->Form->input('User.username'); ?>
<?php echo $this->Form->input('User.photo', array('type' => 'file')); ?>
<?php echo $this->Form->end(); ?>

Using the above setup, uploaded files cannot be deleted. To do so, 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`)
);

<?php
class User extends AppModel {
    public $actsAs = array(
        'Upload.Upload' => array(
            'photo' => array(
                'fields' => array(
                    'dir' => 'photo_dir'
                )
            )
        )
    );
}
?>

In the above example, photo can be a file upload via a file input within a form, a file grabber (from a url) via a text input, OR programatically used on the controller to file grab via a url.

File Upload Example¶

<?php echo $this->Form->create('User', array('type' => 'file')); ?>
    <?php echo $this->Form->input('User.username'); ?>
    <?php echo $this->Form->input('User.photo', array('type' => 'file')); ?>
    <?php echo $this->Form->input('User.photo_dir', array('type' => 'hidden')); ?>
<?php echo $this->Form->end(); ?>

File Grabbing via Form Example¶

<?php echo $this->Form->create('User', array('type' => 'file')); ?>
    <?php echo $this->Form->input('User.username'); ?>
    <?php echo $this->Form->input('User.photo', array('type' => 'file')); ?>
    <?php echo $this->Form->input('User.photo_dir', array('type' => 'hidden')); ?>
<?php echo $this->Form->end(); ?>

Programmatic File Retrieval without a Form¶

<?php
$this->User->set(array('photo' => $image_url));
$this->User->save();
?>

Thumbnail Creation¶

Thumbnails are not automatically created. To do so, thumbnail sizes must be defined: Note: by default thumbnails will be generated by imagick, if you want to use GD you need to set the thumbnailMethod attribute. Example: 'thumbnailMethod' => 'php'.

<?php
class User extends AppModel {
    public $actsAs = array(
        'Upload.Upload' => array(
            'photo' => array(
                'thumbnailSizes' => array(
                    'xvga' => '1024x768',
                    'vga' => '640x480',
                    'thumb' => '80x80'
                )
            )
        )
    );
}
?>

Displaying links to files in your view¶

Once your files have been uploaded you can link to them using the HtmlHelper by specifying the path and using the file information from the database.

This example uses the default behaviour configuration using the model Example.

<?php
$exampleData = [
    'Example' => [
        'image' => 'imageFile.jpg',
        'dir' => '7'
    ]
];

echo $this->Html->link('../files/example/image/' . $exampleData['Example']['dir'] . '/' . $exampleData['Example']['image']);
?>

If we have configured a thumbnail in our application. We can simply prefix our file with the name of that thumbnail.

<?php
echo $this->Html->link('../files/example/image/' . $exampleData['Example']['dir'] . '/thumb_' . $exampleData['Example']['image']);
?>

Uploading Multiple files¶

Multiple files can also be attached to a single record:

<?php
class User extends AppModel {
    public $actsAs = array(
        'Upload.Upload' => array(
            'resume',
            'photo' => array(
                'fields' => array(
                    'dir' => 'profile_dir'
                )
            )
        )
    );
}
?>

Each key in the Upload.Upload array is a field name, and can contain it’s own configuration. For example, you might want to set different fields for storing file paths:

<?php
class User extends AppModel {
    public $actsAs = array(
        'Upload.Upload' => array(
            'resume' => array(
                'fields' => array(
                    'dir' => 'resume_dir',
                    'type' => 'resume_type',
                    'size' => 'resume_size',
                )
            ),
            'photo' => array(
                'fields' => array(
                    'dir' => 'photo_dir',
                    'type' => 'photo_type',
                    'size' => 'photo_size',
                )
            )
        )
    );
}
?>

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.

If you are looking to add an unknown or high number of uploads to a model it’s worth considering using a polymorphic attachment.

Remove a current file without deleting the entire record¶

In some cases you might want to remove a photo or uploaded file without having to remove the entire record from the Model. In this case you would use the following code:

<?php
echo $this->Form->create('Model', array('type' => 'file'));
echo $this->Form->input('Model.file.remove', array('type' => 'checkbox', 'label' => 'Remove existing file'));
?>

Saving two uploads into different folders¶

Sometimes you might want to upload more than one file, but upload each file into a different folder. This is actually very simple. By simply using the behavior configuration for each file you can change the path. Don’t forget to make sure the plugin is installed first.

Let’s assume for this example that we want to upload a picture of a user, and say, a picture of their car. For the sake of simplicity we’ll also assume that these files are just stored in the User model.

Note: It’s important to notice that each field can have it’s own configuration.

<?php
// app/Model/User.php
public $actsAs = array(
    'Upload.Upload' => array(
        'avatar' => array( // The name of the field in our database, so this is `users.avatar`
            'rootDir' => ROOT, // Here we can define the rootDir, which is the root of the application, usually an absolute path to your project
            'path' => '{ROOT}{DS}webroot{DS}files{DS}{model}{DS}{field}{DS}', // The path pattern that we want to use to save our file where {DS} is the directory separator and the {ROOT}, {model} and {field} tokens are replaced with their matching values
            'fields' => array(
                'dir' => 'image_dir' // It's always helpful to save the directory our files are in, just in case
            )
        ),
        'car' => array(
            'path' => '{ROOT}{DS}webroot{DS}files{DS}cars{DS}' // Here we have changed the path, so our images will now be in a different folder
        )
    )
)

Changing the upload path dynamically¶

If you need to change the path of the upload dynamically you can do that by changing the behavior settings in your model. Perhaps in a model callback such as beforeSave().

<?php
// app/Model/User.php
$this->Behaviors->Upload->settings['field']['path'] = $newPath;
?>