Uploading

Class Upload helps with validating and upoading files to the server.

Creating object

To upload files you need an Upload instance. You can get this instance from the request object which is available in all factories or manually create an instance.

class Photos {

    public function upload($request) {
        $upload = $request->Upload;
    }

    private function privateMethod() {
        // if you use Artaengine with namespace then Upload in arta\request
        require_once ARTA_DIR.'request/Upload.php';
        $upload = new Upload();
    }
}

Checking and debugging

You can use below methods to check and debug upload:

// see all uploads
I($request->Upload->getFiles());

// check if a key exists in upload
$key = 'file';
$key = 'file.1';
if ($request->Upload->has($key)) {

}

Batch validating

Before uploading file(s) you can validate them and only store those which are suitable. Each uploaded file is wrapped inside a UploadFile instance. This instances can be fetched from the Upload instance and validated and/or uploaded separately. However if you want to check all the uploaded files against the same set of rules you can do it directly with the Upload instance as shown below:

$rules = array(
    // will return error if file is not uploaded
    'required' => true,
    // max file size
    'size'     => '2M',
    // can be array or string
    'type'     => array('image/jpeg', 'image/png'),
    'ext'      => array('jpg', 'jpeg', 'png'),
    // set an external method to manually validate
    'plugin'   => 'PhotoEdit::isPhoto',
);

// validate the rule set against all uploaded files
$validate = $request->Upload->validate($rules);

if ($validate === true) {
    // all uploaded files follow the rules
} else {
    // an array of errors
    I($validate);
}

Batch uploading

Each uploaded file is wrapped inside a UploadFile instance. This instances can be fetched from the Upload instance and validated and/or uploaded separately. However if you can upload all files at once directly with the Upload instance as shown below:

<input type="file" id="file1"/>      key = file1
<input type="file" id="file[1][2]"/> key = file.1.2
<input type="file" id="file[1][3]"/> key = file.1.3
// upload files to this directory with their original filenames
$result = $request->Upload->validate('/var/uploads');

// result will be somethin like this:
$result = array(
    'file1'    => true,  // uploaded sucessfully
    'file.1.2' => true,  // uploaded sucessfully
    'file.1.3' => array( // uploaded sucessfully
        ERRORS
    ),
);
// upload files to this directory with their original filenames
try {
    $request->Upload->validate('/var/uploads', true);
} catch (Exception $x) {

}
// define filename to store each upload by it's key
$paths = array(
    'file1'    => '/var/uploads/1.jpg',
    'file.1.2' => '/var/uploads/2.jpg',
    'file.1.3' => '/var/uploads/3.jpg',
);

$result = $request->Upload->validate($paths);
// define filename to store each upload by it's key
$paths = array(
    'file1'    => '/var/uploads/1.jpg',
    'file.1.2' => '/var/uploads/2.jpg',
    'file.1.3' => '/var/uploads/3.jpg',
);

try {
    $request->Upload->validate($paths, true);
} catch (Exception $x) {

}

Validating

To iterate over the uploaded files and validate them one by one:

$errors  = array();
$success = array();

// validation rules
$rules = array(
    // will return error if file is not uploaded
    'required' => true,
    // max file size
    'size'     => '1M',
    // can be array or string
    'type'     => array('image/jpeg', 'image/png'),
    'ext'      => array('jpg', 'jpeg', 'png'),
    // set an external method to manually validate
    'plugin'   => array($this, 'isPhoto'),
);

// iterate over the uploaded files
foreach ($request->Upload as $key => $uploaded) {
    // $uploaded is an intance of UploadFile

    $validate = $uploaded->validate($rules);
    if ($validate === true) {
        $success[] = $key;
    } else {
        $errors[$key] = $validate;
    }
}

I('Successfully', $success, 'errors', $errors);

Validation rules

  • Marks that a file is required to be uploaded. Otherwise the original PHP upload related error and message will be added to the error stack.
  • Uploaded file(s) max file-size. If the uploaded file-size is larger then this an UploadError::SIZE will be added to the error stack. You can use units with values: '2M' meaning 2 mega bytes, '5K' meaning 4 kilo bytes and 1000 meaning 1000 bytes.
  • A string or list of strings which are file mime types to be checked against uploaded file mime type(s). If uploaded file type not matches then an UploadError::TYPE will be raised or added to the error stack.
  • A string or list of strings which are file extensions to be checked against uploaded file extensions(s). If uploaded file extension not matches then an UploadError::EXT will be raised or added to the error stack.
  • A custom function name or array(class, method) which will check the upload file and return True/False. After uploading a file this function/method will be called passing the file path to it, then the plugin decides to return True or False. If False is returned then an UploadError::PLUGIN will be raised or added to the error stack.

Uploading

To iterate over the uploaded files and save them to a path:

$path = '/var/www/my-project/uploads/';
$i = 0;
// iterate over the uploaded files
foreach ($request->Upload as $uploaded) {
    // $uploaded is an intance of UploadFile
    try {
        $uploaded->moveTo($path.(++$i).'.jpg');
    } catch (UploadError $x) {
        // could not upload is the path writable?
    }
}

Example with validation:

$path = '/var/www/my-project/uploads/';
$i    = 0;

$errors  = array();
$success = array();

$rules = array(
    'required' => true,
    'size'     => '1000K',
    'type'     => array('image/jpeg', 'image/png'),
    'ext'      => array('jpg', 'jpeg', 'png'),
    'plugin'   => array($this, 'isPhoto'),
);

// the Upload instance is iteratable
foreach ($request->Upload as $key => $uploaded) {

    $validate = $uploaded->validate($rules);

    if ($validate === true) {
        // save the uploaded file
        try {
            $uploaded->moveTo($path.(++$i).'.jpg');
            $success[$key] = 'Successfully uploaded';
        } catch (UploadError $x) {
            $errors[$key] = 'Can not write on disk';
        }
    } else {
        $errors[$key] = $validate;
    }
}

I('Successfully', $success, 'errors', $errors);

Example

Uploading files
TOP