Uploading Files.

Uploading files are a lot easy and its just similar to working with GET/POST forms. First of all you must have multipart form.

 <form enctype="multipart/form-data" method="POST"> 

and you should have a hidden input field holding the max file size.

 <input type="hidden" name="MAX_FILE_SIZE" value="1024" /> 

so we can simply design a form in the view.

<span class="status">
  <?= $status ?>
</span>
<form enctype="multipart/form-data" method="POST">
  <input type="hidden" name="MAX_FILE_SIZE" value="1024" />
  Choose a file to Upload: <input name="atch" type="file" /><br />
  <label class="error">
    <?= triggeredErr('atch', $request->file) ?>
  </label>
  <input type="submit" value="Submit" />
</form>

However if you dont like writting HTML much you can also use Zigmoyd HTML helper Utilities.

<?= span::open(null, 'status') ?><?= $status ?><?= span::close() ?>
<?= form::startMultipart() ?>
  <?= form::hidden('MAX_FILE_SIZE', 1024) ?>
  Choose a file to upload: <?= form::file('atch') ?><br />
  <?= label::open(null, 'error') ?><?= triggeredErr('atch', $request->file) ?><?= label::close() ?>
  <?= form::submit(null, 'Upload') ?>
<?= form::end() ?>

and here also you can use isSubmitted() to check wheather or not the form has ben submitted.

Attention:

As Uploading is a serious Thing for the shake of security you must you a validation map while uploading. Its not only just a populer advice or boring note. as uploading is a highly sencitive activity you cant upload files if you dont use a validation map. Must must set atleast validation rules for the upload fileld(s) If you dont really want to mark the upload field as required or mandatory you can just add a criteria optional against it.see validation System, Validation Map. However Its worth to mention that Zigmoyd Validation system's optional criteria can handle the following situations.
If no file has been provided for uploading its Ok as the field is optional. But If some file has been specified for uploading it must be validated through the filters mentioned just next to the optional criteria.

<?php
class someController extends homeController{//homeController ultimately extends zigController Class
  public function someMethod(){
    if(!$this->request->file->isSubmitted()){
      //form has not ben submitted yet
    }else{
      //form has been submitted.
      $this->request->file->initValidator('vldMapName')//Validation Map against which to validate
      if(!$this->request->file->doUpload()){
        //Failed to Upload
        //there are so many causes for uploading to fail including overruling validation map
      }else{
        //successfully Uploaded file
      }
    }
  }
}
?>

doUpload() method does the uploading job. Better to say it tries to upload the file(s)

Note:

you can use multiple Upload Fileds.

for informarion on validating upload see validation.

By default it stores all files in transfer/up directory in your project's directory. however you can change that by invoking upload::setDestination() method.

Configuration

upload system is configured by etc/upload.ini.php in your current project's directory which may look like the following one.

