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.

.. code:: sql

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

.. code:: php

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

.. code:: php

    <?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:

.. code:: sql

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

.. code:: php

    <?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
^^^^^^^^^^^^^^^^^^^

.. code:: php

    <?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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code:: php

    <?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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code:: php

    <?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'``.

.. code:: 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 <configuration.md>`__ using the model ``Example``.

.. code:: php

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

.. code:: php

    <?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:

.. code:: php

    <?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:

.. code:: php

    <?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 <polymorphic.html>`__.

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:

.. code:: php

    <?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 <installation.md>`__.

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.

.. code:: php

    <?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()``.

.. code:: php

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