[Sommaire] [Imprimer]

   1  <?php
   2  
   3  require_once 'PEAR.php';
   4  require_once 'Log.php';
   5  
   6  define('VFS_QUOTA_METRIC_BYTE', 1);
   7  define('VFS_QUOTA_METRIC_KB', 2);
   8  define('VFS_QUOTA_METRIC_MB', 3);
   9  define('VFS_QUOTA_METRIC_GB', 4);
  10  
  11  /**
  12   * VFS API for abstracted file storage and access.
  13   *
  14   * $Horde: framework/VFS/VFS.php,v 1.69.4.16 2006/08/07 00:30:14 chuck Exp $
  15   *
  16   * Copyright 2002-2006 Chuck Hagenbuch <chuck@horde.org>
  17   *
  18   * See the enclosed file COPYING for license information (LGPL). If you did
  19   * not receive this file, see http://www.fsf.org/copyleft/lgpl.html.
  20   *
  21   * @author  Chuck Hagenbuch <chuck@horde.org>
  22   * @package VFS
  23   * @since   Horde 2.2
  24   */
  25  class VFS {
  26  
  27      /**
  28       * Hash containing connection parameters.
  29       *
  30       * @var array
  31       */
  32      var $_params = array();
  33  
  34      /**
  35       * List of additional credentials required for this VFS backend (example:
  36       * For FTP, we need a username and password to log in to the server with).
  37       *
  38       * @var array
  39       */
  40      var $_credentials = array();
  41  
  42      /**
  43       * List of permissions and if they can be changed in this VFS backend.
  44       *
  45       * @var array
  46       */
  47      var $_permissions = array(
  48          'owner' => array('read' => false, 'write' => false, 'execute' => false),
  49          'group' => array('read' => false, 'write' => false, 'execute' => false),
  50          'all'   => array('read' => false, 'write' => false, 'execute' => false));
  51  
  52      /**
  53       * A PEAR Log object. If present, will be used to log errors and
  54       * informational messages about VFS activity.
  55       *
  56       * @var Log
  57       */
  58      var $_logger = null;
  59  
  60      /**
  61       * The log level to use - messages with a higher log level than configured
  62       * here will not be logged. Defaults to only logging errors or higher.
  63       *
  64       * @var integer
  65       */
  66      var $_logLevel = PEAR_LOG_ERR;
  67  
  68      /**
  69       * The current size, in bytes, of the VFS item.
  70       *
  71       * @var integer
  72       */
  73      var $_vfsSize = null;
  74  
  75      /**
  76       * Constructor.
  77       *
  78       * @param array $params  A hash containing connection parameters.
  79       */
  80      function VFS($params = array())
  81      {
  82          if (empty($params['user'])) {
  83              $params['user'] = '';
  84          }
  85          if (empty($params['vfs_quotalimit'])) {
  86              $params['vfs_quotalimit'] = -1;
  87          }
  88          if (empty($params['vfs_quotaroot'])) {
  89              $params['vfs_quotaroot'] = '/';
  90          }
  91          $this->_params = $params;
  92      }
  93  
  94      /**
  95       * Checks the credentials that we have by calling _connect(), to see if
  96       * there is a valid login.
  97       *
  98       * @return mixed  True on success, PEAR_Error describing the problem if the
  99       *                credentials are invalid.
 100       */
 101      function checkCredentials()
 102      {
 103          return $this->_connect();
 104      }
 105  
 106      /**
 107       * Sets configuration parameters.
 108       *
 109       * @param array $params  An associative array with parameter names as keys.
 110       */
 111      function setParams($params = array())
 112      {
 113          foreach ($params as $name => $value) {
 114              $this->_params[$name] = $value;
 115          }
 116      }
 117  
 118      /**
 119       * Returns configuration parameters.
 120       *
 121       * @param string $name  The parameter to return.
 122       *
 123       * @return mixed  The parameter value or null if it doesn't exist.
 124       */
 125      function getParam($name)
 126      {
 127          return isset($this->_params[$name]) ? $this->_params[$name] : null;
 128      }
 129  
 130      /**
 131       * Logs a message if a PEAR Log object is available, and the message's
 132       * priority is lower than or equal to the configured log level.
 133       *
 134       * @param mixed   $message   The message to be logged.
 135       * @param integer $priority  The message's priority.
 136       */
 137      function log($message, $priority = PEAR_LOG_ERR)
 138      {
 139          if (!isset($this->_logger) || $priority > $this->_logLevel) {
 140              return;
 141          }
 142  
 143          if (is_a($message, 'PEAR_Error')) {
 144              $userinfo = $message->getUserInfo();
 145              $message = $message->getMessage();
 146              if ($userinfo) {
 147                  if (is_array($userinfo)) {
 148                      $userinfo = implode(', ', $userinfo);
 149                  }
 150                  $message .= ': ' . $userinfo;
 151              }
 152          }
 153  
 154          /* Make sure to log in the system's locale. */
 155          $locale = setlocale(LC_TIME, 0);
 156          setlocale(LC_TIME, 'C');
 157  
 158          $this->_logger->log($message, $priority);
 159  
 160          /* Restore original locale. */
 161          setlocale(LC_TIME, $locale);
 162      }
 163  
 164      /**
 165       * Sets the PEAR Log object used to log informational or error messages.
 166       *
 167       * @param Log &$logger  The Log object to use.
 168       */
 169      function setLogger(&$logger, $logLevel = null)
 170      {
 171          if (!is_a($logger, 'Log')) {
 172              return false;
 173          }
 174  
 175          $this->_logger = &$logger;
 176          if (!is_null($logLevel)) {
 177              $this->_logLevel = $logLevel;
 178          }
 179      }
 180  
 181      /**
 182       * Retrieves the size of a file from the VFS.
 183       *
 184       * @abstract
 185       *
 186       * @param string $path  The pathname to the file.
 187       * @param string $name  The filename to retrieve.
 188       *
 189       * @return integer The file size.
 190       */
 191      function size($path, $name)
 192      {
 193          return PEAR::raiseError(_("Not supported."));
 194      }
 195  
 196      /**
 197       * Returns the size of a folder
 198       *
 199       * @since Horde 3.1
 200       *
 201       * @param string $path  The path to the folder.
 202       * @param string $name  The name of the folder.
 203       *
 204       * @return integer  The size of the folder, in bytes, or PEAR_Error on
 205       *                  failure.
 206       */
 207      function getFolderSize($path = null, $name = null)
 208      {
 209          $size = 0;
 210          $root = ((!is_null($path)) ? $path . '/' : '') . $name;
 211          $object_list = $this->listFolder($root, null, true, false, true);
 212          foreach ($object_list as $key => $val) {
 213              if (isset($val['subdirs'])) {
 214                  $size += $this->getFolderSize($root, $key);
 215              } else {
 216                  $filesize = $this->size($root, $key);
 217                  if (is_a($filesize, 'PEAR_Error')) {
 218                      return $filesize;
 219                  }
 220                  $size += $filesize;
 221              }
 222          }
 223  
 224          return $size;
 225      }
 226  
 227      /**
 228       * Retrieves a file from the VFS.
 229       *
 230       * @abstract
 231       *
 232       * @param string $path  The pathname to the file.
 233       * @param string $name  The filename to retrieve.
 234       *
 235       * @return string The file data.
 236       */
 237      function read($path, $name)
 238      {
 239          return PEAR::raiseError(_("Not supported."));
 240      }
 241  
 242      /**
 243       * Retrieves a part of a file from the VFS. Particularly useful when
 244       * reading large files which would exceed the PHP memory limits if they
 245       * were stored in a string.
 246       *
 247       * @abstract
 248       *
 249       * @param string  $path       The pathname to the file.
 250       * @param string  $name       The filename to retrieve.
 251       * @param integer $offset     The offset of the part. (The new offset will
 252       *                            be stored in here).
 253       * @param integer $length     The length of the part. If the length = -1,
 254       *                            the whole part after the offset is retrieved.
 255       *                            If more bytes are given as exists after the
 256       *                            given offset. Only the available bytes are
 257       *                            read.
 258       * @param integer $remaining  The bytes that are left, after the part that
 259       *                            is retrieved.
 260       *
 261       * @return string The file data.
 262       */
 263      function readByteRange($path, $name, &$offset, $length = -1, &$remaining)
 264      {
 265          return PEAR::raiseError(_("Not supported."));
 266      }
 267  
 268      /**
 269       * Stores a file in the VFS.
 270       *
 271       * @abstract
 272       *
 273       * @param string $path         The path to store the file in.
 274       * @param string $name         The filename to use.
 275       * @param string $tmpFile      The temporary file containing the data to
 276       *                             be stored.
 277       * @param boolean $autocreate  Automatically create directories?
 278       *
 279       * @return mixed  True on success or a PEAR_Error object on failure.
 280       */
 281      function write($path, $name, $tmpFile, $autocreate = false)
 282      {
 283          return PEAR::raiseError(_("Not supported."));
 284      }
 285  
 286      /**
 287       * Stores a file in the VFS from raw data.
 288       *
 289       * @abstract
 290       *
 291       * @param string $path         The path to store the file in.
 292       * @param string $name         The filename to use.
 293       * @param string $data         The file data.
 294       * @param boolean $autocreate  Automatically create directories?
 295       *
 296       * @return mixed  True on success or a PEAR_Error object on failure.
 297       */
 298      function writeData($path, $name, $data, $autocreate = false)
 299      {
 300          return PEAR::raiseError(_("Not supported."));
 301      }
 302  
 303      /**
 304       * Moves a file through the backend.
 305       *
 306       * @abstract
 307       *
 308       * @param string $path  The path of the original file.
 309       * @param string $name  The name of the original file.
 310       * @param string $dest  The destination file name.
 311       *
 312       * @return mixed  True on success or a PEAR_Error object on failure.
 313       */
 314      function move($path, $name, $dest)
 315      {
 316          return PEAR::raiseError(_("Not supported."));
 317      }
 318  
 319      /**
 320       * Copies a file through the backend.
 321       *
 322       * @abstract
 323       *
 324       * @param string $path  The path of the original file.
 325       * @param string $name  The name of the original file.
 326       * @param string $dest  The name of the destination directory.
 327       *
 328       * @return mixed  True on success or a PEAR_Error object on failure.
 329       */
 330      function copy($path, $name, $dest)
 331      {
 332          return PEAR::raiseError(_("Not supported."));
 333      }
 334  
 335      /**
 336       * Deletes a file from the VFS.
 337       *
 338       * @abstract
 339       *
 340       * @param string $path  The path to delete the file from.
 341       * @param string $name  The filename to delete.
 342       *
 343       * @return mixed  True on success or a PEAR_Error object on failure.
 344       */
 345      function deleteFile($path, $name)
 346      {
 347          return PEAR::raiseError(_("Not supported."));
 348      }
 349  
 350      /**
 351       * Renames a file in the VFS.
 352       *
 353       * @abstract
 354       *
 355       * @param string $oldpath  The old path to the file.
 356       * @param string $oldname  The old filename.
 357       * @param string $newpath  The new path of the file.
 358       * @param string $newname  The new filename.
 359       *
 360       * @return mixed  True on success or a PEAR_Error object on failure.
 361       */
 362      function rename($oldpath, $oldname, $newpath, $newname)
 363      {
 364          return PEAR::raiseError(_("Not supported."));
 365      }
 366  
 367      /**
 368       * Returns if a given file or folder exists in a folder.
 369       *
 370       * @param string $path  The path to the folder.
 371       * @param string $name  The file or folder name.
 372       *
 373       * @return boolean  True if it exists, false otherwise.
 374       */
 375      function exists($path, $name)
 376      {
 377          $list = $this->listFolder($path);
 378          if (is_a($list, 'PEAR_Error')) {
 379              return false;
 380          } else {
 381              return isset($list[$name]);
 382          }
 383      }
 384  
 385      /**
 386       * Creates a folder in the VFS.
 387       *
 388       * @abstract
 389       *
 390       * @param string $path  The parent folder.
 391       * @param string $name  The name of the new folder.
 392       *
 393       * @return mixed  True on success or a PEAR_Error object on failure.
 394       */
 395      function createFolder($path, $name)
 396      {
 397          return PEAR::raiseError(_("Not supported."));
 398      }
 399  
 400      /**
 401       * Automatically creates any necessary parent directories in the specified
 402       * $path.
 403       *
 404       * @param string $path  The VFS path to autocreate.
 405       */
 406      function autocreatePath($path)
 407      {
 408          $dirs = explode('/', $path);
 409          if (is_array($dirs)) {
 410              $cur = '/';
 411              foreach ($dirs as $dir) {
 412                  if (!empty($dir)) {
 413                      if (!$this->isFolder($cur, $dir)) {
 414                          $result = $this->createFolder($cur, $dir);
 415                          if (is_a($result, 'PEAR_Error')) {
 416                              return $result;
 417                          }
 418                      }
 419                      if ($cur != '/') {
 420                          $cur .= '/';
 421                      }
 422                      $cur .= $dir;
 423                  }
 424              }
 425          }
 426  
 427          return true;
 428      }
 429  
 430      /**
 431       * Checks if a given item is a folder.
 432       *
 433       * @param string $path  The parent folder.
 434       * @param string $name  The item name.
 435       *
 436       * @return boolean  True if it is a folder, false otherwise.
 437       */
 438      function isFolder($path, $name)
 439      {
 440          $folderList = $this->listFolder($path, null, true, true);
 441          return isset($folderList[$name]);
 442      }
 443  
 444      /**
 445       * Deletes a folder from the VFS.
 446       *
 447       * @abstract
 448       *
 449       * @param string $path        The parent folder.
 450       * @param string $name        The name of the folder to delete.
 451       * @param boolean $recursive  Force a recursive delete?
 452       *
 453       * @return mixed  True on success or a PEAR_Error object on failure.
 454       */
 455      function deleteFolder($path, $name, $recursive = false)
 456      {
 457          return PEAR::raiseError(_("Not supported."));
 458      }
 459  
 460      /**
 461       * Recursively remove all files and subfolders from the given
 462       * folder.
 463       *
 464       * @param string $path  The path of the folder to empty.
 465       *
 466       * @return mixed  True on success or a PEAR_Error object on failure.
 467       */
 468      function emptyFolder($path)
 469      {
 470          // Get and delete the subfolders.
 471          $list = $this->listFolder($path, null, true, true);
 472          if (is_a($list, 'PEAR_Error')) {
 473              return $list;
 474          }
 475          foreach ($list as $folder) {
 476              $result = $this->deleteFolder($path, $folder['name'], true);
 477              if (is_a($result, 'PEAR_Error')) {
 478                  return $result;
 479              }
 480          }
 481          // Only files are left, get and delete them.
 482          $list = $this->listFolder($path);
 483          if (is_a($list, 'PEAR_Error')) {
 484              return $list;
 485          }
 486          foreach ($list as $file) {
 487              $result = $this->deleteFile($path, $file['name']);
 488              if (is_a($result, 'PEAR_Error')) {
 489                  return $result;
 490              }
 491          }
 492  
 493          return true;
 494      }
 495  
 496      /**
 497       * Returns a file list of the directory passed in.
 498       *
 499       * @param string $path        The path of the directory.
 500       * @param mixed $filter       String/hash to filter file/dirname on.
 501       * @param boolean $dotfiles   Show dotfiles?
 502       * @param boolean $dironly    Show only directories?
 503       * @param boolean $recursive  Return all directory levels recursively?
 504       *
 505       * @return array  File list on success or PEAR_Error on failure.
 506       */
 507      function listFolder($path, $filter = null, $dotfiles = true,
 508                          $dironly = false, $recursive = false)
 509      {
 510          $list = $this->_listFolder($path, $filter, $dotfiles, $dironly);
 511          if (!$recursive || is_a($list, 'PEAR_Error')) {
 512              return $list;
 513          }
 514  
 515          foreach ($list as $name => $values) {
 516              if ($values['type'] == '**dir') {
 517                  $list[$name]['subdirs'] = $this->listFolder($path . '/' . $name, $filter, $dotfiles, $dironly, $recursive);
 518              }
 519          }
 520  
 521          return $list;
 522      }
 523  
 524      /**
 525       * Returns an an unsorted file list of the specified directory.
 526       *
 527       * @abstract
 528       *
 529       * @param string $path       The path of the directory.
 530       * @param mixed $filter      String/hash to filter file/dirname on.
 531       * @param boolean $dotfiles  Show dotfiles?
 532       * @param boolean $dironly   Show only directories?
 533       *
 534       * @return array  File list on success or PEAR_Error on failure.
 535       */
 536      function _listFolder($path, $filter = null, $dotfiles = true,
 537                           $dironly = false)
 538      {
 539          return PEAR::raiseError(_("Not supported."));
 540      }
 541  
 542      /**
 543       * Returns the current working directory of the VFS backend.
 544       *
 545       * @return string  The current working directory.
 546       */
 547      function getCurrentDirectory()
 548      {
 549          return '';
 550      }
 551  
 552      /**
 553       * Returns whether or not a filename matches any filter element.
 554       *
 555       * @access private
 556       *
 557       * @param mixed $filter     String/hash to build the regular expression
 558       *                          from.
 559       * @param string $filename  String containing the filename to match.
 560       *
 561       * @return boolean  True on match, false on no match.
 562       */
 563      function _filterMatch($filter, $filename)
 564      {
 565          $namefilter = null;
 566  
 567          // Build a regexp based on $filter.
 568          if ($filter !== null) {
 569              $namefilter = '/';
 570              if (is_array($filter)) {
 571                  $once = false;
 572                  foreach ($filter as $item) {
 573                      if ($once !== true) {
 574                          $namefilter .= '(';
 575                          $once = true;
 576                      } else {
 577                          $namefilter .= '|(';
 578                      }
 579                      $namefilter .= $item . ')';
 580                  }
 581              } else {
 582                  $namefilter .= '(' . $filter . ')';
 583              }
 584              $namefilter .= '/';
 585          }
 586  
 587          $match = false;
 588          if ($namefilter !== null) {
 589              $match = preg_match($namefilter, $filename);
 590          }
 591  
 592          return $match;
 593      }
 594  
 595      /**
 596       * Changes permissions for an item on the VFS.
 597       *
 598       * @abstract
 599       *
 600       * @param string $path        The parent folder of the item.
 601       * @param string $name        The name of the item.
 602       * @param string $permission  The permission to set.
 603       *
 604       * @return mixed  True on success or a PEAR_Error object on failure.
 605       */
 606      function changePermissions($path, $name, $permission)
 607      {
 608          return PEAR::raiseError(_("Not supported."));
 609      }
 610  
 611      /**
 612       * Returns a sorted list of folders in the specified directory.
 613       *
 614       * @abstract
 615       *
 616       * @param string $path         The path of the directory to get the
 617       *                             directory list for.
 618       * @param mixed $filter        Hash of items to filter based on folderlist.
 619       * @param boolean $dotfolders  Include dotfolders?
 620       *
 621       * @return mixed  Folder list on success or a PEAR_Error object on failure.
 622       */
 623      function listFolders($path = '', $filter = null, $dotfolders = true)
 624      {
 625          return PEAR::raiseError(_("Not supported."));
 626      }
 627  
 628      /**
 629       * Returns the list of additional credentials required, if any.
 630       *
 631       * @return array  Credential list.
 632       */
 633      function getRequiredCredentials()
 634      {
 635          return array_diff($this->_credentials, array_keys($this->_params));
 636      }
 637  
 638      /**
 639       * Returns an array specifying what permissions are changeable for this
 640       * VFS implementation.
 641       *
 642       * @return array  Changeable permisions.
 643       */
 644      function getModifiablePermissions()
 645      {
 646          return $this->_permissions;
 647      }
 648  
 649      /**
 650       * Converts a string to all lowercase characters ignoring the current
 651       * locale.
 652       *
 653       * @param string $string  The string to be lowercased
 654       *
 655       * @return string  The string with lowercase characters
 656       */
 657      function strtolower($string)
 658      {
 659          $language = setlocale(LC_CTYPE, 0);
 660          setlocale(LC_CTYPE, 'en');
 661          $string = strtolower($string);
 662          setlocale(LC_CTYPE, $language);
 663          return $string;
 664      }
 665  
 666      /**
 667       * Returns the character (not byte) length of a string.
 668       *
 669       * @param string $string   The string to return the length of.
 670       * @param string $charset  The charset to use when calculating the
 671       *                         string's length.
 672       *
 673       * @return string  The string's length.
 674       */
 675      function strlen($string, $charset = null)
 676      {
 677          if (extension_loaded('mbstring')) {
 678              if (is_null($charset)) {
 679                  $charset = 'ISO-8859-1';
 680              }
 681              $ret = @mb_strlen($string, $charset);
 682              if (!empty($ret)) {
 683                  return $ret;
 684              }
 685          }
 686          return strlen($string);
 687      }
 688  
 689      /**
 690       * Returns the size of the VFS item.
 691       *
 692       * @since Horde 3.1
 693       *
 694       * @return integer  The size, in bytes, of the VFS item.
 695       */
 696      function getVFSSize()
 697      {
 698          if (is_null($this->_vfsSize)) {
 699              $this->_vfsSize = $this->getFolderSize($this->_params['vfs_quotaroot']);
 700          }
 701          return $this->_vfsSize;
 702      }
 703  
 704      /**
 705       * Sets the VFS quota limit.
 706       *
 707       * @since Horde 3.1
 708       *
 709       * @param integer $quota   The limit to apply.
 710       * @param integer $metric  The metric to multiply the quota into.
 711       */
 712      function setQuota($quota, $metric = VFS_QUOTA_METRIC_BYTE)
 713      {
 714          switch ($metric) {
 715          case VFS_QUOTA_METRIC_KB:
 716              $quota *= pow(2, 10);
 717              break;
 718  
 719          case VFS_QUOTA_METRIC_MB:
 720              $quota *= pow(2, 20);
 721              break;
 722  
 723          case VFS_QUOTA_METRIC_GB:
 724              $quota *= pow(2, 30);
 725              break;
 726          }
 727  
 728          $this->_params['vfs_quotalimit'] = $quota;
 729      }
 730  
 731      /**
 732       * Sets the VFS quota root.
 733       *
 734       * @since Horde 3.1
 735       *
 736       * @param string $dir  The root directory for the quota determination.
 737       */
 738      function setQuotaRoot($dir)
 739      {
 740          $this->_params['vfs_quotaroot'] = $dir;
 741      }
 742  
 743      /**
 744       * Get quota information (used/allocated), in bytes.
 745       *
 746       * @since Horde 3.1
 747       *
 748       * @return mixed  An associative array.
 749       *                'limit' = Maximum quota allowed
 750       *                'usage' = Currently used portion of quota (in bytes)
 751       *                Returns PEAR_Error on failure.
 752       */
 753      function getQuota()
 754      {
 755          if (empty($this->_params['vfs_quotalimit'])) {
 756              return PEAR::raiseError(_("No quota set."));
 757          }
 758  
 759          $usage = $this->getVFSSize();
 760          if (is_a($usage, 'PEAR_Error')) {
 761              return $usage;
 762          } else {
 763              return array('usage' => $usage, 'limit' => $this->_params['vfs_quotalimit']);
 764          }
 765      }
 766  
 767      /**
 768       * Determines the location of the system temporary directory.
 769       *
 770       * @access protected
 771       *
 772       * @return string  A directory name which can be used for temp files.
 773       *                 Returns false if one could not be found.
 774       */
 775      function _getTempDir()
 776      {
 777          $tmp_locations = array('/tmp', '/var/tmp', 'c:\WUTemp', 'c:\temp',
 778                                 'c:\windows\temp', 'c:\winnt\temp');
 779  
 780          /* Try PHP's upload_tmp_dir directive. */
 781          $tmp = ini_get('upload_tmp_dir');
 782  
 783          /* Otherwise, try to determine the TMPDIR environment variable. */
 784          if (empty($tmp)) {
 785              $tmp = getenv('TMPDIR');
 786          }
 787  
 788          /* If we still cannot determine a value, then cycle through a list of
 789           * preset possibilities. */
 790          while (empty($tmp) && sizeof($tmp_locations)) {
 791              $tmp_check = array_shift($tmp_locations);
 792              if (@is_dir($tmp_check)) {
 793                  $tmp = $tmp_check;
 794              }
 795          }
 796  
 797          /* If it is still empty, we have failed, so return false; otherwise
 798           * return the directory determined. */
 799          return empty($tmp) ? false : $tmp;
 800      }
 801  
 802      /**
 803       * Creates a temporary file.
 804       *
 805       * @access protected
 806       *
 807       * @return string   Returns the full path-name to the temporary file or
 808       *                  false if a temporary file could not be created.
 809       */
 810      function _getTempFile()
 811      {
 812          $tmp_dir = $this->_getTempDir();
 813          if (empty($tmp_dir)) {
 814              return false;
 815          }
 816  
 817          $tmp_file = tempnam($tmp_dir, 'vfs');
 818  
 819          /* If the file was created, then register it for deletion and
 820           * return. */
 821          if (empty($tmp_file)) {
 822              return false;
 823          } else {
 824              return $tmp_file;
 825          }
 826      }
 827  
 828      /**
 829       * Checks the quota when preparing to write data.
 830       *
 831       * @access private
 832       *
 833       * @param string $mode   Either 'string' or 'file'.  If 'string', $data is
 834       *                       the data to be written.  If 'file', $data is the
 835       *                       filename containing the data to be written.
 836       * @param string &$data  Either the data or the filename to the data.
 837       *
 838       * @return mixed  PEAR_Error on error, true on success.
 839       */
 840      function _checkQuotaWrite($mode, &$data)
 841      {
 842          if ($this->_params['vfs_quotalimit'] != -1) {
 843              if ($mode == 'file') {
 844                  $filesize = @filesize($data);
 845                  if ($filesize === false) {
 846                      return PEAR::raiseError(_("Unable to read VFS file (filesize() failed)."));
 847                 }
 848              } else {
 849                  $filesize = strlen($data);
 850              }
 851              $vfssize = $this->getVFSSize();
 852              if (is_a($vfssize, 'PEAR_Error')) {
 853                  return $vfssize;
 854              }
 855              if (($vfssize + $filesize) > $this->_params['vfs_quotalimit']) {
 856                  return PEAR::raiseError(_("Unable to write VFS file, quota will be exceeded."));
 857              } elseif ($this->_vfsSize !== 0) {
 858                  $this->_vfsSize += $filesize;
 859              }
 860          }
 861  
 862          return true;
 863      }
 864  
 865      /**
 866       * Checks the quota when preparing to delete data.
 867       *
 868       * @access private
 869       *
 870       * @param string $path  The path the file is located in.
 871       * @param string $name  The filename.
 872       *
 873       * @return mixed  PEAR_Error on error, true on success.
 874       */
 875      function _checkQuotaDelete($path, $name)
 876      {
 877          if (($this->_params['vfs_quotalimit'] != -1) &&
 878              !empty($this->_vfsSize)) {
 879              $filesize = $this->size($path, $name);
 880              if (is_a($filesize, 'PEAR_Error')) {
 881                  return PEAR::raiseError(_("Unable to read VFS file (size() failed)."));
 882              }
 883              $this->_vfsSize -= $filesize;
 884          }
 885  
 886          return true;
 887      }
 888  
 889      /**
 890       * Attempts to return a concrete VFS instance based on $driver.
 891       *
 892       * @param mixed $driver  The type of concrete VFS subclass to return. This
 893       *                       is based on the storage driver ($driver). The
 894       *                       code is dynamically included.
 895       * @param array $params  A hash containing any additional configuration or
 896       *                       connection parameters a subclass might need.
 897       *
 898       * @return VFS  The newly created concrete VFS instance, or a PEAR_Error
 899       *              on failure.
 900       */
 901      function &factory($driver, $params = array())
 902      {
 903          include_once 'VFS/' . $driver . '.php';
 904          $class = 'VFS_' . $driver;
 905          if (class_exists($class)) {
 906              $vfs = &new $class($params);
 907          } else {
 908              $vfs = PEAR::raiseError(sprintf(_("Class definition of %s not found."), $class));
 909          }
 910  
 911          return $vfs;
 912      }
 913  
 914      /**
 915       * Attempts to return a reference to a concrete VFS instance based on
 916       * $driver. It will only create a new instance if no VFS instance with the
 917       * same parameters currently exists.
 918       *
 919       * This should be used if multiple types of file backends (and, thus,
 920       * multiple VFS instances) are required.
 921       *
 922       * This method must be invoked as: $var = &VFS::singleton()
 923       *
 924       * @param mixed $driver  The type of concrete VFS subclass to return. This
 925       *                       is based on the storage driver ($driver). The
 926       *                       code is dynamically included.
 927       * @param array $params  A hash containing any additional configuration or
 928       *                       connection parameters a subclass might need.
 929       *
 930       * @return VFS  The concrete VFS reference, or a PEAR_Error on failure.
 931       */
 932      function &singleton($driver, $params = array())
 933      {
 934          static $instances;
 935          if (!isset($instances)) {
 936              $instances = array();
 937          }
 938  
 939          $signature = serialize(array($driver, $params));
 940          if (!isset($instances[$signature])) {
 941              $instances[$signature] = &VFS::factory($driver, $params);
 942          }
 943  
 944          return $instances[$signature];
 945      }
 946  
 947  }