modules/stream/stream.module

<?php


/**
 * @file 
 * Stream replacement for file.inc
 *
 */

/**
 * Implementation of hook_boot
 * 
 * Registers core stream handlers for public and private files.
 */

function stream_boot() {
  $manager = StreamWrapperManager::singleton();
  $manager->register('public',   'StreamWrapperFilePublic', 'StreamFilePublic');
  $manager->register('private',  'StreamWrapperFilePrivate', 'StreamFilePrivate');
}

function stream_perm() {
  return array(
    'administer stream handlers' => array(
      'title' => 'Administer stream handlers',
      'Description' => 'Administer settings for stream handlers.'
    ),
  );  
}

function stream_menu() {
  $items = array();

  // menu items that are basically just menu blocks
  $items['admin/settings/stream'] = array(
    'title' => 'Stream configuration',
    'description' => 'Configure stream settings.',
    'position' => 'right',
    'weight' => -5,
    'page callback' => 'stream_settings_overview',
    'access arguments' => array('access administration pages'),
  );

  $items['admin/settings/stream/public'] = array(
    'title' => 'public:// settings',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('stream_settings_public_form'),
    'access arguments' => array('administer stream handlers')
  );
  $items['admin/settings/stream/private'] = array(
    'title' => 'private:// settings',
    'page callback' => 'drupal_get_form',
    'page arguments' => array('stream_settings_private_form'),
    'access arguments' => array('administer stream handlers')
  );
  return $items; 
}

/**
 * Menu callback; displays a module's settings page.
 */
function stream_settings_overview() {
  // Check database setup if necessary
  if (function_exists('db_check_setup') && empty($_POST)) {
    db_check_setup();
  }

  $item = menu_get_item('admin/settings/stream');
  $content = system_admin_menu_block($item);

  $output = theme('admin_block_content', $content);

  return $output;
}

function stream_settings_public_form() {
  $form = array();
  $form['stream_public_path'] = array(
    '#type' => 'textfield',
    '#title' => t('public:// file path'),
    '#default_value' => variable_get('stream_public_path', 'sites/default/files'),
    '#maxlength' => 255,
    '#description' => t('The path where public:// files will be stored. This directory must exist and be writable by Drupal. If the download method is set to public, this directory must be relative to the Drupal installation directory and be accessible over the web. If the download method is set to private, this directory should not be accessible over the web. Changing this location will modify all download paths and may cause unexpected problems on an existing site.'),
    '#after_build' => array('system_check_directory')
  );
  return system_settings_form($form);
}

function stream_settings_private_form() {
  $form = array();
  $form['stream_private_path'] = array(
    '#type' => 'textfield',
    '#title' => t('private:// file path'),
    '#default_value' => variable_get('stream_private_path', 'sites/default/files-private'),
    '#maxlength' => 255,
    '#description' => t('The path where public:// files will be stored. This directory must exist and be writable by Drupal. If the download method is set to public, this directory must be relative to the Drupal installation directory and be accessible over the web. If the download method is set to private, this directory should not be accessible over the web. Changing this location will modify all download paths and may cause unexpected problems on an existing site.'),
    '#after_build' => array('system_check_directory')
  );

  return system_settings_form($form);
}

/**
 * Stream API
 */

/** 
 * Debug Logging function.
 */
function stream_debug($message) {
  if (TRUE) watchdog('stream', $message, array(), WATCHDOG_DEBUG);
}

/**
 * This class provides a basic interface for registering stream wrappers.
 * It extends the standard functionality of stream_wrapper_register and
 * stream_get_wrappers with the ability to look up classnames/protocol 
 * associations and load wrappers classes by protocol. This additional
 * functionality allows the stream_wrapper_classes to be extended with 
 * Drupal specific stream functionality.
 */

class StreamWrapperManager {
  static private $wrappers = array();

  // private constructor to enforce singleton.
  private function __construct() { }

  /**
   * Load the singleton instance of the StreamWrapperManager.
   * @return object:StreamWrapperManager
   */
  public static function singleton() {
    static $instance = NULL;
    if (is_null($instance)) {
      $instance = new StreamWrapperManager();
    }
    return $instance;
  }

