Modules

Kohana_Upload

This class is a transparent base class for Upload and should not be accessed directly.

Upload helper class for working with uploaded files and Validation.

$array = Validation::factory($_FILES);

Remember to define your form with "enctype=multipart/form-data" or file uploading will not work!

The following configuration properties can be set:

package
Kohana
category
Helpers
author
Kohana Team
copyright
© 2007-2012 Kohana Team
license
https://kohana.top/license

Class declared in SYSPATH/classes/Kohana/Upload.php on line 22.

Properties

public static string $default_directory

default upload directory

string(6) "upload"

public static boolean $remove_spaces

remove spaces in uploaded files

bool TRUE

Methods

public static image( array $file [, integer $max_width = NULL , integer $max_height = NULL , boolean $exact = bool FALSE ] ) (defined in Kohana_Upload)

Validation rule to test if an upload is an image and, optionally, is the correct size.

// The "image" file must be an image
$array->rule('image', 'Upload::image')

// The "photo" file has a maximum size of 640x480 pixels
$array->rule('photo', 'Upload::image', [':value', 640, 480]);

// The "image" file must be exactly 100x100 pixels
$array->rule('image', 'Upload::image', [':value', 100, 100, true]);

Parameters

  • array $file required - $_FILES item
  • integer $max_width = NULL - Maximum width of image
  • integer $max_height = NULL - Maximum height of image
  • boolean $exact = bool FALSE - Match width and height exactly?

Return Values

  • boolean

Source Code

public static function image(array $file, $max_width = null, $max_height = null, $exact = false)
{
    if (Upload::not_empty($file)) {
        try {
            // Get the width and height from the uploaded image
            list($width, $height) = getimagesize($file['tmp_name']);
        } catch (ErrorException $e) {
            // Ignore read errors
        }

        if (empty($width) OR empty($height)) {
            // Cannot get image size, cannot validate
            return false;
        }

        if (!$max_width) {
            // No limit, use the image width
            $max_width = $width;
        }

        if (!$max_height) {
            // No limit, use the image height
            $max_height = $height;
        }

        if ($exact) {
            // Check if dimensions match exactly
            return ($width === $max_width AND $height === $max_height);
        } else {
            // Check if size is within maximum dimensions
            return ($width <= $max_width AND $height <= $max_height);
        }
    }

    return false;
}

public static not_empty( array $file ) (defined in Kohana_Upload)

Tests if a successful upload has been made.

$array->rule('file', 'Upload::not_empty');

Parameters

  • array $file required - $_FILES item

Return Values

  • bool

Source Code

public static function not_empty(array $file)
{
    return (isset($file['error'])
        AND isset($file['tmp_name'])
        AND $file['error'] === UPLOAD_ERR_OK
        AND is_uploaded_file($file['tmp_name']));
}

public static save( array $file [, string $filename = NULL , string $directory = NULL , integer $chmod = integer 420 ] ) (defined in Kohana_Upload)

Save an uploaded file to a new location. If no filename is provided, the original filename will be used, with a unique prefix added.

This method should be used after validating the $_FILES array:

if ($array->check())
{
    // Upload is valid, save it
    Upload::save($array['file']);
}

Parameters

  • array $file required - Uploaded file data
  • string $filename = NULL - New filename
  • string $directory = NULL - New directory
  • integer $chmod = integer 420 - Chmod mask

Return Values

  • string - On success, full path to new file
  • false - On failure

Source Code

public static function save(array $file, $filename = null, $directory = null, $chmod = 0644)
{
    if (!isset($file['tmp_name']) OR ! is_uploaded_file($file['tmp_name'])) {
        // Ignore corrupted uploads
        return false;
    }

    if ($filename === null) {
        // Use the default filename, with a timestamp pre-pended
        $filename = uniqid() . $file['name'];
    }

    if (Upload::$remove_spaces === true) {
        // Remove spaces from the filename
        $filename = preg_replace('/\s+/u', '_', $filename);
    }

    if ($directory === null) {
        // Use the pre-configured upload directory
        $directory = Upload::$default_directory;
    }

    if (!is_dir($directory) OR ! is_writable(realpath($directory))) {
        throw new Kohana_Exception('Directory :dir must be writable', [':dir' => Debug::path($directory)]);
    }

    // Make the filename into a complete path
    $filename = realpath($directory) . DIRECTORY_SEPARATOR . $filename;

    if (move_uploaded_file($file['tmp_name'], $filename)) {
        if ($chmod !== false) {
            // Set permissions on filename
            chmod($filename, $chmod);
        }

        // Return new file path
        return $filename;
    }

    return false;
}

public static size( array $file , string $size ) (defined in Kohana_Upload)

Validation rule to test if an uploaded file is allowed by file size. File sizes are defined as: SB, where S is the size (1, 8.5, 300, etc.) and B is the byte unit (K, MiB, GB, etc.). All valid byte units are defined in Num::$byte_units

$array->rule('file', 'Upload::size', [':value', '1M'])
$array->rule('file', 'Upload::size', [':value', '2.5KiB'])

Parameters

  • array $file required - $_FILES item
  • string $size required - Maximum file size allowed

Return Values

  • bool

Source Code

public static function size(array $file, $size)
{
    if ($file['error'] === UPLOAD_ERR_INI_SIZE) {
        // Upload is larger than PHP allowed size (upload_max_filesize)
        return false;
    }

    if ($file['error'] !== UPLOAD_ERR_OK) {
        // The upload failed, no size to check
        return true;
    }

    // Convert the provided size to bytes for comparison
    $size = Num::bytes($size);

    // Test that the file is under or equal to the max size
    return ($file['size'] <= $size);
}

public static type( array $file , array $allowed ) (defined in Kohana_Upload)

Test if an uploaded file is an allowed file type, by extension.

$array->rule('file', 'Upload::type', [':value', ['jpg', 'png', 'gif']]);

Parameters

  • array $file required - $_FILES item
  • array $allowed required - Allowed file extensions

Return Values

  • bool

Source Code

public static function type(array $file, array $allowed)
{
    if ($file['error'] !== UPLOAD_ERR_OK)
        return true;

    $ext = strtolower(pathinfo($file['name'], PATHINFO_EXTENSION));

    return in_array($ext, $allowed);
}

public static valid( array $file ) (defined in Kohana_Upload)

Tests if upload data is valid, even if no file was uploaded. If you do require a file to be uploaded, add the Upload::not_empty rule before this rule.

$array->rule('file', 'Upload::valid')

Parameters

  • array $file required - $_FILES item

Return Values

  • bool

Source Code

public static function valid($file)
{
    return (isset($file['error'])
        AND isset($file['name'])
        AND isset($file['type'])
        AND isset($file['tmp_name'])
        AND isset($file['size']));
}