[default]
filter[] = "size(0, 1024)"
filter[] = "ext.deny(o, bin, sh, exe, bat, com)"
filter[] = "mime.deny(application/x-php)"
filter[] = "content.ban(violence)"
filter[] = "name.ban(passwd, shadow)"
[rule]
Z_UPLOAD_RULE_REQ = required;required Specifies that the field is mandatory
Z_UPLOAD_RULE_SIZE = size;size(MIN, MAX) * means any
Z_UPLOAD_RULE_EXT_ALLOW = ext.allow;ext.allow(png, jpeg) Allowed Extension
Z_UPLOAD_RULE_EXT_DENY = ext.deny;ext.deny(png, jpeg) Denied Extension
Z_UPLOAD_RULE_MIME_ALLOW = mime.allow;mime.allow(text/plain|text/html) Allowed Mime Types
Z_UPLOAD_RULE_MIME_DENY = mime.deny;mime.deny(text/plain|text/html) Denied Mime Types
Z_UPLOAD_RULE_NAME_BAN = name.ban;name.ban(words1|words2)
Z_UPLOAD_RULE_NAME_REGX = name.regx;name.regx(REGEX) reguler expression to match
Z_UPLOAD_RULE_IMAGE = img;img File must be an Image
Z_UPLOAD_RULE_IMAGE_HEIGHT = img.height;img.height(MIN, MAX) * means any
Z_UPLOAD_RULE_IMAGE_WIDTH = img.width;img.width(MIN, MAX) * means any
Z_UPLOAD_RULE_CONTENT_BAN = content.ban;content.ban(words1|words2) Specify Ban words in Contents File must be textual
Z_UPLOAD_RULE_CONTENT_LEN = content.len;content.len(MIN, MAX) sets the strlen() of a textual file
Z_UPLOAD_RULE_CONTENT_CONTAIN = content.contains;content.contains(words1|words2) Specify the words must be present on the texual file uploaded
[settings]
Z_UPLOAD_NAME_RANDOM = "off"
Z_UPLOAD_NAME_OVERWRITE = "off"
[php_error]
UPLOAD_ERR_INI_SIZE = "Uploaded file size is greater than allowed Size in php.ini file (This is a Development Friendly Error Message The Developer should Change it)"
UPLOAD_ERR_FORM_SIZE = "Uploaded File Size Exided the allowed file size in the Hidden Filed (This is a Development Friendly Error Message The Developer should Change it or add an size(0, MAX_FILE_SIZE) criteria)"
UPLOAD_ERR_PARTIAL = "File could was Partially Uploaded (This is a Development Friendly Error Message The Developer should Change it)"
UPLOAD_ERR_NO_FILE = "No File has been Supplied for Uploading (This is a Development Friendly Error Message The Developer should Change it)"
UPLOAD_ERR_NO_TMP_DIR = "Missing a Temporary Folder (This is a Development Friendly Error Message The Developer should Change it)"
UPLOAD_ERR_CANT_WRITE = "Failed to write the uploaded file on server Disk (This is a Development Friendly Error Message The Developer should Change it)"
;UPLOAD_ERR_EXTENSION = "The extension is not supported by php.ini File (This is a Development Friendly Error Message The Developer should Change it or add a criteria ext.deny(EXTENS_TO_DENY))"

on the [default] directive you can store the default filters that will be automatically applied on all upload fields. e.g. you wouldn't need to create a map and initialize validation system invoking initValidator() method.

Warning:

the above mentioned feature is currently only available to PHP5 however PHP4 might be supported in the next version.

[rule] directive holds default rule names and what that rule does is comment out on its right side. see more about it on Validation Map Page

[php_error] block holds default error messages for Standard errors fired by PHP.

[settings] directive holds default settings about which we will now discuss.

Upload Settings

by default when you upload some file it remains in the server with its original name. however if you set it to random name it will use a random name everytime a new file is uploaded. for that change the Z_UPLOAD_NAME_RANDOM to on

if two file with same name uploaded one after another should it overwrite the first one with the second one or not is controlled by Z_UPLOAD_NAME_OVERWRITE

You can statically change them in INI configuration files as well as dynamically with zDef (Zigmoyd Defining System). You can issue zDef::set('Z_UPLOAD_NAME_RANDOM', true) at runtime to set it to on.
You can also change Z_UPLOAD_NAME_OVERWRITE at runtime in the same way. you can simply code like this.

<?php
class someController extends homeController{//homeController ultimately extends zigController Class
  public function someMethod(){
    if(!$this->request->file->isSubmitted()){
      //form has not ben submitted yet
    }else{
      //form has been submitted.
      zDef::set('Z_UPLOAD_NAME_RANDOM', true);
      $this->request->file->initValidator('vldMapName')//validation
      if(!$this->request->file->doUpload()){
        //Failed to Upload
        //there are so many causes for uploading to fail including overruling validation map
      }else{
        //successfully Uploaded file
      }
    }
  }
}
?>