  /**
   * Register a class to handle a stream protocol.
   * @param string $protocol   stream protocol
   * @param string $classname  classname to handle the protocol.
   * @return bool result of stream_wrapper_register 
   * @see: http://us3.php.net/manual/en/function.stream-wrapper-register.php
   */
  function register($protocol, $streamwrapperclass, $streamclass) {
    self::$wrappers[$protocol]['streamwrapper'] = $streamwrapperclass;
    self::$wrappers[$protocol]['streamclass'] = $streamclass;
    return stream_wrapper_register($protocol, $streamwrapperclass);
  }

  function unregister($protocol) {
    if (stream_wrapper_unregister($protocol)) {
      unset(self::$wrappers[$protocol]);
      return TRUE;
    }
    return FALSE;
  }

  /**
   * Return the streamwrapper classname for a given protocol.
   * @param string $protocol stream protocol.
   * @return mixed string is a protocol has a registered handler or FALSE.
   */
  function streamwrapperclass($protocol) {
    if (empty(self::$wrappers[$protocol]['streamwrapperclass'])) {
      return FALSE;
    }
    return self::$wrappers[$protocol];
  }

  /**
   * Return the stream class name for a given protocol.
   * @param string $protocol stream protocol.
   * @return mixed string is a protocol has a registered handler or FALSE.
   */
  function streamclass($protocol) {
    if (empty(self::$wrappers[$protocol]['streamclass'])) {
      return FALSE;
    }
    return self::$wrappers[$protocol];
  }


  /**
   * Return the StreamWrapperManagers wrapper registry.
   */ 
  function wrappers() {
    return self::$wrappers;
  }
}

/**
 * A base StreamWrapper class to extend.
 */
class StreamWrapper {

  public function stream_open($path, $mode, $options, &$opened_path) {
    return FALSE;
  }

  public function stream_close() { } 

  public function stream_read($count) {
    return FALSE;
  }

  public function stream_write($data) {
    return 0;
  }

  public function stream_eof() {
    return TRUE;
  }

  public function stream_tell() {
    return 0;
  }

  public function stream_seek($offset, $whence) {
    return FALSE;
  }

  public function stream_flush() {
    return TRUE;
  }

  public function stream_stat() {
    return array();
  }

  // PHP > 5.3.0
  public function stream_cast(int $cast_as) {
    return FALSE;
  }

  // PHP > 5.3.0
  public function stream_set_option($option, $arg1, $arg2) {
    return FALSE;
  }
  
  // Do not implement if unsupported.
  // public function unlink($path) {}

  
  // Do not implement if unsupported.
  // public function rename($path_from, $path_to) {}

  // Do not implement if unsupported.
  // public function mkdir($path, $mode, $options) {}


  // Do not implement if unsupported.
  // public function rmdir($path, $options) {}

  public function dir_open($path, $option) {
    return FALSE;
  }

  public function url_stat($path, $flags) {
    return array();
  }

  public function dir_readdir() {
    return '';
  }

  public function dir_rewinddir() {
    return FALSE;
  }

  public function dir_closedir() {
    return TRUE;
  }
}

/**
 * A stream wrapper class for working with Local files.
 */
class StreamWrapperFile extends StreamWrapper {

  // A handle to the file opened by stream_open().
  private $fileHandle;

  /**
   * Support for fopen(), file_get_contents(), file_put_contents() etc.
   *
   * @param $path
   *   A string containing the path to the file to open.
   * @param $mode
   *   The file mode ("r", "wb" etc.).
   * @param $options
   *   A bit mask of STREAM_USE_PATH and STREAM_REPORT_ERRORS.
   * @param &$opened_path
   *   A string containing the path actually opened.
   * @return
   *  TRUE if file was opened successfully.
   */
  public function stream_open($path, $mode, $options, &$opened_path) {
    stream_debug("stream_open($path, $mode, $options, &$opened_path)");
    stream_debug("realpath: ". $this->realpath($path));
    if ($options & STREAM_REPORT_ERRORS) {
      $this->fileHandle = fopen($this->realpath($path, $mode), $mode);
    }
    else {
      $this->fileHandle = @fopen($this->realpath($path, $mode), $mode);
    }
    return (bool)$this->fileHandle;
  }

