<?php
/* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */
/**
* Abstract base class for all the readers
*
* A reader is a compilation of serveral files that can be read
*
* PHP versions 4 and 5
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330,Boston,MA 02111-1307 USA
*
* @category File Formats
* @package File_Archive
* @author Vincent Lascaux <vincentlascaux@php.net>
* @copyright 1997-2005 The PHP Group
* @license http://www.gnu.org/copyleft/lesser.html LGPL
* @version CVS: $Id: Reader.php,v 1.33 2005/07/07 12:24:57 vincentlascaux Exp $
* @link http://pear.php.net/package/File_Archive
*/
require_once "PEAR.php";
/**
* Abstract base class for all the readers
*
* A reader is a compilation of serveral files that can be read
*/
class File_Archive_Reader
{
/**
* Move to the next file in the reader
*
* @return bool false iif no more files are available
*/
function next()
{
return false;
}
/**
* Move to the next file whose name is in directory $filename
* or is exactly $filename
*
* @param string $filename Name of the file to find in the archive
* @param bool $close If true, close the reader and search from the first file
* @return bool whether the file was found in the archive or not
*/
function select($filename, $close = true)
{
$std = $this->getStandardURL($filename);
if ($close) {
$error = $this->close();
if (PEAR::isError($error)) {
return $error;
}
}
while (($error = $this->next()) === true) {
$sourceName = $this->getFilename();
if (
empty($std) ||
//$std is a file
$std == $sourceName ||
//$std is a directory
strncmp($std.'/', $sourceName, strlen($std)+1) == 0
) {
return true;
}
}
return $error;
}
/**
* Returns the standard path
* Changes \ to /
* Removes the .. and . from the URL
* @param string $path a valid URL that may contain . or .. and \
* @static
*/
function getStandardURL($path)
{
if ($path == '.') {
return '';
}
$std = str_replace("\\", "/", $path);
while ($std != ($std = preg_replace("/[^\/:?]+\/\.\.\//", "", $std))) ;
$std = str_replace("/./", "", $std);
if (strncmp($std, "./", 2) == 0) {
return substr($std, 2);
} else {
return $std;
}
}
/**
* Returns the name of the file currently read by the reader
*
* Warning: undefined behaviour if no call to next have been
* done or if last call to next has returned false
*
* @return string Name of the current file
*/
function getFilename()
{
return PEAR::raiseError("Reader abstract function call (getFilename)");
}
/**
* Returns the list of filenames from the current pos to the end of the source
* The source will be closed after having called this function
* This function goes through the whole archive (which may be slow).
* If you intend to work on the reader, doing it in one pass would be faster
*
* @return array filenames from the current pos to the end of the source
*/
function getFileList()
{
$result = array();
while ( ($error = $this->next()) === true) {
$result[] = $this->getFilename();
}
$this->close();
if (PEAR::isError($error)) {
return $error;
} else {
return $result;
}
}
/**
* Returns an array of statistics about the file
* (see the PHP stat function for more information)
*
* The returned array may be empty, even if readers should try
* their best to return as many data as possible
*/
function getStat() { return array(); }
/**
* Returns the MIME associated with the current file
* The default function does that by looking at the extension of the file
*/
function getMime()
{
require_once "File/Archive/Reader/MimeList.php";
return File_Archive_Reader_GetMime($this->getFilename());
}
/**
* If the current file of the archive is a physical file,
*
* @return the name of the physical file containing the data
* or null if no such file exists
*
* The data filename may not be the same as the filename.
*/
function getDataFilename() { return null; }
/**
* Reads some data from the current file
* If the end of the file is reached, returns null
* If $length is not specified, reads up to the end of the file
* If $length is specified reads up to $length
*/
function getData($length = -1)
{
return PEAR::raiseError("Reader abstract function call (getData)");
}
/**
* Skip some data and returns how many bytes have been skipped
* This is strictly equivalent to
* return strlen(getData($length))
* But could be far more efficient
*/
function skip($length = -1)
{
$data = $this->getData($length);
if (PEAR::isError($data)) {
return $data;
} else {
return strlen($data);
}
}
/**
* Move the current position back of a given amount of bytes.
* Not all readers may implement this function (a PEAR error will
* be returned if the reader can't rewind)
*
* @param int $length number of bytes to seek before the current pos
* or -1 to move back to the begining of the current file
* @return the number of bytes really rewinded (which may be less than
* $length if the current pos is less than $length
*/
function rewind($length = -1)
{
return PEAR::raiseError('Rewind function is not implemented on this reader');
}
/**
* Returns the current offset in the current file
*/
function tell()
{
$offset = $this->rewind();
$this->skip($offset);
return $offset;
}
/**
* Put back the reader in the state it was before the first call
* to next()
*/
function close()
{
}
/**
* Sends the current file to the Writer $writer
* The data will be sent by chunks of at most $bufferSize bytes
* If $bufferSize <= 0 (default), the blockSize option is used
*/
function sendData(&$writer, $bufferSize = 0)
{
if (PEAR::isError($writer)) {
return $writer;
}
if ($bufferSize <= 0) {
$bufferSize = File_Archive::getOption('blockSize');
}
$filename = $this->getDataFilename();
if ($filename !== null) {
$error = $writer->writeFile($filename);
if (PEAR::isError($error)) {
return $error;
}
} else {
while (($data = $this->getData($bufferSize)) !== null) {
if (PEAR::isError($data)) {
return $data;
}
$error = $writer->writeData($data);
if (PEAR::isError($error)) {
return $error;
}
}
}
}
/**
* Sends the whole reader to $writer and close the reader
*
* @param File_Archive_Writer $writer Where to write the files of the reader
* @param bool $autoClose If true, close $writer at the end of the function.
* Default value is true
* @param int $bufferSize Size of the chunks that will be sent to the writer
* If $bufferSize <= 0 (default value), the blockSize option is used
*/
function extract(&$writer, $autoClose = true, $bufferSize = 0)
{
if (PEAR::isError($writer)) {
$this->close();
return $writer;
}
while (($error = $this->next()) === true) {
if ($writer->newFileNeedsMIME()) {
$mime = $this->getMime();
} else {
$mime = null;
}
$error = $writer->newFile(
$this->getFilename(),
$this->getStat(),
$mime
);
if (PEAR::isError($error)) {
break;
}
$error = $this->sendData($writer, $bufferSize);
if (PEAR::isError($error)) {
break;
}
}
$this->close();
if ($autoClose) {
$writer->close();
}
if (PEAR::isError($error)) {
return $error;
}
}
/**
* Extract only one file (given by the URL)
*
* @param string $filename URL of the file to extract from this
* @param File_Archive_Writer $writer Where to write the file
* @param bool $autoClose If true, close $writer at the end of the function
* Default value is true
* @param int $bufferSize Size of the chunks that will be sent to the writer
* If $bufferSize <= 0 (default value), the blockSize option is used
*/
function extractFile($filename, &$writer,
$autoClose = true, $bufferSize = 0)
{
if (PEAR::isError($writer)) {
return $writer;
}
if (($error = $this->select($filename)) === true) {
$result = $this->sendData($writer, $bufferSize);
if (!PEAR::isError($result)) {
$result = true;
}
} else if ($error === false) {
$result = PEAR::raiseError("File $filename not found");
} else {
$result = $error;
}
if ($autoClose) {
$error = $writer->close();
if (PEAR::isError($error)) {
return $error;
}
}
return $result;
}
/**
* Return a writer that allows appending files to the archive
* After having called makeAppendWriter, $this is closed and should not be
* used until the returned writer is closed.
*
* @return a writer that will allow to append files to an existing archive
* @see makeWriter
*/
function makeAppendWriter()
{
require_once "File/Archive/Predicate/False.php";
return $this->makeWriterRemoveFiles(new File_Archive_Predicate_False());
}
/**
* Return a writer that has the same properties as the one returned by
* makeAppendWriter, but after having removed all the files that follow a
* given predicate.
* After a call to makeWriterRemoveFiles, $this is closed and should not
* be used until the returned writer is closed
*
* @param File_Archive_Predicate $pred the predicate verified by removed files
* @return File_Archive_Writer that allows to append files to the archive
*/
function makeWriterRemoveFiles($pred)
{
return PEAR::raiseError("Reader abstract function call (makeWriterRemoveFiles)");
}
/**
* Returns a writer that removes the current file
* This is a syntaxic sugar for makeWriterRemoveFiles(new File_Archive_Predicate_Current());
*/
function makeWriterRemove()
{
require_once "File/Archive/Predicate/Current.php";
return $this->makeWriterRemoveFiles(new File_Archive_Predicate_Current());
}
/**
* Removes the current file from the reader
*/
function remove()
{
$writer = $this->makeWriterRemove();
if (PEAR::isError($writer)) {
return $writer;
}
$writer->close();
}
/**
* Return a writer that has the same properties as the one returned by makeWriter, but after
* having removed a block of data from the current file. The writer will append data to the current file
* no data (other than the block) will be removed
*
* @param array Lengths of the blocks. The first one will be discarded, the second one kept, the third
* one discarded... If the sum of the blocks is less than the size of the file, the comportment is the
* same as if a last block was set in the array to reach the size of the file
* if $length is -1, the file is truncated from the specified pos
* It is possible to specify blocks of size 0
* @param int $seek relative pos of the block
*/
function makeWriterRemoveBlocks($blocks, $seek = 0)
{
return PEAR::raiseError("Reader abstract function call (makeWriterRemoveBlocks)");
}
}
?>