Book/rar-Phpdoc专题

Rar Archiving

简介
安装／配置
预定义常量
范例
Rar 函数
- rar_wrapper_cache_stats — Cache hits and misses for the URL wrapper
RarArchive — The RarArchive class
- RarArchive::close — Close RAR archive and free all resources
- RarArchive::getComment — Get comment text from the RAR archive
- RarArchive::getEntries — Get full list of entries from the RAR archive
- RarArchive::getEntry — Get entry object from the RAR archive
- RarArchive::isBroken — Test whether an archive is broken (incomplete)
- RarArchive::isSolid — Check whether the RAR archive is solid
- RarArchive::open — Open RAR archive
- RarArchive::setAllowBroken — Whether opening broken archives is allowed
- RarArchive::__toString — Get text representation
RarEntry — The RarEntry class
- RarEntry::extract — Extract entry from the archive
- RarEntry::getAttr — Get attributes of the entry
- RarEntry::getCrc — Get CRC of the entry
- RarEntry::getFileTime — Get entry last modification time
- RarEntry::getHostOs — Get entry host OS
- RarEntry::getMethod — Get pack method of the entry
- RarEntry::getName — Get name of the entry
- RarEntry::getPackedSize — Get packed size of the entry
- RarEntry::getStream — Get file handler for entry
- RarEntry::getUnpackedSize — Get unpacked size of the entry
- RarEntry::getVersion — Get minimum version of RAR program required to unpack the entry
- RarEntry::isDirectory — Test whether an entry represents a directory
- RarEntry::isEncrypted — Test whether an entry is encrypted
- RarEntry::__toString — Get text representation of entry
RarException — The RarException class
- RarException::isUsingExceptions — Check whether error handling with exceptions is in use
- RarException::setUsingExceptions — Activate and deactivate error handling with exceptions

简介

This class represents a RAR archive, which may be formed by several volumes (parts) and which contains a number of RAR entries (i.e., files, directories and other special objects such as symbolic links).

Objects of this class can be traversed, yielding the entries stored in the respective RAR archive. Those entries can also be obtained through RarArchive::getEntry and RarArchive::getEntries.

类摘要

RarArchive

final class RarArchive implements Traversable {

/* 方法 */

public bool close ( void )

public string getComment ( void )

public arrayfalse getEntries ( void )

public RarEntryfalse getEntry ( string $entryname )

public bool isBroken ( void )

public bool isSolid ( void )

public static RarArchivefalse open ( string $filename [, string $password = NULL [, callable $volume_callback = NULL ]] )

public bool setAllowBroken ( bool $allow_broken )

public string __toString ( void )

}

RarArchive::close

rar_close

Close RAR archive and free all resources

说明

面向对象风格 (method):

public bool RarArchive::close ( void )

过程化风格:

bool rar_close ( RarArchive $rarfile )

Close RAR archive and free all allocated resources.

参数

rarfile
A RarArchive object, opened with rar_open.

返回值

成功时返回 true，或者在失败时返回 false。

更新日志

版本	说明
PECL rar 2.0.0	The RAR entries returned by RarArchive::getEntry and RarArchive::getEntries are now invalidated when calling this method. This means that all instance methods called for such entries and not guaranteed to succeed.

范例

示例 #1 面向对象风格

<?php
$rar_arch = RarArchive::open('latest_winrar.rar');
echo $rar_arch."\n";
$rar_arch->close();
echo $rar_arch."\n";
?>

以上例程的输出类似于：

RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar"
RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar" (closed)

示例 #2 过程化风格

<?php
$rar_arch = rar_open('latest_winrar.rar');
echo $rar_arch."\n";
rar_close($rar_arch);
echo $rar_arch."\n";
?>

RarArchive::getComment

rar_comment_get

Get comment text from the RAR archive

说明

面向对象风格 (method):

public string RarArchive::getComment ( void )

过程化风格:

string rar_comment_get ( RarArchive $rarfile )

Get the (global) comment stored in the RAR archive. It may be up to 64 KiB long.

Note:

This extension does not support comments at the entry level.

参数

rarfile
A RarArchive object, opened with rar_open.

返回值

Returns the comment or null if there is none.

Note:

RAR has currently no support for unicode comments. The encoding of the result of this function is not specified, but it will probably be Windows-1252.

范例

示例 #1 面向对象风格

<?php
$rar_arch = RarArchive::open('commented.rar'); 
echo $rar_arch->getComment();
?>

以上例程的输出类似于：

This is the comment of the file commented.rar.

示例 #2 过程化风格

<?php
$rar_arch = rar_open('commented.rar'); 
echo rar_comment_get($rar_arch);
?>

RarArchive::getEntries

rar_list

Get full list of entries from the RAR archive

说明

面向对象风格 (method):

public arrayfalse RarArchive::getEntries ( void )

过程化风格:

arrayfalse rar_list ( RarArchive $rarfile )

Get entries list (files and directories) from the RAR archive.

Note:

If the archive has entries with the same name, this method, together with RarArchive foreach iteration and array-like access with numeric indexes, are the only ones to access all the entries (i.e., RarArchive::getEntry and the rar:// wrapper are insufficient).

参数

rarfile
A RarArchive object, opened with rar_open.

返回值

rar_list returns array of RarEntry objects 或者在失败时返回 false.

更新日志

版本	说明
PECL rar 3.0.0	Support for RAR archives with repeated entry names is no longer defective.

范例

示例 #1 面向对象风格

<?php
$rar_arch = RarArchive::open('solid.rar');
if ($rar_arch === FALSE)
    die("Could not open RAR archive.");

$rar_entries = $rar_arch->getEntries();
if ($rar_entries === FALSE)
    die("Could not retrieve entries.");

echo "Found " . count($rar_entries) . " entries.\n";

foreach ($rar_entries as $e) {
    echo $e;
    echo "\n";
}
$rar_arch->close();
?>

以上例程的输出类似于：

Found 2 entries.
RarEntry for file "tese.txt" (23b93a7a)
RarEntry for file "unrardll.txt" (2ed64b6e)

示例 #2 过程化风格

<?php
$rar_arch = rar_open('solid.rar');
if ($rar_arch === FALSE)
    die("Could not open RAR archive.");

$rar_entries = rar_list($rar_arch);
if ($rar_entries === FALSE)
    die("Could retrieve entries.");

echo "Found " . count($rar_entries) . " entries.\n";

foreach ($rar_entries as $e) {
    echo $e;
    echo "\n";
}
rar_close($rar_arch);
?>

参见

RarArchive::getEntry
rar:// wrapper

RarArchive::getEntry

rar_entry_get

Get entry object from the RAR archive

说明

面向对象风格 (method):

public RarEntryfalse RarArchive::getEntry ( string $entryname )

过程化风格:

RarEntryfalse rar_entry_get ( RarArchive $rarfile , string $entryname )

Get entry object (file or directory) from the RAR archive.

Note:

You can also get entry objects using RarArchive::getEntries.

Note that a RAR archive can have multiple entries with the same name; this method will retrieve only the first.

参数

rarfile
A RarArchive object, opened with rar_open.

entryname
Path to the entry within the RAR archive.

Note:

The path must be the same returned by RarEntry::getName.

返回值

Returns the matching RarEntry object 或者在失败时返回 false.

范例

示例 #1 面向对象风格

<?php
$rar_arch = RarArchive::open('solid.rar');
if ($rar_arch === FALSE)
    die("Could not open RAR archive.");
$rar_entry = $rar_arch->getEntry('tese.txt');
if ($rar_entry === FALSE)
    die("Could not get such entry");
echo get_class($rar_entry)."\n";
echo $rar_entry;
$rar_arch->close();
?>

以上例程的输出类似于：

RarEntry
RarEntry for file "tese.txt" (23b93a7a)

示例 #2 过程化风格

<?php
$rar_arch = rar_open('solid.rar');
if ($rar_arch === FALSE)
    die("Could not open RAR archive.");
$rar_entry = rar_entry_get($rar_arch, 'tese.txt');
if ($rar_entry === FALSE)
    die("Could not get such entry");
echo get_class($rar_entry)."\n";
echo $rar_entry;
rar_close($rar_arch);
?>

参见

RarArchive::getEntries
rar:// wrapper

RarArchive::isBroken

rar_broken_is

Test whether an archive is broken (incomplete)

说明

面向对象风格 (method):

public bool RarArchive::isBroken ( void )

过程化风格:

bool rar_broken_is ( RarArchive $rarfile )

This function determines whether an archive is incomplete, i.e., if a volume is missing or a volume is truncated.

参数

rarfile
A RarArchive object, opened with rar_open.

返回值

Returns true if the archive is broken, false otherwise. This function may also return false if the passed file has already been closed. The only way to tell the two cases apart is to enable exceptions with RarException::setUsingExceptions; however, this should be unnecessary as a program should not operate on closed files.

范例

示例 #1 面向对象风格

<?php
function retnull() { return null; }
$file = dirname(__FILE__) . "/multi_broken.part1.rar";
/* Third argument is used to omit notice */
$arch = RarArchive::open($file, null, 'retnull');
var_dump($arch->isBroken());
?>

以上例程的输出类似于：

bool(true)

示例 #2 过程化风格

<?php
function retnull() { return null; }
$file = dirname(__FILE__) . "/multi_broken.part1.rar";
/* Third argument is used to omit notice */
$arch = rar_open($file, null, 'retnull');
var_dump(rar_broken_is($arch));
?>

参见

RarArchive::setAllowBroken

RarArchive::isSolid

rar_solid_is

Check whether the RAR archive is solid

说明

面向对象风格 (method):

public bool RarArchive::isSolid ( void )

过程化风格:

bool rar_solid_is ( RarArchive $rarfile )

Check whether the RAR archive is solid. Individual file extraction is slower on solid archives.

参数

rarfile
A RarArchive object, opened with rar_open.

返回值

Returns true if the archive is solid, false otherwise.

范例

示例 #1 面向对象风格

<?php
$arch1 = RarArchive::open("store_method.rar");
$arch2 = RarArchive::open("solid.rar");
echo "$arch1: " . ($arch1->isSolid()?'yes':'no') ."\n";
echo "$arch2: " . ($arch2->isSolid()?'yes':'no') . "\n";
?>

以上例程的输出类似于：

RAR Archive "C:\php_rar\trunk\tests\store_method.rar": no
RAR Archive "C:\php_rar\trunk\tests\solid.rar": yes

示例 #2 过程化风格

<?php
$arch1 = rar_open("store_method.rar");
$arch2 = rar_open("solid.rar");
echo "$arch1: " . (rar_solid_is($arch1)?'yes':'no') ."\n";
echo "$arch2: " . (rar_solid_is($arch2)?'yes':'no') . "\n";
?>

RarArchive::open

rar_open

Open RAR archive

说明

面向对象风格 (method):

public static RarArchivefalse RarArchive::open ( string $filename [, string $password = NULL [, callable $volume_callback = NULL ]] )

过程化风格:

RarArchivefalse rar_open ( string $filename [, string $password = NULL [, callable $volume_callback = NULL ]] )

Open specified RAR archive and return RarArchive instance representing it.

Note:

If opening a multi-volume archive, the path of the first volume should be passed as the first parameter. Otherwise, not all files will be shown. This is by design.

参数

filename
Path to the Rar archive.

password
A plain password, if needed to decrypt the headers. It will also be used by default if encrypted files are found. Note that the files may have different passwords in respect to the headers and among them.

volume_callback
A function that receives one parameter – the path of the volume that was not found – and returns a string with the correct path for such volume or null if such volume does not exist or is not known. The programmer should ensure the passed function doesn't cause loops as this function is called repeatedly if the path returned in a previous call did not correspond to the needed volume. Specifying this parameter omits the notice that would otherwise be emitted whenever a volume is not found; an implementation that only returns null can therefore be used to merely omit such notices.

Warning

Prior to version 2.0.0, this function would not handle relative paths correctly. Use realpath as a workaround.

返回值

Returns the requested RarArchive instance 或者在失败时返回 false.

更新日志

版本	说明
PECL rar 3.0.0	`volume_callback` was added.

范例

示例 #1 面向对象风格

<?php
$rar_arch = RarArchive::open('encrypted_headers.rar', 'samplepassword');
if ($rar_arch === FALSE)
    die("Failed opening file");

$entries = $rar_arch->getEntries();
if ($entries === FALSE)
    die("Failed fetching entries");

echo "Found " . count($entries) . " files.\n";

if (empty($entries))
    die("No valid entries found.");

$stream = reset($entries)->getStream();
if ($stream === FALSE)
    die("Failed opening first file");

$rar_arch->close();

echo "Content of first one follows:\n";
echo stream_get_contents($stream);

fclose($stream);
?>

以上例程的输出类似于：

Found 2 files.
Content of first one follows:
Encrypted file 1 contents.

示例 #2 过程化风格

<?php
$rar_arch = rar_open('encrypted_headers.rar', 'samplepassword');
if ($rar_arch === FALSE)
    die("Failed opening file");

$entries = rar_list($rar_arch);
if ($entries === FALSE)
    die("Failed fetching entries");

echo "Found " . count($entries) . " files.\n";

if (empty($entries))
    die("No valid entries found.");

$stream = reset($entries)->getStream();
if ($stream === FALSE)
    die("Failed opening first file");

rar_close($rar_arch);

echo "Content of first one follows:\n";
echo stream_get_contents($stream);

fclose($stream);
?>

示例 #3 Volume Callback

<?php
/* In this example, there's a volume named multi_broken.part1.rar
 * whose next volume is named multi.part2.rar */
function resolve($vol) {
    if (preg_match('/_broken/', $vol))
        return str_replace('_broken', '', $vol);
    else
        return null;
}
$rar_file1 = rar_open(dirname(__FILE__).'/multi_broken.part1.rar', null, 'resolve');
$entry = $rar_file1->getEntry('file2.txt');
$entry->extract(null, dirname(__FILE__) . "/temp_file2.txt");
?>

参见

rar:// wrapper

RarArchive::setAllowBroken

Whether opening broken archives is allowed

说明

面向对象风格 (method):

public bool RarArchive::setAllowBroken ( bool $allow_broken )

过程化风格:

bool rar_allow_broken_set ( RarArchive $rarfile , bool $allow_broken )

This method defines whether broken archives can be read or all the operations that attempt to extract the archive entries will fail. Broken archives are archives for which no error is detected when the file is opened but an error occurs when reading the entries.

参数

rarfile
A RarArchive object, opened with rar_open.

allow_broken
Whether to allow reading broken files (true) or not (false).

返回值

Returns true 或者在失败时返回 false. It will only fail if the file has already been closed.

范例

示例 #1 面向对象风格

<?php
function retnull() { return null; }
$file = dirname(__FILE__) . "/multi_broken.part1.rar";
/* Third argument omits "volume not found" message */
$a = RarArchive::open($file, null, 'retnull');
$a->setAllowBroken(true);
foreach ($a->getEntries() as $e) {
    echo "$e\n";
}
var_dump(count($a));
?>

以上例程的输出类似于：

RarEntry for file "file1.txt" (52b28202)
int(1)

示例 #2 过程化风格

<?php
function retnull() { return null; }
$file = dirname(__FILE__) . "/multi_broken.part1.rar";
/* Third argument omits "volume not found" message */
$a = rar_open($file, null, 'retnull');
rar_allow_broken_set($a, true);
foreach (rar_list($a) as $e) {
    echo "$e\n";
}
var_dump(count($a));
?>

参见

RarArchive::isBroken

RarArchive::__toString

Get text representation

说明

public string RarArchive::__toString ( void )

Provides a string representation for this RarArchive object. It currently shows the full path name of the archive volume that was opened and whether the resource is valid or was already closed through a call to RarArchive::close.

This method may be used only for debugging purposes, as there are no guarantees as to which information the result contains or how it is formatted.

参数

此函数没有参数。

返回值

A textual representation of this RarArchive object. The content of this representation is unspecified.

范例

示例 #1 RarArchive::__toString example

<?php
$rar_arch = RarArchive::open('latest_winrar.rar');
echo $rar_arch."\n";
$rar_arch->close();
echo $rar_arch."\n";
?>

以上例程的输出类似于：

RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar"
RAR Archive "D:\php_rar\trunk\tests\latest_winrar.rar" (closed)

简介

A RAR entry, representing a directory or a compressed file inside a RAR archive.

类摘要

RarEntry

final class RarEntry {

/* 常量 */

const int RarEntry::HOST_MSDOS = 0 ;

const int RarEntry::HOST_OS2 = 1 ;

const int RarEntry::HOST_WIN32 = 2 ;

const int RarEntry::HOST_UNIX = 3 ;

const int RarEntry::HOST_MACOS = 4 ;

const int RarEntry::HOST_BEOS = 5 ;

const int RarEntry::ATTRIBUTE_WIN_READONLY = 1 ;

const int RarEntry::ATTRIBUTE_WIN_HIDDEN = 2 ;

const int RarEntry::ATTRIBUTE_WIN_SYSTEM = 4 ;

const int RarEntry::ATTRIBUTE_WIN_DIRECTORY = 16 ;

const int RarEntry::ATTRIBUTE_WIN_ARCHIVE = 32 ;

const int RarEntry::ATTRIBUTE_WIN_DEVICE = 64 ;

const int RarEntry::ATTRIBUTE_WIN_NORMAL = 128 ;

const int RarEntry::ATTRIBUTE_WIN_TEMPORARY = 256 ;

const int RarEntry::ATTRIBUTE_WIN_SPARSE_FILE = 512 ;

const int RarEntry::ATTRIBUTE_WIN_REPARSE_POINT = 1024 ;

const int RarEntry::ATTRIBUTE_WIN_COMPRESSED = 2048 ;

const int RarEntry::ATTRIBUTE_WIN_OFFLINE = 4096 ;

const int RarEntry::ATTRIBUTE_WIN_NOT_CONTENT_INDEXED = 8192 ;

const int RarEntry::ATTRIBUTE_WIN_ENCRYPTED = 16384 ;

const int RarEntry::ATTRIBUTE_WIN_VIRTUAL = 65536 ;

const int RarEntry::ATTRIBUTE_UNIX_WORLD_EXECUTE = 1 ;

const int RarEntry::ATTRIBUTE_UNIX_WORLD_WRITE = 2 ;

const int RarEntry::ATTRIBUTE_UNIX_WORLD_READ = 4 ;

const int RarEntry::ATTRIBUTE_UNIX_GROUP_EXECUTE = 8 ;

const int RarEntry::ATTRIBUTE_UNIX_GROUP_WRITE = 16 ;

const int RarEntry::ATTRIBUTE_UNIX_GROUP_READ = 32 ;

const int RarEntry::ATTRIBUTE_UNIX_OWNER_EXECUTE = 64 ;

const int RarEntry::ATTRIBUTE_UNIX_OWNER_WRITE = 128 ;

const int RarEntry::ATTRIBUTE_UNIX_OWNER_READ = 256 ;

const int RarEntry::ATTRIBUTE_UNIX_STICKY = 512 ;

const int RarEntry::ATTRIBUTE_UNIX_SETGID = 1024 ;

const int RarEntry::ATTRIBUTE_UNIX_SETUID = 2048 ;

const int RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET = 61440 ;

const int RarEntry::ATTRIBUTE_UNIX_FIFO = 4096 ;

const int RarEntry::ATTRIBUTE_UNIX_CHAR_DEV = 8192 ;

const int RarEntry::ATTRIBUTE_UNIX_DIRECTORY = 16384 ;

const int RarEntry::ATTRIBUTE_UNIX_BLOCK_DEV = 24576 ;

const int RarEntry::ATTRIBUTE_UNIX_REGULAR_FILE = 32768 ;

const int RarEntry::ATTRIBUTE_UNIX_SYM_LINK = 40960 ;

const int RarEntry::ATTRIBUTE_UNIX_SOCKET = 49152 ;

/* 方法 */

public bool extract ( string $dir [, string $filepath = "" [, string $password = NULL [, bool $extended_data = false ]]] )

public int getAttr ( void )

public string getCrc ( void )

public string getFileTime ( void )

public int getHostOs ( void )

public int getMethod ( void )

public string getName ( void )

public int getPackedSize ( void )

public resourcefalse getStream ([ string $password ] )

public int getUnpackedSize ( void )

public int getVersion ( void )

public bool isDirectory ( void )

public bool isEncrypted ( void )

public string __toString ( void )

}

预定义常量

RarEntry::HOST_MSDOS
If the return value of RarEntry::getHostOs equals this constant, MS-DOS was used to add this entry. Use instead of RAR_HOST_MSDOS.

RarEntry::HOST_OS2
If the return value of RarEntry::getHostOs equals this constant, OS/2 was used to add this entry. Intended to replace RAR_HOST_OS2.

RarEntry::HOST_WIN32
If the return value of RarEntry::getHostOs equals this constant, Microsoft Windows was used to add this entry. Intended to replace RAR_HOST_WIN32.

RarEntry::HOST_UNIX
If the return value of RarEntry::getHostOs equals this constant, an unspecified UNIX OS was used to add this entry. Intended to replace RAR_HOST_UNIX.

RarEntry::HOST_MACOS
If the return value of RarEntry::getHostOs equals this constant, Mac OS was used to add this entry.

RarEntry::HOST_BEOS
If the return value of RarEntry::getHostOs equals this constant, BeOS was used to add this entry. Intended to replace RAR_HOST_BEOS.

RarEntry::ATTRIBUTE_WIN_READONLY
Bit that represents a Windows entry with a read-only attribute. To be used with RarEntry::getAttr on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_HIDDEN
Bit that represents a Windows entry with a hidden attribute. To be used with RarEntry::getAttr on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_SYSTEM
Bit that represents a Windows entry with a system attribute. To be used with RarEntry::getAttr on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_DIRECTORY
Bit that represents a Windows entry with a directory attribute (entry is a directory). To be used with RarEntry::getAttr on entries whose host OS is Microsoft Windows. See also RarEntry::isDirectory, which also works with entries that were not added in WinRAR.

RarEntry::ATTRIBUTE_WIN_ARCHIVE
Bit that represents a Windows entry with an archive attribute. To be used with RarEntry::getAttr on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_DEVICE
Bit that represents a Windows entry with a device attribute. To be used with RarEntry::getAttr on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_NORMAL
Bit that represents a Windows entry with a normal file attribute (entry is NOT a directory). To be used with RarEntry::getAttr on entries whose host OS is Microsoft Windows. See also RarEntry::isDirectory, which also works with entries that were not added in WinRAR.

RarEntry::ATTRIBUTE_WIN_TEMPORARY
Bit that represents a Windows entry with a temporary attribute. To be used with RarEntry::getAttr on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_SPARSE_FILE
Bit that represents a Windows entry with a sparse file attribute (file is an NTFS sparse file). To be used with RarEntry::getAttr on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_REPARSE_POINT
Bit that represents a Windows entry with a reparse point attribute (entry is an NTFS reparse point, e.g. a directory junction or a mount file system). To be used with RarEntry::getAttr on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_COMPRESSED
Bit that represents a Windows entry with a compressed attribute (NTFS only). To be used with RarEntry::getAttr on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_OFFLINE
Bit that represents a Windows entry with an offline attribute (entry is offline and not accessible). To be used with RarEntry::getAttr on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_NOT_CONTENT_INDEXED
Bit that represents a Windows entry with a not content indexed attribute (entry is to be indexed). To be used with RarEntry::getAttr on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_ENCRYPTED
Bit that represents a Windows entry with an encrypted attribute (NTFS only). To be used with RarEntry::getAttr on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_WIN_VIRTUAL
Bit that represents a Windows entry with a virtual attribute. To be used with RarEntry::getAttr on entries whose host OS is Microsoft Windows.

RarEntry::ATTRIBUTE_UNIX_WORLD_EXECUTE
Bit that represents a UNIX entry that is world executable. To be used with RarEntry::getAttr on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_WORLD_WRITE
Bit that represents a UNIX entry that is world writable. To be used with RarEntry::getAttr on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_WORLD_READ
Bit that represents a UNIX entry that is world readable. To be used with RarEntry::getAttr on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_GROUP_EXECUTE
Bit that represents a UNIX entry that is group executable. To be used with RarEntry::getAttr on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_GROUP_WRITE
Bit that represents a UNIX entry that is group writable. To be used with RarEntry::getAttr on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_GROUP_READ
Bit that represents a UNIX entry that is group readable. To be used with RarEntry::getAttr on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_OWNER_EXECUTE
Bit that represents a UNIX entry that is owner executable. To be used with RarEntry::getAttr on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_OWNER_WRITE
Bit that represents a UNIX entry that is owner writable. To be used with RarEntry::getAttr on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_OWNER_READ
Bit that represents a UNIX entry that is owner readable. To be used with RarEntry::getAttr on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_STICKY
Bit that represents the UNIX sticky bit. To be used with RarEntry::getAttr on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_SETGID
Bit that represents the UNIX setgid attribute. To be used with RarEntry::getAttr on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_SETUID
Bit that represents the UNIX setuid attribute. To be used with RarEntry::getAttr on entries whose host OS is UNIX.

RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET
Mask to isolate the last four bits (nibble) of UNIX attributes (_S_IFMT, the type of file mask). To be used with RarEntry::getAttr on entries whose host OS is UNIX and with the constants RarEntry::ATTRIBUTE_UNIX_FIFO, RarEntry::ATTRIBUTE_UNIX_CHAR_DEV, RarEntry::ATTRIBUTE_UNIX_DIRECTORY, RarEntry::ATTRIBUTE_UNIX_BLOCK_DEV, RarEntry::ATTRIBUTE_UNIX_REGULAR_FILE, RarEntry::ATTRIBUTE_UNIX_SYM_LINK and RarEntry::ATTRIBUTE_UNIX_SOCKET.

RarEntry::ATTRIBUTE_UNIX_FIFO
Unix FIFOs will have attributes whose last four bits have this value. To be used with RarEntry::getAttr on entries whose host OS is UNIX and with the constant RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET.

RarEntry::ATTRIBUTE_UNIX_CHAR_DEV
Unix character devices will have attributes whose last four bits have this value. To be used with RarEntry::getAttr on entries whose host OS is UNIX and with the constant RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET.

RarEntry::ATTRIBUTE_UNIX_DIRECTORY
Unix directories will have attributes whose last four bits have this value. To be used with RarEntry::getAttr on entries whose host OS is UNIX and with the constant RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET. See also RarEntry::isDirectory, which also works with entries that were added in other operating systems.

RarEntry::ATTRIBUTE_UNIX_BLOCK_DEV
Unix block devices will have attributes whose last four bits have this value. To be used with RarEntry::getAttr on entries whose host OS is UNIX and with the constant RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET.

RarEntry::ATTRIBUTE_UNIX_REGULAR_FILE
Unix regular files (not directories) will have attributes whose last four bits have this value. To be used with RarEntry::getAttr on entries whose host OS is UNIX and with the constant RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET. See also RarEntry::isDirectory, which also works with entries that were added in other operating systems.

RarEntry::ATTRIBUTE_UNIX_SYM_LINK
Unix symbolic links will have attributes whose last four bits have this value. To be used with RarEntry::getAttr on entries whose host OS is UNIX and with the constant RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET.

RarEntry::ATTRIBUTE_UNIX_SOCKET
Unix sockets will have attributes whose last four bits have this value. To be used with RarEntry::getAttr on entries whose host OS is UNIX and with the constant RarEntry::ATTRIBUTE_UNIX_FINAL_QUARTET.

RarEntry::extract

Extract entry from the archive

说明

public bool RarEntry::extract ( string $dir [, string $filepath = "" [, string $password = NULL [, bool $extended_data = false ]]] )

RarEntry::extract extracts the entry's data. It will create new file in the specified dir with the name identical to the entry's name, unless the second argument is specified. See below for more information.

参数

dir
Path to the directory where files should be extracted. This parameter is considered if and only if filepath is not. If both parameters are empty an extraction to the current directory will be attempted.

filepath
Path (relative or absolute) containing the directory and filename of the extracted file. This parameter overrides both the parameter dir and the original file name.

password
The password used to encrypt this entry. If the entry is not encrypted, this value will not be used and can be omitted. If this parameter is omitted and the entry is encrypted, the password given to rar_open, if any, will be used. If a wrong password is given, either explicitly or implicitly via rar_open, CRC checking will fail and this method will fail and return false. If no password is given and one is required, this method will fail and return false. You can check whether an entry is encrypted with RarEntry::isEncrypted.

extended_data
If true, extended information such as NTFS ACLs and Unix owner information will be set in the extract files, as long as it's present in the archive.

Warning

Prior to version 2.0.0, this function would not handle relative paths correctly. Use realpath as a workaround.

返回值

成功时返回 true，或者在失败时返回 false。

更新日志

版本	说明
PECL rar 3.0.0	`extended_data` was added.
PECL rar 3.0.0	Support for RAR archives with repeated entry names is no longer defective.

范例

示例 #1 RarEntry::extract example

<?php

$rar_file = rar_open('example.rar') or die("Failed to open Rar archive");

$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");

$entry->extract('/dir/to'); // create /dir/to/Dir/file.txt
$entry->extract(false, '/dir/to/new_name.txt'); // create /dir/to/new_name.txt

?>

示例 #2 How to extract all files in archive:

<?php

/* example by Erik Jenssen aka erix */

$filename = "foobar.rar";
$filepath = "/home/foo/bar/";

$rar_file = rar_open($filepath.$filename);
$list = rar_list($rar_file);
foreach($list as $file) {
    $entry = rar_entry_get($rar_file, $file);
    $entry->extract("."); // extract to the current dir
}
rar_close($rar_file);

?>

参见

RarEntry::getStream
rar:// wrapper

RarEntry::getAttr

Get attributes of the entry

说明

public int RarEntry::getAttr ( void )

Returns the OS-dependent attributes of the archive entry.

参数

此函数没有参数。

返回值

Returns the attributes or false on error.

范例

示例 #1 RarEntry::getAttr example

<?php

$rar_file = rar_open('example.rar') or die("Can't open Rar archive");

$entry = rar_entry_get($rar_file, 'dir/in/the/archive') or die("Can't find such entry");

$host_os = $entry->getHostOs();
$attr = $entry->getAttr();

switch($host_os) {
    case RAR_HOST_MSDOS:
    case RAR_HOST_OS2:
    case RAR_HOST_WIN32:
    case RAR_HOST_MACOS:
        printf("%c%c%c%c%c%c\n",
                ($attr & 0x08) ? 'V' : '.',
                ($attr & 0x10) ? 'D' : '.',
                ($attr & 0x01) ? 'R' : '.',
                ($attr & 0x02) ? 'H' : '.',
                ($attr & 0x04) ? 'S' : '.',
                ($attr & 0x20) ? 'A' : '.');
        break;
    case RAR_HOST_UNIX:
    case RAR_HOST_BEOS:
        switch ($attr & 0xF000)
        {
            case 0x4000:
                printf("d");
                break;
            case 0xA000:
                printf("l");
                break;
            default:
                printf("-");
                break;
        }
        printf("%c%c%c%c%c%c%c%c%c\n",
                ($attr & 0x0100) ? 'r' : '-',
                ($attr & 0x0080) ? 'w' : '-',
                ($attr & 0x0040) ? (($attr & 0x0800) ? 's':'x'):(($attr & 0x0800) ? 'S':'-'),
                ($attr & 0x0020) ? 'r' : '-',
                ($attr & 0x0010) ? 'w' : '-',
                ($attr & 0x0008) ? (($attr & 0x0400) ? 's':'x'):(($attr & 0x0400) ? 'S':'-'),
                ($attr & 0x0004) ? 'r' : '-',
                ($attr & 0x0002) ? 'w' : '-',
                ($attr & 0x0001) ? 'x' : '-');
        break;
}

rar_close($rar_file);

?>

参见

RarEntry::getHostOs
The constants in RarEntry

RarEntry::getCrc

Get CRC of the entry

说明

public string RarEntry::getCrc ( void )

Returns an hexadecimal string representation of the CRC of the archive entry.

参数

此函数没有参数。

返回值

Returns the CRC of the archive entry or false on error.

更新日志

版本	说明
PECL rar 2.0.0	This method now returns correct values for multiple volume archives.

RarEntry::getFileTime

Get entry last modification time

说明

public string RarEntry::getFileTime ( void )

Gets entry last modification time.

参数

此函数没有参数。

返回值

Returns entry last modification time as string in format YYYY-MM-DD HH:II:SS, or false on error.

RarEntry::getHostOs

Get entry host OS

说明

public int RarEntry::getHostOs ( void )

Returns the code of the host OS of the archive entry.

参数

此函数没有参数。

返回值

Returns the code of the host OS, or false on error.

范例

示例 #1 RarEntry::getHostOs example (version >= 2.0.0)

<?php

$rar_file = rar_open('example.rar') or die("Failed to open Rar archive");

$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");

switch ($entry->getHostOs()) {
    case RarEntry::HOST_MSDOS:
        echo "MS-DOS\n";
        break;
    case RarEntry::HOST_OS2:
        echo "OS2\n";
        break;
    case RarEntry::HOST_WIN32:
        echo "Win32\n";
        break;
    case RarEntry::HOST_MACOS:
        echo "MacOS\n";
        break;
    case RarEntry::HOST_UNIX:
        echo "Unix/Linux\n";
        break;
    case RarEntry::HOST_BEOS:
        echo "BeOS\n";
        break;
}

?>

示例 #2 RarEntry::getHostOs example (version \<= 1.0.0)

<?php

$rar_file = rar_open('example.rar') or die("Failed to open Rar archive");

$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");

switch ($entry->getHostOs()) {
    case RAR_HOST_MSDOS:
        echo "MS-DOS\n";
        break;
    case RAR_HOST_OS2:
        echo "OS2\n";
        break;
    case RAR_HOST_WIN32:
        echo "Win32\n";
        break;
    case RAR_HOST_MACOS:
        echo "MacOS\n";
        break;
    case RAR_HOST_UNIX:
        echo "Unix/Linux\n";
        break;
    case RAR_HOST_BEOS:
        echo "BeOS\n";
        break;
}

?>

参见

RarEntry::extract

RarEntry::getMethod

Get pack method of the entry

说明

public int RarEntry::getMethod ( void )

RarEntry::getMethod returns number of the method used when adding current archive entry.

参数

此函数没有参数。

返回值

Returns the method number or false on error.

范例

示例 #1 RarEntry::getMethod example

<?php

$rar_file = rar_open('example.rar') or die("Failed to open Rar archive");

$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");

echo "Method number: " . $entry->getMethod();

?>

RarEntry::getName

Get name of the entry

说明

public string RarEntry::getName ( void )

Returns the name (with path) of the archive entry.

参数

此函数没有参数。

返回值

Returns the entry name as a string, or false on error.

更新日志

版本	说明
PECL rar 2.0.0	As of version 2.0.0, the returned string is encoded in Unicode/UTF-8.

范例

示例 #1 RarEntry::getName example

<?php

//this example is safe even in pages not encoded in UTF-8
//for those encoded in UTF-8, the call to mb_convert_encoding is unnecessary

$rar_file = rar_open('example.rar') or die("Failed to open Rar archive");

$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");

echo "Entry name: " . mb_convert_encoding(
    htmlentities(
        $entry->getName(),
        ENT_COMPAT,
        "UTF-8"
    ),
    "HTML-ENTITIES",
    "UTF-8"
);

?>

RarEntry::getPackedSize

Get packed size of the entry

说明

public int RarEntry::getPackedSize ( void )

Get packed size of the archive entry.

Note:

Note that on platforms with 32-bit longs (that includes Windows x64), the maximum size returned is capped at 2 GiB. Check the constant PHP_INT_MAX.

参数

此函数没有参数。

返回值

Returns the packed size, or false on error.

更新日志

版本	说明
PECL rar 2.0.0	This method now returns correct values of packed sizes bigger than 2 GiB on platforms with 64-bit ints and never returns negative values on other platforms.

范例

示例 #1 RarEntry::getPackedSize example

<?php

$rar_file = rar_open('example.rar') or die("Failed to open Rar archive");

$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");

echo "Packed size of " . $entry->getName() . " = " . $entry->getPackedSize() . " bytes";

?>

RarEntry::getStream

Get file handler for entry

说明

public resourcefalse RarEntry::getStream ([ string $password ] )

Returns a file handler that supports read operations. This handler provides on-the-fly decompression for this entry.

The handler is not invalidated by calling rar_close.

Warning

The resulting stream has no integrity verification. In particular, file corruption and decryption with a wrong a key will not be detected. It is the programmer's responsability to use the entry's CRC to check for integrity, if he so wishes.

参数

password
The password used to encrypt this entry. If the entry is not encrypted, this value will not be used and can be omitted. If this parameter is omitted and the entry is encrypted, the password given to rar_open, if any, will be used. If a wrong password is given, either explicitly or implicitly via rar_open, this method's resulting stream will produce wrong output. If no password is given and one is required, this method will fail and return false. You can check whether an entry is encrypted with RarEntry::isEncrypted.

返回值

The file handler 或者在失败时返回 false.

更新日志

版本	说明
PECL rar 3.0.0	Support for RAR archives with repeated entry names is no longer defective.

范例

示例 #1 RarEntry::getStream example

<?php

$rar_file = rar_open('example.rar');
if ($rar_file === false)
    die("Failed to open Rar archive");

$entry = rar_entry_get($rar_file, 'Dir/file.txt');
if ($entry === false)
    die("Failed to find such entry");

$stream = $entry->getStream();
if ($stream === false)
    die("Failed to obtain stream.");

rar_close($rar_file); //stream is independent from file

while (!feof($stream)) {
    $buff = fread($stream, 8192);
    if ($buff !== false)
        echo $buff;
    else
        break; //fread error
}

fclose($stream);

?>

参见

RarEntry::extract
rar:// wrapper

RarEntry::getUnpackedSize

Get unpacked size of the entry

说明

public int RarEntry::getUnpackedSize ( void )

Get unpacked size of the archive entry.

Note:

Note that on platforms with 32-bit longs (that includes Windows x64), the maximum size returned is capped at 2 GiB. Check the constant PHP_INT_MAX.

参数

此函数没有参数。

返回值

Returns the unpacked size, or false on error.

更新日志

版本	说明
PECL rar 2.0.0	This method now returns correct values of unpacked sizes bigger than 2 GiB on platforms with 64-bit ints and never returns negative values on other platforms.

返回值

示例 #1 RarEntry::getUnpackedSize example

<?php

$rar_file = rar_open('example.rar') or die("Failed to open Rar archive");

$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");

echo "Unpacked size of " . $entry->getName() . " = " . $entry->getPackedSize() . " bytes";

?>

RarEntry::getVersion

Get minimum version of RAR program required to unpack the entry

说明

public int RarEntry::getVersion ( void )

Returns minimum version of RAR program (e.g. WinRAR) required to unpack the entry. It is encoded as 10 * major version + minor version.

参数

此函数没有参数。

返回值

Returns the version or false on error.

范例

示例 #1 RarEntry::getVersion example

<?php

$rar_file = rar_open('example.rar') or die("Failed to open Rar archive");

$entry = rar_entry_get($rar_file, 'Dir/file.txt') or die("Failed to find such entry");

echo "Rar version required for unpacking: " . $entry->getVersion();

?>

RarEntry::isDirectory

Test whether an entry represents a directory

说明

public bool RarEntry::isDirectory ( void )

Tests whether the current entry is a directory.

参数

此函数没有参数。

返回值

Returns true if this entry is a directory and false otherwise.

注释

This function is only available starting with version 2.0.0, but one can also test whether an entry is a directory by checking the entry attributes, like this (only works for files compressed in RAR for Windows or Unix):

<?php
//...
//Open file, get entry and store in variable $e...
//...

$isDirectory = (bool) ((($e->getHostOs() == RAR_HOST_WIN32) && ($e->getAttr() & 0x10)) ||
    (($e->getHostOs() == RAR_HOST_UNIX) && (($e->getAttr() & 0xf000) == 0x4000)));
?>

RarEntry::isEncrypted

Test whether an entry is encrypted

说明

public bool RarEntry::isEncrypted ( void )

Tests whether the current entry contents are encrypted.

Note:

The password used may differ between files inside the same RAR archive.

参数

此函数没有参数。

返回值

Returns true if the current entry is encrypted and false otherwise.

RarEntry::__toString

Get text representation of entry

说明

public string RarEntry::__toString ( void )

RarEntry::__toString returns a textual representation for this entry. It includes whether the entry is a file or a directory (symbolic links and other special objects will be treated as files), the UTF-8 name of the entry and its CRC. The form and content of this representation may be changed in the future, so they cannot be relied upon.

参数

此函数没有参数。

返回值

A textual representation for the entry.

简介

This class serves two purposes: it is the type of the exceptions thrown by the RAR extension functions and methods and it allows, through static methods to query and define the error behaviour of the extension, i.e., whether exceptions are thrown or only warnings are emitted.

The following error codes are used:

-1 - error outside UnRAR library
11 - insufficient memory
12 - bad data
13 - bad archive
14 - unknown format
15 - file open error
16 - file create error
17 - file close error
18 - read error
19 - write error
20 - buffer too small
21 - unknown RAR error
22 - password required but not given

类摘要

RarException

final class RarException extends Exception {

/* 方法 */

public static bool isUsingExceptions ( void )

public static void setUsingExceptions ( bool $using_exceptions )

/* 继承的方法 */

final public string Exception::getMessage ( void )

final public Throwable Exception::getPrevious ( void )

final public mixed Exception::getCode ( void )

final public string Exception::getFile ( void )

final public int Exception::getLine ( void )

final public array Exception::getTrace ( void )

final public string Exception::getTraceAsString ( void )

public string Exception::__toString ( void )

final private void Exception::__clone ( void )

}

RarException::isUsingExceptions

Check whether error handling with exceptions is in use

说明

public static bool RarException::isUsingExceptions ( void )

Checks whether the RAR functions will emit warnings and return error values or whether they will throw exceptions in most of the circumstances (does not include some programmatic errors such as passing the wrong type of arguments).

参数

此函数没有参数。

返回值

Returns true if exceptions are being used, false otherwise.

范例

示例 #1 RarException::isUsingExceptions example

<?php
//The default is not to use exceptions
var_dump(RarException::isUsingExceptions());
?>

以上例程的输出类似于：

bool(false)

参见

RarException::setUsingExceptions

RarException::setUsingExceptions

Activate and deactivate error handling with exceptions

说明

public static void RarException::setUsingExceptions ( bool $using_exceptions )

If and only if the argument is true, then, instead of emitting warnings and returning a special value indicating error when the UnRAR library encounters an error, an exception of type RarException will be thrown.

Exceptions will also be thrown for the following errors, which occur outside the library (their error code will be -1):

attempting some operations on a closed RarArchive object or a RarEntry object relative to the first;
attempting to get an entry that does not exist with RarArchive::getEntry.

参数

using_exceptions
Should be true to activate exception throwing, false to deactivate (the default).

范例

示例 #1 RarException::setUsingExceptions example

<?php
var_dump(RarException::isUsingExceptions());
$arch = RarArchive::open("does_not_exist.rar");
var_dump($arch);

RarException::setUsingExceptions(true);
var_dump(RarException::isUsingExceptions());
$arch = RarArchive::open("does_not_exist.rar");
var_dump($arch); //not reached
?>

以上例程的输出类似于：

bool(false)

Warning: RarArchive::open(): Failed to open does_not_exist.rar: ERAR_EOPEN (file open error) in C:\php_rar\trunk\tests\test.php on line 3
bool(false)
bool(true)

Fatal error: Uncaught exception 'RarException' with message 'unRAR internal error: Failed to open does_not_exist.rar: ERAR_EOPEN (file open error)' in C:\php_rar\trunk\tests\test.php:8
Stack trace:
#0 C:\php_rar\trunk\tests\test.php(8): RarArchive::open('does_not_exist....')
#1 {main}
  thrown in C:\php_rar\trunk\tests\test.php on line 8

参见

RarException::isUsingExceptions