  // Undocumented PHP stream wrapper method.
  function stream_lock($operation) {
    $args = func_get_args();
    stream_debug('stream_lock:' . $operation .','. print_r($args,1));
    if (in_array($operation, array(LOCK_SH, LOCK_EX, LOCK_UN, LOCK_NB))) {
      return flock($this->fileHandle, $operation);
    }
    return TRUE;
  }

  /**
   * Support for fread(), file_get_contents() etc.
   *
   * @param $count
   *    Maximum number of bytes to be read.
   * @return
   *  The string that was read, or FALSE in case of an error.
   */
  public function stream_read($count) {
    stream_debug("stream_read($count)");
    return fread($this->fileHandle, $count);
  }

  /**
   * Support for fwrite(), file_put_contents() etc.
   *
   * @param $data
   *   The string to be written.
   * @return
   *   The number of bytes written.
   */
  public function stream_write($data) {
    stream_debug("stream_write($data)");
    return fwrite($this->fileHandle, $data);
  }

  /**
   * Support for feof().
   *
   * @return
   *   TRUE if end-of-file has been reached.
   */
  public function stream_eof() {
    stream_debug("stream_eof()");
    return feof($this->fileHandle);
  }

  /**
   * Support for fseek().
   * 
   * @param $offset
   *   The byte offset to got to.
   * @param $whence
   *   SEEK_SET, SEEK_CUR, or SEEK_END.
   * @return
   *   TRUE on success
   */
  public function stream_seek($offset, $whence) {
    stream_debug("stream_seek($offset, $whence)");
    return fseek($this->fileHandle, $offset, $whence);
  }

  /**
   * Support for fflush().
   *
   * @return
   *   TRUE if data was successfully stored (or there was no data to store).
   */
  public function stream_flush() {
    stream_debug("stream_flush()");
    return fflush($this->fileHandle);
  }

  /**
   * Support for ftell().
   *
   * @return
   *   The current offset in bytes from the beginning of file.
   */
  public function stream_tell() {
    stream_debug("stream_tell()");
    return ftell($this->fileHandle);
  }

  /**
   * Support for fstat().
   *
   * @return
   *   An array with file status, or FALSE in case of an error - see fstat()
   *   for a description of this array.
   */
  public function stream_stat() {
    stream_debug("stream_stat()");
    return fstat($this->fileHandle);
  }

  /**
   * Support for fclose().
   *
   * @return
   *   TRUE if stream was successfully closed.
   */
  public function stream_close() {
    stream_debug("stream_close()");
    return fclose($this->fileHandle);
  }

  /**
   * Support for unlink().
   *
   * @param $path
   *   A string containing the path to the file to delete.
   * @return
   *   TRUE if file was successfully deleted.
   */
  public function unlink($path) {
    stream_debug("unlink($path)");
    return unlink($this->realpath($path));
  }

  /**
   * Support for rename().
   *
   * @param $fromPath
   *   The path to the file to rename.
   * @param $toPath
   *   The new path to the file.
   *
   * @return
   *   TRUE if file was successfully renamed.
   */
  public function rename($fromPath, $toPath) {
    stream_debug("rename($fromPath, $toPath)");
    return rename($this->realpath($fromPath), $this->realpath($toPath));
  }

  /**
   * Support for mkdir().
   *
   * @param $path
   *   A string containing the path to the directory to create.
   * @param $mode
   *   Permission flags - see mkdir().
   * @param $options
   *   A bit mask of STREAM_REPORT_ERRORS and STREAM_MKDIR_RECURSIVE.
   * @return
   *   TRUE if directory was successfully created.
   */
  public function mkdir($path, $mode, $options) {
    stream_debug("mkdir($path, $mode, $options)");
    $recursive = (bool)($options & STREAM_MKDIR_RECURSIVE);
    if ($options & STREAM_REPORT_ERRORS) {
      return mkdir($this->realpath($path), $mode, $recursive);
    }
    else {
      return @mkdir($this->realpath($path), $mode, $recursive);
    }
  }

