[Sommaire] [Imprimer]

   1  <?php
   2  //
   3  // Definition of eZFileHandler class
   4  //
   5  // Created on: <13-Aug-2003 16:20:19 amos>
   6  //
   7  // SOFTWARE NAME: eZ publish
   8  // SOFTWARE RELEASE: 3.9.0
   9  // BUILD VERSION: 17785
  10  // COPYRIGHT NOTICE: Copyright (C) 1999-2006 eZ systems AS
  11  // SOFTWARE LICENSE: GNU General Public License v2.0
  12  // NOTICE: >
  13  //   This program is free software; you can redistribute it and/or
  14  //   modify it under the terms of version 2.0  of the GNU General
  15  //   Public License as published by the Free Software Foundation.
  16  //
  17  //   This program is distributed in the hope that it will be useful,
  18  //   but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  //   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20  //   GNU General Public License for more details.
  21  //
  22  //   You should have received a copy of version 2.0 of the GNU General
  23  //   Public License along with this program; if not, write to the Free
  24  //   Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
  25  //   MA 02110-1301, USA.
  26  //
  27  //
  28  
  29  /*! \file ezfilehandler.php
  30  */
  31  
  32  /*!
  33    \class eZFileHandler ezfilehandler.php
  34    \brief Interface for file handlers
  35  
  36    Generic interface for all file handlers.
  37  
  38    Using this class i divided into five areas, they are:
  39  
  40    File handling using open(), close(), read(), write() and flush().
  41  
  42    File position handling using seek(), tell(), rewind() and eof().
  43  
  44    Quick output of the file using passtrough().
  45  
  46    Error handling with error(), errorString() and errorNumber().
  47  
  48    \h1 Creating specific handlers
  49  
  50    The file handlers must inherit from this class and reimplement
  51    some virtual functions.
  52  
  53    For dealing with files the following functions must be reimplemented.
  54    doOpen(), doClose(), doRead(), doWrite() and doFlush().
  55  
  56    For dealing with file positions the following functions must be reimplemented.
  57    doSeek(), doTell(), doRewind() and doEOF().
  58  
  59    For dealing with quick output the passtrough() function must be reimplemented,
  60    if not reimplemented the default implemententation will simply read n bytes
  61    using read() and output it with print.
  62  
  63    Also the errorString() and errorNumber() functions must be reimplemented
  64    to provide proper error handler. The error() function is not required
  65    to be implemented since it has a default implementation, for speed
  66    it might be wise to implement the function.
  67  
  68    This class will handle most of the generic logic, like checking that
  69    the filename is correct and if the open succeded, and give error
  70    messages based on this.
  71    The actual implementations will only have to execute the specific
  72    code and return a result.
  73  
  74  */
  75  
  76  class eZFileHandler
  77  {
  78      /*!
  79       Initializes the handler. Optionally the parameters \a $filename
  80       and \a $mode may be provided to automatically open the file.
  81      */
  82      function eZFileHandler( $handlerIdentifier = false, $handlerName = false )
  83      {
  84          if ( !$handlerIdentifier )
  85          {
  86              $handlerIdentifier = 'plain';
  87              $handlerName = 'Plain';
  88          }
  89          $this->Name = $handlerName;
  90          $this->Identifier = $handlerIdentifier;
  91          $this->FileName = false;
  92          $this->FileHandler = false;
  93          $this->Mode = false;
  94          $this->IsOpen = false;
  95          $this->IsBinary = false;
  96      }
  97  
  98      /*!
  99       \return \c true if a file is opened, \c false otherwise.
 100      */
 101      function isOpen()
 102      {
 103          return $this->IsOpen;
 104      }
 105  
 106      /*!
 107       \return \c true if the file was opened in binary mode.
 108      */
 109      function isBinaryMode()
 110      {
 111          return $this->IsBinary;
 112      }
 113  
 114      /*!
 115       \return the filename currently in use.
 116      */
 117      function filename()
 118      {
 119          return $this->FileName;
 120      }
 121  
 122      /*!
 123       \return the mode which was used to open the currently used file.
 124      */
 125      function mode()
 126      {
 127          return $this->Mode;
 128      }
 129  
 130      /*!
 131       \return the name of current handler.
 132       \sa identifier
 133      */
 134      function name()
 135      {
 136          return $this->Name;
 137      }
 138  
 139      /*!
 140       \return the identifier of the current handler.
 141       \sa name
 142      */
 143      function identifier()
 144      {
 145          return $this->Identifier;
 146      }
 147  
 148      /*!
 149       \virtual
 150       \return true if this handler can be used.
 151       \note The default implementation is to return \c true for all handlers.
 152      */
 153      function isAvailable()
 154      {
 155          return true;
 156      }
 157  
 158      /*!
 159       Links the file \a $sourceFilename to \a $destinationFilename.
 160       If \a $destinationFilename is a directory then the filename is taken from \a $sourceFilename and appended to the destination.
 161       It will use symbolic links for the operating system that support it and file copy for all others.
 162       \param $symbolicLink if \c true then the files will be made as symbolic links, otherwise as hard links.
 163       \return \c true if sucessful or \c false if the copy failed.
 164      */
 165      function linkCopy( $sourceFilename, $destinationFilename, $symbolicLink = true )
 166      {
 167          if ( in_array( eZSys::osType(),
 168                         array( 'unix', 'linux', 'mac' ) ) )
 169          {
 170              if ( $symbolicLink )
 171                  $result = eZFileHandler::symlink( $sourceFilename, $destinationFilename );
 172              else
 173                  $result = eZFileHandler::link( $sourceFilename, $destinationFilename );
 174              if ( $result )
 175                  return $result;
 176              return eZFileHandler::copy( $sourceFilename, $destinationFilename );
 177          }
 178          else
 179          {
 180              return eZFileHandler::copy( $sourceFilename, $destinationFilename );
 181          }
 182      }
 183  
 184      /*!
 185       Creates a symbolic link to the file \a $sourceFilename on the destination \a $destinationFilename.
 186       This means that if someone tries to open \a $destinationFilename they will infact open \a $sourceFilename.
 187       If \a $destinationFilename is a directory then the filename is taken from \a $sourceFilename and appended to the destination.
 188       It will first try to rename the file and if that does not work copy the file and unlink.
 189       \return \c true if sucessful or \c false if the copy failed.
 190      */
 191      function symlink( $sourceFilename, $destinationFilename )
 192      {
 193          if ( !file_exists( $sourceFilename ) and
 194               !is_link( $sourceFilename ) )
 195          {
 196              eZDebug::writeError( "Cannot symbolicly link to file $sourceFilename, it does not exist",
 197                                   'eZFileHandler::symlink' );
 198              return false;
 199          }
 200          $isDir = false;
 201          if ( is_dir( $destinationFilename ) )
 202          {
 203              $isDir = true;
 204              $dirPosition = strrpos( $sourceFilename, '/' );
 205              $filePosition = 0;
 206              if ( $dirPosition !== false )
 207                  $filePosition = $dirPosition + 1;
 208              if ( strlen( $destinationFilename ) > 0 and
 209                   $destinationFilename[strlen( $destinationFilename ) - 1] == '/' )
 210                  $destinationFilename .= substr( $sourceFilename, $filePosition );
 211              else
 212                  $destinationFilename .= '/' . substr( $sourceFilename, $filePosition );
 213          }
 214          $destinationFilename = preg_replace( "#/+#", '/', $destinationFilename );
 215          $sourceDir = $sourceFilename;
 216          $sourceName = false;
 217          $sourceDirPos = strrpos( $sourceDir, '/' );
 218          if ( $sourceDirPos !== false )
 219          {
 220              $sourceName = substr( $sourceDir, $sourceDirPos + 1 );
 221              $sourceDir = substr( $sourceDir, 0, $sourceDirPos );
 222          }
 223          $commonOffset = 0;
 224          for ( $i = 0; $i < strlen( $sourceFilename ) and $i < strlen( $sourceDir ); ++$i )
 225          {
 226              if ( $sourceFilename[$i] != $sourceDir[$i] )
 227                  break;
 228              $commonOffset = $i;
 229          }
 230          if ( $commonOffset > 0 )
 231              $sourceDir = substr( $sourceDir, $commonOffset + 1 );
 232          $directoryCount = substr_count( $sourceDir, '/' );
 233          $cdupText = str_repeat( '../', $directoryCount );
 234          if ( file_exists( $destinationFilename ) and
 235               !is_dir( $destinationFilename ) )
 236          {
 237              if ( !@unlink( $destinationFilename ) )
 238              {
 239                  eZDebug::writeError( "Cannot symbolicly link to file $sourceFilename on destination $destinationFilename, destination file cannot be removed",
 240                                       'eZFileHandler::symlink' );
 241                  return false;
 242              }
 243          }
 244          if ( $sourceDir )
 245              $sourceDir = $sourceDir . '/' . $sourceName;
 246          else
 247              $sourceDir = $sourceName;
 248          if ( symlink( $cdupText . $sourceDir, $destinationFilename ) )
 249          {
 250              return true;
 251          }
 252          eZDebug::writeError( "Failed to symbolicly link to $sourceFilename on destination $destinationFilename",
 253                               'eZFileHandler::symlink' );
 254          return false;
 255      }
 256  
 257      /*!
 258       Creates a symbolic link to the file \a $sourceFilename on the destination \a $destinationFilename.
 259       This means that if someone tries to open \a $destinationFilename they will infact open \a $sourceFilename.
 260       If \a $destinationFilename is a directory then the filename is taken from \a $sourceFilename and appended to the destination.
 261       It will first try to rename the file and if that does not work copy the file and unlink.
 262       \return \c true if sucessful or \c false if the copy failed.
 263      */
 264      function link( $sourceFilename, $destinationFilename )
 265      {
 266          if ( !file_exists( $sourceFilename ) and
 267               !is_link( $sourceFilename ) )
 268          {
 269              eZDebug::writeError( "Cannot link to file $sourceFilename, it does not exist",
 270                                   'eZFileHandler::link' );
 271              return false;
 272          }
 273          $isDir = false;
 274          if ( is_dir( $destinationFilename ) )
 275          {
 276              $isDir = true;
 277              $dirPosition = strrpos( $sourceFilename, '/' );
 278              $filePosition = 0;
 279              if ( $dirPosition !== false )
 280                  $filePosition = $dirPosition + 1;
 281              if ( strlen( $destinationFilename ) > 0 and
 282                   $destinationFilename[strlen( $destinationFilename ) - 1] == '/' )
 283                  $destinationFilename .= substr( $sourceFilename, $filePosition );
 284              else
 285                  $destinationFilename .= '/' . substr( $sourceFilename, $filePosition );
 286          }
 287          $destinationFilename = preg_replace( "#/+#", '/', $destinationFilename );
 288          if ( file_exists( $destinationFilename ) and
 289               !is_dir( $destinationFilename ) )
 290          {
 291              if ( !@unlink( $destinationFilename ) )
 292              {
 293                  eZDebug::writeError( "Cannot link to file $sourceFilename on destination $destinationFilename, destination file cannot be removed",
 294                                       'eZFileHandler::link' );
 295                  return false;
 296              }
 297          }
 298          if ( link( $sourceFilename, $destinationFilename ) )
 299          {
 300              return true;
 301          }
 302          eZDebug::writeError( "Failed to link to $sourceFilename on destination $destinationFilename",
 303                               'eZFileHandler::link' );
 304          return false;
 305      }
 306  
 307      /*!
 308       Moves the file \a $sourceFilename to \a $destinationFilename.
 309       If \a $destinationFilename is a directory then the filename is taken from \a $sourceFilename and appended to the destination.
 310       It will first try to rename the file and if that does not work copy the file and unlink.
 311       \return \c true if sucessful or \c false if the copy failed.
 312      */
 313      function move( $sourceFilename, $destinationFilename )
 314      {
 315          // VS-DBFILE : TODO
 316  
 317          if ( !file_exists( $sourceFilename ) and
 318               !is_link( $sourceFilename ) )
 319          {
 320              eZDebug::writeError( "Cannot rename file $sourceFilename, it does not exist",
 321                                   'eZFileHandler::move' );
 322              return false;
 323          }
 324          $isDir = false;
 325          if ( is_dir( $destinationFilename ) )
 326          {
 327              $isDir = true;
 328              $dirPosition = strrpos( $sourceFilename, '/' );
 329              $filePosition = 0;
 330              if ( $dirPosition !== false )
 331                  $filePosition = $dirPosition + 1;
 332              if ( strlen( $destinationFilename ) > 0 and
 333                   $destinationFilename[strlen( $destinationFilename ) - 1] == '/' )
 334                  $destinationFilename .= substr( $sourceFilename, $filePosition );
 335              else
 336                  $destinationFilename .= '/' . substr( $sourceFilename, $filePosition );
 337          }
 338  
 339  
 340          // If source and destination are the same files we just return true
 341          if ( $sourceFilename == $destinationFilename )
 342          {
 343              return true;
 344          }
 345  
 346          if ( file_exists( $destinationFilename ) and
 347               !is_dir( $destinationFilename ) )
 348          {
 349              if ( !@unlink( $destinationFilename ) )
 350              {
 351                  eZDebug::writeError( "Cannot move file $sourceFilename to destination $destinationFilename, destination file cannot be removed",
 352                                       'eZFileHandler::move' );
 353                  return false;
 354              }
 355          }
 356          $isLink = false;
 357          if ( is_link( $sourceFilename ) )
 358          {
 359              $isLink = true;
 360          }
 361          if ( !$isLink and
 362               @rename( $sourceFilename, $destinationFilename ) )
 363          {
 364              return true;
 365          }
 366          if ( eZFileHandler::copy( $sourceFilename, $destinationFilename ) )
 367          {
 368              if ( !@unlink( $sourceFilename ) )
 369              {
 370                  eZDebug::writeError( "Cannot remove source file $sourceFilename, file was not succesfully moved",
 371                                       'eZFileHandler::move' );
 372                  @unlink( $destinationFilename );
 373                  return false;
 374              }
 375              return true;
 376          }
 377                  eZDebug::writeError( "Failed to copy $sourceFilename to $destinationFilename, file was not succesfully moved",
 378                                       'eZFileHandler::move' );
 379          return false;
 380      }
 381  
 382      /*!
 383       Copies the file \a $sourceFilename to \a $destinationFilename.
 384       \return \c true if sucessful or \c false if the copy failed.
 385      */
 386      function copy( $sourceFilename, $destinationFilename )
 387      {
 388          if ( is_dir( $sourceFilename ) )
 389          {
 390              eZDebug::writeError( "Unable to copy directory $sourceFilename, use eZDir::copy instead",
 391                                   'eZFileHandler::copy' );
 392              return false;
 393          }
 394          $sourceFD = @fopen( $sourceFilename, 'rb' );
 395          if ( !$sourceFD )
 396          {
 397              eZDebug::writeError( "Unable to open source file $sourceFilename in read mode",
 398                                   'eZFileHandler::copy' );
 399              return false;
 400          }
 401          if ( is_dir( $destinationFilename ) )
 402          {
 403              $dirPosition = strrpos( $sourceFilename, '/' );
 404              $filePosition = 0;
 405              if ( $dirPosition !== false )
 406                  $filePosition = $dirPosition + 1;
 407              if ( strlen( $destinationFilename ) > 0 and
 408                   $destinationFilename[strlen( $destinationFilename ) - 1] == '/' )
 409                  $destinationFilename .= substr( $sourceFilename, $filePosition );
 410              else
 411                  $destinationFilename .= '/' . substr( $sourceFilename, $filePosition );
 412          }
 413  
 414          // If source and destination are the same files we just return true
 415          if ( $sourceFilename == $destinationFilename )
 416          {
 417              @fclose( $sourceFD );
 418              return true;
 419          }
 420  
 421          $destinationFD = fopen( $destinationFilename, 'wb' );
 422          if ( !$destinationFD )
 423          {
 424              @fclose( $sourceFD );
 425              eZDebug::writeError( "Unable to open destination file $destinationFilename in write mode",
 426                                   'eZFileHandler::copy' );
 427              return false;
 428          }
 429          $bytesCopied = 0;
 430          do
 431          {
 432              $data = fread( $sourceFD, 4096 );
 433              if ( strlen( $data ) == 0 )
 434                  break;
 435              fwrite( $destinationFD, $data );
 436              $bytesCopied += strlen( $data );
 437          } while( true );
 438  
 439          @fclose( $sourceFD );
 440          @fclose( $destinationFD );
 441          return true;
 442      }
 443  
 444      /*!
 445       \return \c true if the filename \a $filename exists.
 446       If \a $filename is not specified the filename is taken from the one used in open().
 447      */
 448      function exists( $filename = false )
 449      {
 450          if ( !$filename )
 451              $filename = $this->FileName;
 452          return $this->doExists( $filename );
 453      }
 454  
 455      /*!
 456       \return \c true if \a $filename is a directory.
 457      */
 458      function isDirectory( $filename = false )
 459      {
 460          if ( !$filename )
 461              $filename = $this->FileName;
 462          return $this->doIsDirectory( $filename );
 463      }
 464  
 465      /*!
 466       \return \c true if \a $filename is executable.
 467      */
 468      function isExecutable( $filename = false )
 469      {
 470          if ( !$filename )
 471              $filename = $this->FileName;
 472          return $this->doIsExecutable( $filename );
 473      }
 474  
 475      /*!
 476       \return \c true if \a $filename is a file.
 477      */
 478      function isFile( $filename = false )
 479      {
 480          if ( !$filename )
 481              $filename = $this->FileName;
 482          return $this->doIsFile( $filename );
 483      }
 484  
 485      /*!
 486       \return \c true if \a $filename is a link.
 487      */
 488      function isLink( $filename = false )
 489      {
 490          if ( !$filename )
 491              $filename = $this->FileName;
 492          return $this->doIsLink( $filename );
 493      }
 494  
 495      /*!
 496       \return \c true if \a $filename is readable.
 497      */
 498      function isReadable( $filename = false )
 499      {
 500          if ( !$filename )
 501              $filename = $this->FileName;
 502          return $this->doIsReadable( $filename );
 503      }
 504  
 505      /*!
 506       \return \c true if \a $filename is writeable.
 507      */
 508      function isWriteable( $filename = false )
 509      {
 510          if ( !$filename )
 511              $filename = $this->FileName;
 512          return $this->doIsWriteable( $filename );
 513      }
 514  
 515      /*!
 516       \return the statitistics for the file \a $filename.
 517      */
 518      function statistics( $filename = false )
 519      {
 520          if ( !$filename )
 521              $filename = $this->FileName;
 522          return $this->doStatistics( $filename );
 523      }
 524  
 525      /*!
 526       Tries to open the file \a $filename with mode \a $mode and returns
 527       the file resource if succesful.
 528       \return \c false if the file could not be opened.
 529       \param $mode If false the file will be opened in read mode using 'r'
 530       \param $binaryFile If true file will be opened in binary mode (default),
 531                          otherwise text mode is used.
 532       \note Parameter $binaryFile will only have effect on the Windows operating system.
 533      */
 534      function open( $filename, $mode, $binaryFile = true )
 535      {
 536          if ( $this->isOpen() )
 537          {
 538              eZDebug::writeError( "A file is already open (" . $this->FileName . "), close the file before opening a new one.",
 539                                   'eZFileHandler::open' );
 540              return false;
 541          }
 542          if ( !$filename and
 543               !$this->FileName )
 544          {
 545              eZDebug::writeError( "The supplied filename is empty and no filename set for object, cannot open any file",
 546                                   'eZFileHandler::open' );
 547              return false;
 548          }
 549          if ( !$filename )
 550              $filename = $this->FileName;
 551          if ( !$mode )
 552              $mode = 'r';
 553          if ( strpos( $mode, 'b' ) !== false )
 554              $binaryFile = true;
 555          $mode = str_replace( 'b', '', $mode );
 556          if ( $binaryFile )
 557              $mode .= 'b';
 558          $this->IsBinary = $binaryFile;
 559          $result = $this->doOpen( $filename, $mode );
 560          if ( $result )
 561          {
 562  //             eZDebugSetting::writeNotice( 'lib-ezfile-openclose',
 563  //                                          "Opened file $filename with mode '$mode'",
 564  //                                          'eZFileHandler::open' );
 565              $this->FileName = $filename;
 566              $this->Mode = $mode;
 567              $this->IsOpen = true;
 568          }
 569          else
 570              eZDebug::writeError( "Failed opening file $filename with mode $mode",
 571                                   'eZFileHandler::open' );
 572          return $result;
 573      }
 574  
 575      /*!
 576       Tries to close an open file and returns \c true if succesful, \c false otherwise.
 577      */
 578      function close()
 579      {
 580          if ( !$this->isOpen() )
 581          {
 582              eZDebug::writeError( "A file is not currently opened, cannot close.",
 583                                   'eZFileHandler::close' );
 584              return false;
 585          }
 586  //         eZDebugSetting::writeNotice( 'lib-ezfile-openclose',
 587  //                                      "Closing file " . $this->filename() . " with previously opened mode '" . $this->mode() . "'",
 588  //                                      'eZFileHandler::close' );
 589          $result = $this->doClose();
 590          if ( !$result )
 591              eZDebug::writeError( "Failed closing file " . $this->FileName . " opened with mode " . $this->Mode,
 592                                   'eZFileHandler::close' );
 593          else
 594              $this->IsOpen = false;
 595          return $result;
 596      }
 597  
 598      /*!
 599       Tries to unlink the file from the file system.
 600      */
 601      function unlink( $filename = false )
 602      {
 603          if ( !$filename )
 604          {
 605              if ( $this->isOpen() )
 606                  $this->close();
 607              $filename = $this->FileName;
 608          }
 609          $result = eZFileHandler::doUnlink( $filename );
 610          if ( !$result )
 611              eZDebug::writeError( "Failed unlinking file " . $filename,
 612                                   'eZFileHandler::unlink' );
 613          return $result;
 614      }
 615  
 616      /*!
 617       Renames the file \a $sourceFilename to \a $destinationFilename.
 618       If \a $sourceFilename is not supplied then filename() is used,
 619       it will also close the current file connection and reopen it again if
 620       was already open.
 621      */
 622      function rename( $destinationFilename, $sourceFilename = false )
 623      {
 624          if ( !$sourceFilename )
 625          {
 626              $wasOpen = $this->isOpen();
 627              if ( $wasOpen )
 628                  $this->close();
 629              $result = $this->doRename( $destinationFilename, $this->filename() );
 630              if ( $wasOpen and
 631                   $result )
 632                  $this->open( $destinationFilename, $this->mode() );
 633          }
 634          else
 635              $result = $this->doRename( $destinationFilename, $sourceFilename );
 636          return $result;
 637      }
 638  
 639      /*!
 640       Reads up to \a $length bytes from file. Reading stops when
 641       \a $length has been read or \c EOF is reached, whichever comes first.
 642       If the optional parameter \a $length is not specified it will
 643       read bytes until \c EOF is reached.
 644       \return a \c string or \c false if something fails.
 645      */
 646      function read( $length = false )
 647      {
 648          if ( !$this->isOpen() )
 649          {
 650              eZDebug::writeError( "A file is not currently opened, cannot read.",
 651                                   'eZFileHandler::read' );
 652              return false;
 653          }
 654          if ( $length < 0 )
 655          {
 656              eZDebug::writeError( "length cannot be negative ($length)",
 657                                   'eZFileHandler::read' );
 658              return false;
 659          }
 660          if ( $length )
 661          {
 662              return $this->doRead( $length );
 663          }
 664          else
 665          {
 666              $string = '';
 667              $data = false;
 668              do
 669              {
 670                  $data = $this->doRead( 1024 );
 671                  if ( $data )
 672                      $string .= $data;
 673              } while( $data );
 674              return $string;
 675          }
 676      }
 677  
 678      /*!
 679       Writes the content of the string \a $data to the file.
 680       If optional \c $length parameter is supplied writing will stop after
 681       length is reached or the end of the string is reached, whichever comes first.
 682       \return the number of bytes that was written.
 683      */
 684      function write( $data, $length = false )
 685      {
 686          if ( !$this->isOpen() )
 687          {
 688              eZDebug::writeError( "A file is not currently opened, cannot write.",
 689                                   'eZFileHandler::write' );
 690              return false;
 691          }
 692          if ( $length < 0 )
 693          {
 694              eZDebug::writeError( "length cannot be negative ($length)",
 695                                   'eZFileHandler::write' );
 696              return false;
 697          }
 698          return $this->doWrite( $data, $length );
 699      }
 700  
 701      /*!
 702       Force a write of all buffered data.
 703       \return \c true if succesful or \c false if something failed.
 704      */
 705      function flush()
 706      {
 707          if ( !$this->isOpen() )
 708          {
 709              eZDebug::writeError( "A file is not currently opened, cannot flush.",
 710                                   'eZFileHandler::flush' );
 711              return false;
 712          }
 713          return $this->doFlush();
 714      }
 715  
 716      /*!
 717       Seeks to position in file determined by \a $offset and \a $whence.
 718       - SEEK_SET - Set position equal to offset bytes.
 719       - SEEK_CUR - Set position to current location plus offset.
 720       - SEEK_END - Set position to end-of-file plus offset. (To move to a position before the end-of-file, you need to pass a negative value in offset.)
 721  
 722       \note Not all handlers supports all types for \a $whence
 723       \return \c 0 if succesful or \c -1 if something failed.
 724      */
 725      function seek( $offset, $whence = SEEK_SET )
 726      {
 727          if ( !$this->isOpen() )
 728          {
 729              eZDebug::writeError( "A file is not currently opened, cannot seek.",
 730                                   'eZFileHandler::seek' );
 731              return false;
 732          }
 733          return $this->doSeek( $offset, $whence );
 734      }
 735  
 736      /*!
 737       Rewinds the file position to the beginning of the file.
 738       \return \c 0 if something went wrong.
 739      */
 740      function rewind()
 741      {
 742          if ( !$this->isOpen() )
 743          {
 744              eZDebug::writeError( "A file is not currently opened, cannot rewind.",
 745                                   'eZFileHandler::rewind' );
 746              return false;
 747          }
 748          return $this->doRewind();
 749      }
 750  
 751      /*!
 752       Tells the current file position.
 753       \return \c false if something failed.
 754      */
 755      function tell()
 756      {
 757          if ( !$this->isOpen() )
 758          {
 759              eZDebug::writeError( "A file is not currently opened, cannot tell position.",
 760                                   'eZFileHandler::tell' );
 761              return false;
 762          }
 763          return $this->doTell();
 764      }
 765  
 766      /*!
 767       \return \c true if the file pointer is at the end of the file or an error occured, otherwise \c false.
 768      */
 769      function eof()
 770      {
 771          if ( !$this->isOpen() )
 772          {
 773              eZDebug::writeError( "A file is not currently opened, cannot report EOF status.",
 774                                   'eZFileHandler::eof' );
 775              return false;
 776          }
 777          return $this->doEOF();
 778      }
 779  
 780      /*!
 781       Passes the data from the file to the standard output.
 782       \param $closeFile If \c true the file will be closed after output is done.
 783       \return \c false if something failed.
 784      */
 785      function passtrough( $closeFile = true )
 786      {
 787          if ( !$this->isOpen() )
 788          {
 789              eZDebug::writeError( "A file is not currently opened, cannot do a data passtrough.",
 790                                   'eZFileHandler::passtrough' );
 791              return false;
 792          }
 793          return $this->doPasstrough( $closeFile );
 794      }
 795  
 796      /*!
 797       \pure
 798       Does the actual file opening.
 799       \sa open
 800      */
 801      function doOpen( $filename, $mode )
 802      {
 803          $this->FileHandler = @fopen( $filename, $mode );
 804          return $this->FileHandler;
 805      }
 806  
 807      /*!
 808       \pure
 809       Does the actual file closing.
 810       \sa close
 811      */
 812      function doClose()
 813      {
 814          $result = @fclose( $this->FileHandler );
 815          $this->FileHandler = false;
 816          return $result;
 817      }
 818  
 819      /*!
 820       \pure
 821       Does the actual file unlinking.
 822       \sa unlink
 823      */
 824      function doUnlink( $filename )
 825      {
 826          return @unlink( $filename );
 827      }
 828  
 829      /*!
 830       \pure
 831       Does the actual file exists checking.
 832       \sa exists
 833      */
 834      function doExists( $filename )
 835      {
 836          return file_exists( $filename );
 837      }
 838  
 839      /*!
 840       \pure
 841       Does the actual directory checking.
 842       \sa isDirectory
 843      */
 844      function doIsDirectory( $filename )
 845      {
 846          return @is_dir( $filename );
 847      }
 848  
 849      /*!
 850       \pure
 851       Does the actual executable checking.
 852       \sa isExecutable
 853      */
 854      function doIsExecutable( $filename )
 855      {
 856          return @is_executable( $filename );
 857      }
 858  
 859      /*!
 860       \pure
 861       Does the actual file checking.
 862       \sa isFile
 863      */
 864      function doIsFile( $filename )
 865      {
 866          return @is_file( $filename );
 867      }
 868  
 869      /*!
 870       \pure
 871       Does the actual link checking.
 872       \sa isLink
 873      */
 874      function doIsLink( $filename )
 875      {
 876          return @is_link( $filename );
 877      }
 878  
 879      /*!
 880       \pure
 881       Does the actual readable checking.
 882       \sa isReadable
 883      */
 884      function doIsReadable( $filename )
 885      {
 886          return @is_readable( $filename );
 887      }
 888  
 889      /*!
 890       \pure
 891       Does the actual writeable checking.
 892       \sa isWriteable
 893      */
 894      function doIsWriteable( $filename )
 895      {
 896          return @is_writable( $filename );
 897      }
 898  
 899      /*!
 900       \pure
 901       Does the actual writeable checking.
 902       \sa isWriteable
 903      */
 904      function doStatistics( $filename )
 905      {
 906          return @stat( $filename );
 907      }
 908  
 909      /*!
 910       \pure
 911       Does the actual file seek.
 912       \sa seek
 913      */
 914      function doSeek( $offset, $whence )
 915      {
 916          return @fseek( $this->FileHandler, $offset, $whence );
 917      }
 918  
 919      /*!
 920       \virtual
 921       Does the actual file rewind.
 922       \sa rewind
 923       \note Default implementation calls seek with offset set to 0 from the file start.
 924      */
 925      function doRewind()
 926      {
 927          $this->doSeek( $offset, SEEK_SET );
 928      }
 929  
 930      /*!
 931       \pure
 932       Does the actual file telling.
 933       \sa tell
 934      */
 935      function doTell()
 936      {
 937          return @ftell( $this->FileHandler );
 938      }
 939  
 940      /*!
 941       \pure
 942       Does the actual file eof detection.
 943       \sa eof
 944      */
 945      function doEOF()
 946      {
 947          return @feof( $this->FileHandler );
 948      }
 949  
 950      /*!
 951       \pure
 952       Does the actual file passtrough.
 953       \sa eof
 954      */
 955      function doPasstrough( $closeFile = true )
 956      {
 957          $result = @fpasstru( $this->FileHandler );
 958          if ( $closeFile )
 959          {
 960              @fclose( $this->FileHandler );
 961              $this->FileHandler = false;
 962          }
 963      }
 964  
 965      /*!
 966       \pure
 967       Does the actual file reading.
 968       \sa read
 969      */
 970      function doRead( $length = false )
 971      {
 972          return @fread( $this->FileHandler, $length );
 973      }
 974  
 975      /*!
 976       \pure
 977       Does the actual file writing.
 978       \sa write
 979      */
 980      function doWrite( $data, $length = false )
 981      {
 982          if ( $length === false )
 983              return @fwrite( $this->FileHandler, $data );
 984          else
 985              return @fwrite( $this->FileHandler, $data, $length );
 986      }
 987  
 988      /*!
 989       \pure
 990       Does the actual file flushing.
 991       \sa flush
 992      */
 993      function doFlush()
 994      {
 995          return @fflush( $this->FileHandler );
 996      }
 997  
 998      /*!
 999       \pure
1000       Does the actual file renaming.
1001       \sa rename
1002      */
1003      function doRename( $destinationFilename, $sourceFilename )
1004      {
1005          return @rename( $sourceFilename, $destinationFilename );
1006      }
1007  
1008      /*!
1009       \virtual
1010       Returns error data as an associative array, the array contains:
1011       - string - The error string
1012       - number - The error number
1013       \note The default implementation calls errorString() and errorNumber().
1014      */
1015      function error()
1016      {
1017          return array( 'string' => $this->errorString(),
1018                        'number' => $this->errorNumber() );
1019      }
1020  
1021      /*!
1022       \pure
1023       \return the error string from the last error that occured.
1024      */
1025      function errorString()
1026      {
1027          return false;
1028      }
1029  
1030      /*!
1031       \pure
1032       \return the error number from the last error that occured.
1033      */
1034      function errorNumber()
1035      {
1036          return false;
1037      }
1038  
1039      /*!
1040       \virtual
1041       Creates a copy of the current handler and returns a reference to the copy.
1042       \note The default does a simple copy of \c $this, this method must be reimplemented for specific handlers.
1043      */
1044      function &duplicate()
1045      {
1046          $copy = $this;
1047          return $copy;
1048      }
1049  
1050      /*!
1051       Returns the handler for the identifier \a $identifier.
1052               The parameters \a $filename, \a $mode and \a $binaryFile is passed to the handler.
1053       \return \c false if the handler could not be created.
1054      */
1055      function &instance( $identifier, $filename = false, $mode = false, $binaryFile = true )
1056      {
1057          include_once ( 'lib/ezutils/classes/ezini.php' );
1058          $ini =& eZINI::instance( 'file.ini' );
1059          $handlers = $ini->variable( 'FileSettings', 'Handlers' );
1060          $instance = false;
1061          if ( !$identifier )
1062          {
1063              $instance = new eZFileHandler();
1064          }
1065          else if ( isset( $handlers[$identifier] ) )
1066          {
1067              $className = $handlers[$identifier];
1068              $includeFile = 'lib/ezfile/classes/' . $className . '.php';
1069              include_once( $includeFile );
1070              $instance = new $className();
1071              if ( $instance->isAvailable() )
1072              {
1073                  if ( $filename )
1074                      $instance->open( $filename, $mode, $binaryFile );
1075              }
1076              else
1077              {
1078                  unset( $instance );
1079                  $instance = false;
1080              }
1081          }
1082          return $instance;
1083      }
1084  
1085      /// \privatesection
1086      var $Name;
1087      var $FileName;
1088      var $Mode;
1089      var $IsBinary;
1090      var $IsOpen;
1091  }
1092  
1093  ?>