  /**
   * Support for rmdir().
   *
   * @param $path
   *   A string containing the path to the directory to delete.
   * @param $options
   *   A bit mask of STREAM_REPORT_ERRORS.
   * @return
   *   TRUE if directory was successfully removed.
   */
  public function rmdir($path, $options) {
    stream_debug("rmdir($path, $options)");
    if ($options & STREAM_REPORT_ERRORS) {
      return rmdir($this->realpath($path));
    }
    else {
      return @rmdir($this->realpath($path));
    }
  }

  /**
   * Support for stat().
   *
   * @param $path
   *   A string containing the path to get information about.
   * @param $flags
   *   A bit mask of STREAM_URL_STAT_LINK and STREAM_URL_STAT_QUIET.
   * @return
   *   An array with file status, or FALSE in case of an error - see fstat()
   *   for a description of this array.
   */
  public function url_stat($path, $flags) {
    stream_debug("url_stat($path, $flags)");
    return ($flags & STREAM_URL_STAT_QUIET) ? @stat($this->realpath($path)) : stat($this->realpath($path));
  }

  /**
   * Support for opendir().
   *
   * @param $path
   *   A string containing the path to the directory to open.
   * @param $options
   *   Unknown (parameter is not documented in PHP Manual).
   * @return
   *   TRUE on success.
   */
  public function dir_opendir($path, $options) {
    stream_debug("dir_opendir($path, $options)");
    $this->fileHandle = opendir($this->realpath($path));
    return (bool)$this->fileHandle;
  }

  /**
   * Support for readdir().
   *
   * @return
   *   The next filename, or FALSE if there are no more files in the directory.
   */
  public function dir_readdir() {
    stream_debug("dir_readdir()");
    return readdir($this->fileHandle);
  }

  /**
   * Support for rewinddir().
   *
   * @return
   *   TRUE on success.
   */
  public function dir_rewinddir() {
    stream_debug("dir_rewinddir()");
    return rewinddir($this->fileHandle);
  }

  /**
   * Support for closedir().
   *
   * @return
   *   TRUE on success.
   */
  public function dir_closedir() {
    stream_debug("dir_closedir()");
    return closedir($this->fileHandle);
  }

}

/**
 * public:// stream wrapper class.
 */
class StreamWrapperFilePublic extends StreamWrapperFile {

  // A handle to the file opened by stream_open().
  private $pathkey = 'stream_public_path';
  private $pathdefault = 'sites/default/files';

  /**
   * get a realpath for a public stream. Used internally.
   */
  function realpath($path) {
    $parts = parse_url($path);
    $realpath = realpath(variable_get($this->pathkey, $this->pathdefault)) . '/' . $parts['host'] . $parts['path'];
    
    // just in case stream_public_path is s3://, ftp://, etc. Don't call PHP's realpath().
    if (parse_url($realpath, PHP_URL_SCHEME)) {
      stream_debug("realpath($realpath)");
      return $realpath;
    }
    stream_debug("realpath($realpath)");
    return $realpath;
  }
}

/**
 * private:// stream wrapper class.
 */
class StreamWrapperFilePrivate extends StreamWrapperFilePublic {
  private $pathkey = 'stream_private_path';
  private $pathdefault = 'sites/default/files-private';
}


/**
 * Base Stream class. 
 *
 * The drupal_file class represents a physical file stored in Drupal's
 * 'File System Path'. It is important to understand that copy, move, 
 * delete, etc method affect both the the physical file the object
 * represents and the database record for the file. 
 *
 * Example Factory Usage:
 *   
 *   $factory = new StreamFile();
 *   $file = $factory->load_id(87);
 *   $another = $file->load_path('images/logo.png');
 *
 *   $file = StreamFile::load_id(24);
 *
 *   $yet_another = $file->load('path', 'uploads/myfile.pdf');
 *
 * 
 *   if ($yet_another->delete()) unset($yet_another);
 *
 */ 

class Stream {

  // @see drupal_file::load()
  protected static $files = array();

  public $fid = 0;
  public $uid = 1;
  public $filename = '';
  public $filepath = '';
  public $filemime = 'application/octet-stream';
  public $filesize = 0;  
  public $status = 0;
  public $timestamp = 0;

  /**
   * drupal_file constructor.
   *
   * @param object $file (optional) stdClass object to initialize self with.
   */
  function __construct($file = FALSE) {
    if (!$file || !is_object($file)) return;
    // assign all initialized properties to self.
    foreach ($file as $key => $value) {
      $this->$key = $value;
    }
  }

  function _exists_rename($destination) {
    if (file_exists($destination)) { 
      $parts = parse_url($destination);
      $streamdir = $parts['scheme'] . dirname($parts['path']);
      $basename = basename($parts['path']);

      // Destination file already exists, generate an alternative.
      $pos = strrpos($basename, '.');
      if ($pos !== FALSE) {
        $name = substr($basename, 0, $pos);
        $ext = substr($basename, $pos);
      }
      else {
        $name = $basename;
        $ext = '';
      }
  
      $counter = 0;
      do {
        $destination = $directory . '/' . $name . '_' . $counter++ . $ext;
      } while (file_exists($destination));
    }
  
    return $destination;
  }

  /**
   * Create a copy a drupal_file.
   *
   * @param  string $destination (optional) @see file_copy.
   * @param int $replace (optional) @see file_destination
   * @return object|bool  drupal_file if the copy is successful, or FALSE
   * @see file_copy()
   */
  function copy($destination, $replace = FILE_EXISTS_RENAME) {
    if (file_exists($destination)) {
      if ($replace & FILE_EXISTS_ERROR) {
        return FALSE;
      }
      if ($replace & FILE_EXISTS_RENAME) {
        $destination = $this->_exists_rename($destination); 
      }
    }
       
    if (copy($this->filepath, $destination, $replace)) {
      $file = clone $this;
      $file->fid      = null;
      $file->filename = basename($result);
      $file->filepath = $destination;
      if ($file->save()) {
        module_invoke_all('file_copy', $this, $file);
        return $file;
      }
    }
    return FALSE; 
  }


  /**
   * Delete a file and its database record.
   *
   * @param $force
   *   Boolean indicating that the file should be deleted even if
   *   hook_file_references() reports that the file is in use.
   * @return mixed 
   *   TRUE for success, array for reference count, or FALSE in the event
   *   of an error.
   *
   * @see hook_file_references()
   */
  function delete($force = FALSE) {
    // If any module returns a value from the reference hook, the 
    // file will not be deleted from Drupal, but file_delete will
    // return a populated array that tests as TRUE.
    if (!$force && ($references = module_invoke_all('file_references', $this))) {
      return $references;
    }

    // Let other modules clean up on delete.
    module_invoke_all('file_delete', $this);
 
    // Make sure the file is deleted before removing its row from the 
    // database, so UIs can still find the file in the database.
    if (unlink($this->filepath)) {
      db_query('DELETE FROM {files} WHERE fid = %d', $this->fid);
      // remove internally used static cache entries.
      $this->reset_cache('fid::'. $this->fid);
      $this->reset_cache('filepath::'. $this->filepath);
      return TRUE;
    }
    return FALSE;
  }

  /**
   * Return the first matching file in the files table. This is a simple single
   * object loader it in combination with the static $files variable allows all
   * drupal file objects to also act as factories and share the same static cache.
   *
   * @param string key (required) database column to use in where condition.
   * @param int|string value (required) the value of the column to use in the where condition.
   * @return object|bool A Drupal file object or FALSE if a file was not found.
   * @see drupal_file::load(), drupal_file::load_path()
   */
  final function _load($column, $value) {
    // set a cache id based on key and value so we can statically cache 
    // all simple loads.
    $cid = $column . '::' . $value; 
    if (empty(self::$files[$cid])) {
      $file = db_fetch_object(db_query('SELECT f.* FROM {files} f WHERE f.%s = %d', $column, $value));
      $scheme = parse_url($file, PHP_URL_PATH);
      $class = StreamWrapperManager::get_classname($scheme);
      $file = new $class($file);
    }
    module_invoke_all('file_load', $file);
    self::$files[$cid] = $file; 
    // Files are not cloned, because there is in fact only one.
    return self::$files[$cid];
  }
 
  /**
   * Load a file object from the database by id.
   *
   * @param int   $id     A file id. (required)
   * @return object|bool A Drupal file object or FALSE if a file was not found.
   * @see: drupal_file::load()
   */
  final function load_id($id) {
    return $this->_load('fid', $id);
  }

  /**
   * Load a file object from the database by path.
   *
   * @param string  $path   A path to a file. (required)
   * @return object|bool A Drupal file object or FALSE if a file was not found.
   * @see: drupal_file::load()
   */
  final function load_path($path) {
    return $this->_load('filepath', $path);
  }

  /**
   * Move a drupal_file.
   *
   * @param  string $destination (optional) @see file_copy.
   * @param int $replace (optional) @see file_destination
   * @return bool 
   * @see file_copy()
   */
  function move($destination, $replace = FILE_EXISTS_RENAME) {
    if (file_exists($destination)) {
      if ($replace & FILE_EXISTS_ERROR) {
        return FALSE;
      }
      if ($replace & FILE_EXISTS_RENAME) {
        $destination = $this->_exists_rename($destination); 
      }
    }
 
    if (rename($this->filepath, $destination)) {
      $orig = clone $this;
      $this->filename = basename($destination);
      $this->filepath = $result;
      if ($this->save()) {
        module_invoke_all('file_move', $this, $orig);
        return TRUE;
      }
    }
    return FALSE;
  }

  /**
   * Reset the shared static cache.
   */
  public function reset_cache($cid = FALSE) {
    // no cache id, reset the entire cache.
    if (!$cid) {
      self::$files = array();
    }
    elseif (isset(self::$files[$cid])) {
      unset(self::$files[$cid]);
    }
  }

  /**
   * Save the current state of a drupal_file in the database.
   * If the file->fid is empty a new database record will be added. 
   *
   * @return bool TRUE if save succeeded, FALSE if save failed.
   */
  function save() {
    $this->timestamp = time();
    $this->filesize = filesize($this->filepath);
  
    if (empty($this->fid)) {
      $result = drupal_write_record('files', $this);
      module_invoke_all('file_insert', $this);
    }
    else {
      $result = drupal_write_record('files', $this, 'fid');
      module_invoke_all('file_update', $this);
    }
    return $result;
  }

  /**
   * Mark a file as permanent.
   *
   * @return bool 
   */
  function set_status($bitmask = NULL) {
    if (is_null($bitmask)) {
      return $file->status;
    }
    elseif (db_query('UPDATE {files} SET status=%d', $bitmask, $this->fid)) {
      $this->status = $status;
      module_invoke_all('file_set_status', $this, $status);
      return TRUE;
    }
    return FALSE;
  }

  /**
   * Create a URL to the file.
   */
  function url() {
    return '';
  }
}

class StreamPublic extends Stream {
  function url() { }  
  function mime() { } 
}

class StreamPrivate extends StreamPublic {
  function url() { }
}

class StreamUpload extends Stream {
  public $source = '';
  public $errors;

  function save() {
    // validate if not already validated, error is validation didn't pass.
    if (!$this->validate()) {
      return FALSE;
    }
    // rename the file to its original name.
    parent::save();
  }

  function validate($validators = array()) {
    if (!isset($this->errors)) {
      // Default validation for all uploads.
      $validators['file_validate_name_length'] = array();
    
      $this->errors = array();
      foreach ($validators as $function => $args) {
        array_unshift($args, $file);
        $errors = array_merge($errors, call_user_func_array($function, $args));
      }
    }
    return !empty($this->errors);
  }

  function errors() {
    return $this->errors;
  }

  function move($dest) {
    // validate if not already validated, error is validation didn't pass.
    if (!$this->fid && !$this->save()) {
      return FALSE;
    }
    // for upload files we changed the filename in the path to a junk string...
     
  }

  /**
   * Saves a file upload to a temporary location
   *
   * The file will be added to the files table as a temporary file. Temporary
   * files are periodically cleaned. To make the file permanent file call
   * it's set_permanent() method.
   *
   * @param $source
   *   A string specifying the name of the upload field to save.
   * @param $validators
   *   An optional, associative array of callback functions used to validate the
   *   file. The keys are function names and the values arrays of callback
   *   parameters which will be passed in after the user and file objects. The
   *   functions should return an array of error messages, an empty array
   *   indicates that the file passed validation. The functions will be called in
   *   the order specified.
   * @param $destination
   *   A string containing the directory $source should be copied to. If this is
   *   not provided or is not writable, the temporary directory will be used.
   * @param $replace
   *   A boolean indicating whether an existing file of the same name in the
   *   destination directory should overwritten. A FALSE value will generate a
   *   new, unique filename in the destination directory.
   * @return
   *   An object containing the file information, or FALSE in the event of an 
   *   error.
   */

  static function save_upload($source) {
    // check and see if there were any errors.
    if (drupal_file_upload::upload_error($source)) {
      return FALSE;
    }

    // Begin building file object.
    $file = new stdClass();
    $file->source   = $source;
    $file->uid      = $user->uid;
    $file->filename = basename($_FILES['files']['name'][$source]);
    // create a tmp path to use until the file is save to a final location else where.
    // we just use a random string to defang the file for processing in tmp.
    $file->filepath = file_destination(uniqid(),  file_directory_temp(), FALSE);
    $file->filemime = $_FILES['files']['type'][$source];
    $file->filesize = $_FILES['files']['size'][$source];


    // Move uploaded files from PHP's upload_tmp_dir to Drupal's temporary 
    // directory. This overcomes open_basedir restrictions for future file
    // operations.
    if (!move_uploaded_file($_FILES['files']['tmp_name'][$source], $file->filepath)) {
      form_set_error($source, t('File upload error. Could not move uploaded file.'));
      watchdog('file api', 'Upload error. Could not move uploaded file %file to destination %destination.', array('%file' => $file->filename, '%destination' => $file->filepath));
      return FALSE;
    }
    return $file;
  }

  function upload_error($errno) {
    // If no file was uploaded there is an error. :)
    if (empty($_FILES['files']['tmp_name'][$source]) || !is_uploaded_file($_FILES['files']['tmp_name'][$source])) {
      return t('No file uploaded');
    }


    // @see http://php.net/manual/en/features.file-upload.errors.php
    switch ($_FILES['files']['error'][$source]) {
      case UPLOAD_ERR_OK:
        return FALSE;

      case UPLOAD_ERR_INI_SIZE:
      case UPLOAD_ERR_FORM_SIZE:
        return t('The file %file could not be saved, because it exceeds %maxsize, the maximum allowed size for uploads.', array('%file' => $source, '%maxsize' => format_size(file_upload_max_size())));

      case UPLOAD_ERR_PARTIAL:
      case UPLOAD_ERR_NO_FILE:
        return t('The file %file could not be saved, because the upload did not complete.', array('%file' => $source));

      case UPLOAD_ERR_NO_TMP_DIR:
        return t('The file %file could not be saved, because the PHP upload_tmp_dir does not exist.', array('%file' => $source));
          
      case UPLOAD_ERR_CANT_WRITE:
        return t('The file %file could not be saved, because the file could not be written to the disk.', array('%file' => $source));

      case UPLOAD_ERR_EXTENSION:
        return t('The file %file could not be saved, because the upload was stopped by a php extension.', array('%file' => $source));

      // Unknown error
      default:
        return t('The file %file could not be saved. An unknown error has occurred.', array('%file' => $source));
    }
  } 

  // Use static load as the entry point to keep the API interface
  // consistent.    
  function load($source) {
    if (isset(self::$files[$source])) return self::$files[$source];

    // attempt to save the upload.
    if ($file = self::save_upload($source)) {
      return new StreamPublic($file);
    }
  }

}
  
