From 158f5204048da37d9a84b04b8cfbade0f390b850 Mon Sep 17 00:00:00 2001 From: Greg Beaver Date: Tue, 6 Feb 2007 05:46:41 +0000 Subject: [PATCH] major update of all phar docs: fix numerous small errors fix missing documentation or large omissions update references to API version to 1.0.0 add PharFileInfo->chmod() git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@229102 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/phar/fileformat.xml | 20 ++-- reference/phar/functions/phar-begin.xml | 4 +- reference/phar/functions/phar-cancompress.xml | 4 +- reference/phar/functions/phar-commit.xml | 6 +- .../functions/phar-compressallfilesbzip2.xml | 7 +- .../functions/phar-compressallfilesgz.xml | 13 +-- reference/phar/functions/phar-getversion.xml | 6 +- .../phar/functions/phar-isflushingtophar.xml | 17 +++- reference/phar/functions/phar-loadphar.xml | 5 +- reference/phar/functions/phar-mapphar.xml | 9 +- .../phar/functions/phar-offsetexists.xml | 4 +- reference/phar/functions/phar-offsetget.xml | 4 +- reference/phar/functions/phar-offsetset.xml | 12 ++- reference/phar/functions/phar-offsetunset.xml | 12 ++- reference/phar/functions/phar-setmetadata.xml | 12 +-- reference/phar/functions/phar-setstub.xml | 26 ++--- .../functions/phar-uncompressallfiles.xml | 44 +++++---- .../phar/functions/pharfileinfo-chmod.xml | 96 +++++++++++++++++++ .../phar/functions/pharfileinfo-construct.xml | 26 ++--- .../pharfileinfo-getcompressedsize.xml | 14 ++- .../phar/functions/pharfileinfo-getcrc32.xml | 14 ++- .../functions/pharfileinfo-getmetadata.xml | 11 ++- .../functions/pharfileinfo-getpharflags.xml | 20 ++-- .../functions/pharfileinfo-iscompressed.xml | 19 +++- .../pharfileinfo-iscompressedbzip2.xml | 24 ++++- .../functions/pharfileinfo-iscompressedgz.xml | 24 ++++- .../functions/pharfileinfo-iscrcchecked.xml | 14 ++- .../pharfileinfo-setcompressedbzip2.xml | 20 ++-- .../pharfileinfo-setcompressedgz.xml | 20 ++-- .../functions/pharfileinfo-setmetadata.xml | 19 ++-- .../pharfileinfo-setuncompressed.xml | 22 +++-- reference/phar/ini.xml | 22 +++-- reference/phar/reference.xml | 24 +++-- reference/phar/using.xml | 44 +++++++-- 34 files changed, 443 insertions(+), 195 deletions(-) create mode 100644 reference/phar/functions/pharfileinfo-chmod.xml diff --git a/reference/phar/fileformat.xml b/reference/phar/fileformat.xml index a4536cc7b9..e9e7d2e0b7 100644 --- a/reference/phar/fileformat.xml +++ b/reference/phar/fileformat.xml @@ -1,5 +1,5 @@ - +
Phar file format @@ -51,7 +51,7 @@ __HALT_COMPILER(); ]]> may be included or omitted, but there can be no more than 1 space between the ; and the close tag ]]> or the phar extension will be unable - to process the Phar archive. + to process the Phar archive's manifest.
@@ -59,7 +59,7 @@ __HALT_COMPILER(); The Phar manifest is a highly optimized format that allows per-file specification of file compression, file permissions, and even user-defined - meta-data such as user or group. All values greater than 1 byte are stored + meta-data such as file user or group. All values greater than 1 byte are stored in little-endian byte order, with the exception of the API version, which for historical reasons is stored as 3 nibbles in big-endian order. @@ -92,7 +92,7 @@ __HALT_COMPILER(); 2 bytes - API version of the Phar manifest (currently 0.9.0) + API version of the Phar manifest (currently 1.0.0) 4 bytes @@ -244,15 +244,13 @@ __HALT_COMPILER(); 0x00001000 - If set, this Phar contains at least 1 file that - is compressed with zlib compression + If set, this file is compressed with zlib compression 0x00002000 - If set, this Phar contains at least 1 file that - is compressed with bzip compression + If set, this file is compressed with bzip compression @@ -263,7 +261,9 @@ __HALT_COMPILER();
Phar Signature format - Phars containing a signature always have the signature + Phars containing a signature always have the signature appended to the + end of the Phar archive after the loader, manifest, and file contents. + The two signature formats supported at this time are MD5 and SHA1. @@ -294,7 +294,7 @@ __HALT_COMPILER(); 4 bytes - Magic "GBMB" used to define the presence of a signature. + Magic GBMB used to define the presence of a signature. diff --git a/reference/phar/functions/phar-begin.xml b/reference/phar/functions/phar-begin.xml index 5ad896f204..d718f3503f 100644 --- a/reference/phar/functions/phar-begin.xml +++ b/reference/phar/functions/phar-begin.xml @@ -1,5 +1,5 @@ - + Phar->begin @@ -64,7 +64,7 @@ $p['file3.txt']->setMetaData(42); $p->setStub(" - + Phar::canCompress @@ -39,7 +39,7 @@ - + Phar->commit @@ -57,12 +57,12 @@ commit(); +$p->begin(); var_dump($p->getStub()); $p->setStub(" - + Phar->compressAllFilesBZIP2 @@ -13,11 +13,12 @@ - This method causes all files in the Phar archive to be compressed using bzip2 compression. + This method compresses all files in the Phar archive using bzip2 compression. The bzip2 extension must be enabled to take advantage of this feature. In addition, if any files are already compressed using gzip compression, the zlib extension must be enabled in order - to decompress the file. As with all functionality that modifies the contents of + to decompress the files prior to re-compressing with bzip2 compression. + As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed. diff --git a/reference/phar/functions/phar-compressallfilesgz.xml b/reference/phar/functions/phar-compressallfilesgz.xml index 4c331ecf91..ea72041c57 100644 --- a/reference/phar/functions/phar-compressallfilesgz.xml +++ b/reference/phar/functions/phar-compressallfilesgz.xml @@ -1,5 +1,5 @@ - + Phar->compressAllFilesGZ @@ -13,13 +13,14 @@ - This method causes all files in the Phar archive to be compressed using gzip compression. + This method compresses all files in the Phar archive using gzip compression. The zlib extension must be enabled to take advantage of this feature. In addition, if any files are already compressed using - bzip2 compression, the bzip2 extension must be enabled in order - to decompress the file. As with all functionality that modifies the contents of - a phar, the phar.readonly INI variable - must be off in order to succeed. + bzip2 compression, the bzip2 extension must be + enabled in order to decompress the files prior to re-compressing with gzip compression. + As with all functionality that modifies the contents of a phar, the + phar.readonly INI variable must be off + in order to succeed. diff --git a/reference/phar/functions/phar-getversion.xml b/reference/phar/functions/phar-getversion.xml index b0e30feb42..7c1e34773a 100644 --- a/reference/phar/functions/phar-getversion.xml +++ b/reference/phar/functions/phar-getversion.xml @@ -1,5 +1,5 @@ - + Phar->getVersion @@ -27,7 +27,9 @@ The opened archive's API version. This is not to be confused with the API version that the loaded phar extension will use to create - new phars. + new phars. Each Phar archive has the API version hard-coded into + its manifest. See Phar file format + documentation for more information. diff --git a/reference/phar/functions/phar-isflushingtophar.xml b/reference/phar/functions/phar-isflushingtophar.xml index b4598a96a1..fb9fab9a7d 100644 --- a/reference/phar/functions/phar-isflushingtophar.xml +++ b/reference/phar/functions/phar-isflushingtophar.xml @@ -1,5 +1,5 @@ - + Phar->isFlushingToPhar @@ -36,12 +36,22 @@ isFlushingToPhar()); +var_dump($p2->isFlushingToPhar()); +?> +=2= +begin(); var_dump($p->isFlushingToPhar()); +var_dump($p2->isFlushingToPhar()); $p->commit(); +?> +=3= +isFlushingToPhar()); +var_dump($p2->isFlushingToPhar()); ?> ]]> @@ -49,8 +59,13 @@ var_dump($p->isFlushingToPhar()); diff --git a/reference/phar/functions/phar-loadphar.xml b/reference/phar/functions/phar-loadphar.xml index 9a5281deec..6b09b68900 100644 --- a/reference/phar/functions/phar-loadphar.xml +++ b/reference/phar/functions/phar-loadphar.xml @@ -1,5 +1,5 @@ - + Phar::loadPhar @@ -16,7 +16,8 @@ This can be used to read the contents of an external Phar archive. This is most useful for assigning an alias to a phar so that subsequent references - to the phar can use the shorter alias. + to the phar can use the shorter alias, or for loading Phar archives that + only contain data and are not intended for execution/inclusion in PHP scripts. diff --git a/reference/phar/functions/phar-mapphar.xml b/reference/phar/functions/phar-mapphar.xml index 0b908d54dc..4b272e22dd 100644 --- a/reference/phar/functions/phar-mapphar.xml +++ b/reference/phar/functions/phar-mapphar.xml @@ -1,5 +1,5 @@ - + Phar::mapPhar @@ -13,8 +13,9 @@ - This static method should be used inside a Phar archive's loader stub - in order to initialize the phar. + This static method can only be used inside a Phar archive's loader stub + in order to initialize the phar when it is directly executed, or when + it is included in another script. @@ -66,7 +67,7 @@ - + Phar::offsetExists @@ -13,7 +13,7 @@ - This is an implementation of the ArrayAccess interface allowing + This is an implementation of the ArrayAccess interface allowing direct manipulation of the contents of a Phar archive using array access brackets. diff --git a/reference/phar/functions/phar-offsetget.xml b/reference/phar/functions/phar-offsetget.xml index c9de75b909..68bbc65e27 100644 --- a/reference/phar/functions/phar-offsetget.xml +++ b/reference/phar/functions/phar-offsetget.xml @@ -1,5 +1,5 @@ - + Phar::offsetGet @@ -13,7 +13,7 @@ - This is an implementation of the ArrayAccess interface allowing + This is an implementation of the ArrayAccess interface allowing direct manipulation of the contents of a Phar archive using array access brackets. offsetGet is used for retrieving files from a Phar archive. diff --git a/reference/phar/functions/phar-offsetset.xml b/reference/phar/functions/phar-offsetset.xml index 32f925dbc7..ca4154cb0c 100644 --- a/reference/phar/functions/phar-offsetset.xml +++ b/reference/phar/functions/phar-offsetset.xml @@ -1,5 +1,5 @@ - + Phar::offsetSet @@ -14,7 +14,7 @@ - This is an implementation of the ArrayAccess interface allowing + This is an implementation of the ArrayAccess interface allowing direct manipulation of the contents of a Phar archive using array access brackets. offsetSet is used for modifying an existing file, or adding a new file to a Phar archive. @@ -75,8 +75,12 @@ ]]> diff --git a/reference/phar/functions/phar-offsetunset.xml b/reference/phar/functions/phar-offsetunset.xml index f79cd8c322..f74fe64f38 100644 --- a/reference/phar/functions/phar-offsetunset.xml +++ b/reference/phar/functions/phar-offsetunset.xml @@ -1,5 +1,5 @@ - + Phar::offsetUnset @@ -13,7 +13,7 @@ - This is an implementation of the ArrayAccess interface allowing + This is an implementation of the ArrayAccess interface allowing direct manipulation of the contents of a Phar archive using array access brackets. offsetUnset is used for deleting an existing file, and is called by the unset @@ -65,8 +65,12 @@ ]]> diff --git a/reference/phar/functions/phar-setmetadata.xml b/reference/phar/functions/phar-setmetadata.xml index 4338e50ff8..4093d9cb6a 100644 --- a/reference/phar/functions/phar-setmetadata.xml +++ b/reference/phar/functions/phar-setmetadata.xml @@ -1,5 +1,5 @@ - + Phar->setMetaData @@ -9,7 +9,7 @@ &reftitle.description; intPhar->setMetaData - + mixedmetadata @@ -61,12 +61,12 @@ @unlink('brandnewphar.phar'); try { $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar'); + $p['file.php'] = 'setMetaData(array('bootstrap' => 'file.php')); + var_dump($p->getMetaData()); } catch (Exception $e) { - echo 'Could not create phar:', $e; + echo 'Could not create and/or modify phar:', $e; } -$p['file.php'] = 'setMetaData(array('bootstrap' => 'file.php')); -var_dump($p->getMetaData()); ?> ]]> diff --git a/reference/phar/functions/phar-setstub.xml b/reference/phar/functions/phar-setstub.xml index 2b05404646..1decc4e5f8 100644 --- a/reference/phar/functions/phar-setstub.xml +++ b/reference/phar/functions/phar-setstub.xml @@ -1,5 +1,5 @@ - + Phar->setStub @@ -9,7 +9,7 @@ &reftitle.description; voidPhar->setStub - + stringstub @@ -62,15 +62,19 @@ include 'phar://myphar.phar/somefile.php'; setStub(''); -include 'phar://brandnewphar.phar/a.php'; -var_dump($p->getStub()); -$p['b.php'] = 'setStub(''); -include 'phar://brandnewphar.phar/b.php'; -var_dump($p->getStub()); +try { + $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar'); + $p['a.php'] = 'setStub(''); + include 'phar://brandnewphar.phar/a.php'; + var_dump($p->getStub()); + $p['b.php'] = 'setStub(''); + include 'phar://brandnewphar.phar/b.php'; + var_dump($p->getStub()); +} catch (Exception $e) { + echo 'Write operations failed on brandnewphar.phar: ', $e; +} ?> ]]> diff --git a/reference/phar/functions/phar-uncompressallfiles.xml b/reference/phar/functions/phar-uncompressallfiles.xml index 785361e4ae..9bb8d8b2f1 100644 --- a/reference/phar/functions/phar-uncompressallfiles.xml +++ b/reference/phar/functions/phar-uncompressallfiles.xml @@ -1,5 +1,5 @@ - + Phar->uncompressAllFiles @@ -13,11 +13,11 @@ - This method causes all files in the Phar archive to be uncompressed. + This method decompresses all files in the Phar archive. If any files are already compressed using gzip compression, the zlib extension must be enabled in order - to decompress the file, and any files compressed using bzip2 compression - require the bzip2 extension to decompress the file. + to decompress the files, and any files compressed using bzip2 compression + require the bzip2 extension to decompress the files. As with all functionality that modifies the contents of a phar, the phar.readonly INI variable must be off in order to succeed. @@ -45,22 +45,26 @@ compressAllFilesGZ(); -foreach ($p as $file) { - var_dump($file->getFileName()); - var_dump($file->isCompressed()); - var_dump($file->isCompressedBZIP2()); - var_dump($file->isCompressedGZ()); -} -$p->uncompressAllFiles(); -foreach ($p as $file) { - var_dump($file->getFileName()); - var_dump($file->isCompressed()); - var_dump($file->isCompressedBZIP2()); - var_dump($file->isCompressedGZ()); +try { + $p = new Phar('/path/to/my.phar', 0, 'my.phar'); + $p['myfile.txt'] = 'hi'; + $p['myfile2.txt'] = 'hi'; + $p->compressAllFilesGZ(); + foreach ($p as $file) { + var_dump($file->getFileName()); + var_dump($file->isCompressed()); + var_dump($file->isCompressedBZIP2()); + var_dump($file->isCompressedGZ()); + } + $p->uncompressAllFiles(); + foreach ($p as $file) { + var_dump($file->getFileName()); + var_dump($file->isCompressed()); + var_dump($file->isCompressedBZIP2()); + var_dump($file->isCompressedGZ()); + } +} catch (Exception $e) { + echo 'Write operations failed on my.phar: ', $e; } ?> ]]> diff --git a/reference/phar/functions/pharfileinfo-chmod.xml b/reference/phar/functions/pharfileinfo-chmod.xml new file mode 100644 index 0000000000..5a596feb3e --- /dev/null +++ b/reference/phar/functions/pharfileinfo-chmod.xml @@ -0,0 +1,96 @@ + + + + + PharFileInfo->chmod + Sets file-specific meta-data saved with a file + + + &reftitle.description; + + voidPharFileInfo->chmod + intpermissions + + + + PharFileInfo->chmod allows setting of the executable + file permissions bit, as well as read-only bits. Writeable bits are + ignored, and set at runtime based on the + phar.readonly INI variable. + + + + + + &reftitle.parameters; + + + + permissions + + + permissions (see chmod) + + + + + + + + + &reftitle.examples; + + + A <function>PharFileInfo->chmod</function> example + + + +'; + // set executable bit + $p['file.sh']->chmod(0555); + var_dump($p['file.sh']->isExecutable()); +} catch (Exception $e) { + echo 'Could not create/modify phar: ', $e; +} +?> +]]> + + &example.outputs; + + + + + + + + + + diff --git a/reference/phar/functions/pharfileinfo-construct.xml b/reference/phar/functions/pharfileinfo-construct.xml index 64379a483b..2610ce8eee 100644 --- a/reference/phar/functions/pharfileinfo-construct.xml +++ b/reference/phar/functions/pharfileinfo-construct.xml @@ -1,5 +1,5 @@ - + PharFileInfo::__construct @@ -58,16 +58,20 @@ $text) { - echo "line number $line: $text"; -} -// this also works -$file = new PharFileInfo('phar:///path/to/my.phar/testfile.txt'); -foreach ($file as $line => $text) { - echo "line number $line: $text"; +try { + $p = new Phar('/path/to/my.phar', 0, 'my.phar'); + $p['testfile.txt'] = "hi\nthere\ndude"; + $file = $p['testfile.txt']; + foreach ($file as $line => $text) { + echo "line number $line: $text"; + } + // this also works + $file = new PharFileInfo('phar:///path/to/my.phar/testfile.txt'); + foreach ($file as $line => $text) { + echo "line number $line: $text"; + } +} catch (Exception $e) { + echo 'Phar operations failed: ', $e; } ?> ]]> diff --git a/reference/phar/functions/pharfileinfo-getcompressedsize.xml b/reference/phar/functions/pharfileinfo-getcompressedsize.xml index e9a6b458f9..fee55466c5 100644 --- a/reference/phar/functions/pharfileinfo-getcompressedsize.xml +++ b/reference/phar/functions/pharfileinfo-getcompressedsize.xml @@ -1,5 +1,5 @@ - + PharFileInfo->getCompressedSize @@ -33,10 +33,14 @@ getCompressedSize(); +try { + $p = new Phar('/path/to/my.phar', 0, 'my.phar'); + $p['myfile.txt'] = 'hi'; + $file = $p['myfile.txt']; + echo $file->getCompressedSize(); +} catch (Exception $e) { + echo 'Write operations failed on my.phar: ', $e; +} ?> ]]> diff --git a/reference/phar/functions/pharfileinfo-getcrc32.xml b/reference/phar/functions/pharfileinfo-getcrc32.xml index 0935429305..1766a51219 100644 --- a/reference/phar/functions/pharfileinfo-getcrc32.xml +++ b/reference/phar/functions/pharfileinfo-getcrc32.xml @@ -1,5 +1,5 @@ - + PharFileInfo->getCRC32 @@ -44,10 +44,14 @@ getCRC32(); +try { + $p = new Phar('/path/to/my.phar', 0, 'my.phar'); + $p['myfile.txt'] = 'hi'; + $file = $p['myfile.txt']; + echo $file->getCRC32(); +} catch (Exception $e) { + echo 'Write operations on my.phar.phar failed: ', $e; +} ?> ]]> diff --git a/reference/phar/functions/pharfileinfo-getmetadata.xml b/reference/phar/functions/pharfileinfo-getmetadata.xml index 2d334d0c94..af0b35d0b3 100644 --- a/reference/phar/functions/pharfileinfo-getmetadata.xml +++ b/reference/phar/functions/pharfileinfo-getmetadata.xml @@ -1,5 +1,5 @@ - + PharFileInfo->getMetaData @@ -13,6 +13,7 @@ + Return meta-data that was saved in the Phar archive's manifest for this file. @@ -43,12 +44,12 @@ @unlink('brandnewphar.phar'); try { $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar'); + $p['file.txt'] = 'hello'; + $p['file.txt']->setMetaData(array('user' => 'bill', 'mime-type' => 'text/plain')); + var_dump($p['file.txt']->getMetaData()); } catch (Exception $e) { - echo 'Could not create phar:', $e; + echo 'Could not create/modify brandnewphar.phar: ', $e; } -$p['file.txt'] = 'hello'; -$p['file.txt']->setMetaData(array('user' => 'bill', 'mime-type' => 'text/plain')); -var_dump($p['file.txt']->getMetaData()); ?> ]]> diff --git a/reference/phar/functions/pharfileinfo-getpharflags.xml b/reference/phar/functions/pharfileinfo-getpharflags.xml index afe54523f5..541ada23f0 100644 --- a/reference/phar/functions/pharfileinfo-getpharflags.xml +++ b/reference/phar/functions/pharfileinfo-getpharflags.xml @@ -1,5 +1,5 @@ - + PharFileInfo->getPharFlags @@ -12,15 +12,15 @@ - This returns the size of the file within the Phar archive. Uncompressed files will return - the same value for getCompressedSize as they will with filesize + This returns the flags set in the manifest for a Phar. This will always + return 0 in the current implementation. &reftitle.returnvalues; - The size in bytes of the file within the Phar archive on disk. + The Phar flags (always 0 in the current implementation) @@ -32,10 +32,14 @@ getPharFlags()); +try { + $p = new Phar('/path/to/my.phar', 0, 'my.phar'); + $p['myfile.txt'] = 'hi'; + $file = $p['myfile.txt']; + var_dump($file->getPharFlags()); +} catch (Exception $e) { + echo 'Could not create/modify my.phar: ', $e; +} ?> ]]> diff --git a/reference/phar/functions/pharfileinfo-iscompressed.xml b/reference/phar/functions/pharfileinfo-iscompressed.xml index 2c7524337f..cf16ddc508 100644 --- a/reference/phar/functions/pharfileinfo-iscompressed.xml +++ b/reference/phar/functions/pharfileinfo-iscompressed.xml @@ -1,5 +1,5 @@ - + PharFileInfo->isCompressed @@ -33,10 +33,18 @@ isCompressed()); +try { + $p = new Phar('/path/to/my.phar', 0, 'my.phar'); + $p['myfile.txt'] = 'hi'; + $p['myfile2.txt'] = 'hi'; + $p['myfile2.txt']->setCompressedGZ(); + $file = $p['myfile.txt']; + $file2 = $p['myfile2.txt']; + var_dump($file->isCompressed()); + var_dump($file2->isCompressed()); +} catch (Exception $e) { + echo 'Create/modify on phar my.phar failed: ', $e; +} ?> ]]> @@ -44,6 +52,7 @@ var_dump($file->isCompressed()); diff --git a/reference/phar/functions/pharfileinfo-iscompressedbzip2.xml b/reference/phar/functions/pharfileinfo-iscompressedbzip2.xml index baab47a83d..6ca17379c2 100644 --- a/reference/phar/functions/pharfileinfo-iscompressedbzip2.xml +++ b/reference/phar/functions/pharfileinfo-iscompressedbzip2.xml @@ -1,5 +1,5 @@ - + PharFileInfo->isCompressedBZIP2 @@ -33,10 +33,22 @@ isCompressedBZIP2()); +try { + $p = new Phar('/path/to/my.phar', 0, 'my.phar'); + $p['myfile.txt'] = 'hi'; + $p['myfile2.txt'] = 'hi'; + $p['myfile3.txt'] = 'hi'; + $p['myfile2.txt']->setCompressedGZ(); + $p['myfile3.txt']->setCompressedBZIP2(); + $file = $p['myfile.txt']; + $file2 = $p['myfile2.txt']; + $file3 = $p['myfile3.txt']; + var_dump($file->isCompressedBZIP2()); + var_dump($file2->isCompressedBZIP2()); + var_dump($file3->isCompressedBZIP2()); +} catch (Exception $e) { + echo 'Create/modify on phar my.phar failed: ', $e; +} ?> ]]> @@ -44,6 +56,8 @@ var_dump($file->isCompressedBZIP2()); diff --git a/reference/phar/functions/pharfileinfo-iscompressedgz.xml b/reference/phar/functions/pharfileinfo-iscompressedgz.xml index 831c5b3508..e3887227d6 100644 --- a/reference/phar/functions/pharfileinfo-iscompressedgz.xml +++ b/reference/phar/functions/pharfileinfo-iscompressedgz.xml @@ -1,5 +1,5 @@ - + PharFileInfo->isCompressedGZ @@ -33,10 +33,22 @@ isCompressedGZ()); +try { + $p = new Phar('/path/to/my.phar', 0, 'my.phar'); + $p['myfile.txt'] = 'hi'; + $p['myfile2.txt'] = 'hi'; + $p['myfile3.txt'] = 'hi'; + $p['myfile2.txt']->setCompressedGZ(); + $p['myfile3.txt']->setCompressedBZIP2(); + $file = $p['myfile.txt']; + $file2 = $p['myfile2.txt']; + $file3 = $p['myfile3.txt']; + var_dump($file->isCompressedGZ()); + var_dump($file2->isCompressedGZ()); + var_dump($file3->isCompressedGZ()); +} catch (Exception $e) { + echo 'Create/modify on phar my.phar failed: ', $e; +} ?> ]]> @@ -44,6 +56,8 @@ var_dump($file->isCompressedGZ()); diff --git a/reference/phar/functions/pharfileinfo-iscrcchecked.xml b/reference/phar/functions/pharfileinfo-iscrcchecked.xml index c27107cde0..ffa83aaae0 100644 --- a/reference/phar/functions/pharfileinfo-iscrcchecked.xml +++ b/reference/phar/functions/pharfileinfo-iscrcchecked.xml @@ -1,5 +1,5 @@ - + PharFileInfo->isCRCChecked @@ -33,10 +33,14 @@ isCRCChecked()); +try { + $p = new Phar('/path/to/my.phar', 0, 'my.phar'); + $p['myfile.txt'] = 'hi'; + $file = $p['myfile.txt']; + var_dump($file->isCRCChecked()); +} catch (Exception $e) { + echo 'Create/modify operations failed on my.phar: ', $e; +} ?> ]]> diff --git a/reference/phar/functions/pharfileinfo-setcompressedbzip2.xml b/reference/phar/functions/pharfileinfo-setcompressedbzip2.xml index 1a583cb2b6..ef57de3800 100644 --- a/reference/phar/functions/pharfileinfo-setcompressedbzip2.xml +++ b/reference/phar/functions/pharfileinfo-setcompressedbzip2.xml @@ -1,5 +1,5 @@ - + PharFileInfo->setCompressedBZIP2 @@ -13,7 +13,7 @@ - This method causes the file referenced to be compressed using bzip2 compression. + This method compresses the file inside the Phar archive using bzip2 compression. The bzip2 extension must be enabled to take advantage of this feature. In addition, if the file is already compressed using gzip compression, the zlib extension must be enabled in order @@ -41,12 +41,16 @@ isCompressedBZIP2()); -$p['myfile.txt']->setCompressedBZIP2(); -var_dump($file->isCompressedBZIP2()); +try { + $p = new Phar('/path/to/my.phar', 0, 'my.phar'); + $p['myfile.txt'] = 'hi'; + $file = $p['myfile.txt']; + var_dump($file->isCompressedBZIP2()); + $p['myfile.txt']->setCompressedBZIP2(); + var_dump($file->isCompressedBZIP2()); +} catch (Exception $e) { + echo 'Create/modify operations on my.phar failed: ', $e; +} ?> ]]> diff --git a/reference/phar/functions/pharfileinfo-setcompressedgz.xml b/reference/phar/functions/pharfileinfo-setcompressedgz.xml index 1d5bb27b86..788731c0fe 100644 --- a/reference/phar/functions/pharfileinfo-setcompressedgz.xml +++ b/reference/phar/functions/pharfileinfo-setcompressedgz.xml @@ -1,5 +1,5 @@ - + PharFileInfo->setCompressedGZ @@ -13,7 +13,7 @@ - This method causes the file referenced to be compressed using gzip compression. + This method compresses the file inside the Phar archive using gzip compression. The zlib extension must be enabled to take advantage of this feature. In addition, if the file is already compressed using bzip2 compression, the bzip2 extension must be enabled in order @@ -41,12 +41,16 @@ isCompressedGZ()); -$p['myfile.txt']->setCompressedGZ(); -var_dump($file->isCompressedGZ()); +try { + $p = new Phar('/path/to/my.phar', 0, 'my.phar'); + $p['myfile.txt'] = 'hi'; + $file = $p['myfile.txt']; + var_dump($file->isCompressedGZ()); + $p['myfile.txt']->setCompressedGZ(); + var_dump($file->isCompressedGZ()); +} catch (Exception $e) { + echo 'Create/modify operations on my.phar failed: ', $e; +} ?> ]]> diff --git a/reference/phar/functions/pharfileinfo-setmetadata.xml b/reference/phar/functions/pharfileinfo-setmetadata.xml index df736fce15..40c2b604fc 100644 --- a/reference/phar/functions/pharfileinfo-setmetadata.xml +++ b/reference/phar/functions/pharfileinfo-setmetadata.xml @@ -1,5 +1,5 @@ - + PharFileInfo->setMetaData @@ -9,7 +9,7 @@ &reftitle.description; intPharFileInfo->setMetaData - + mixedmetadata @@ -18,9 +18,10 @@ Meta-data can significantly slow down the performance of loading a phar archive if the data is large, or if there are many files containing meta-data. It is important to note that file permissions are natively supported inside a - phar, and you can use chmod to change the permissions of - files inside a phar. As with all functionality that modifies the contents of - a phar, the phar.readonly INI variable must be + phar, although it is possible to set them with the + PharFileInfo->chmod + method. As with all functionality that modifies the contents of a phar, the + phar.readonly INI variable must be off in order to succeed. @@ -62,12 +63,12 @@ @unlink('brandnewphar.phar'); try { $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar'); + $p['file.txt'] = 'hello'; + $p['file.txt']->setMetaData(array('user' => 'bill', 'mime-type' => 'text/plain')); + var_dump($p['file.txt']->getMetaData()); } catch (Exception $e) { - echo 'Could not create phar:', $e; + echo 'Could not create/modify phar: ', $e; } -$p['file.txt'] = 'hello'; -$p['file.txt']->setMetaData(array('user' => 'bill', 'mime-type' => 'text/plain')); -var_dump($p['file.txt']->getMetaData()); ?> ]]> diff --git a/reference/phar/functions/pharfileinfo-setuncompressed.xml b/reference/phar/functions/pharfileinfo-setuncompressed.xml index ca6e4af8e1..4d75963c83 100644 --- a/reference/phar/functions/pharfileinfo-setuncompressed.xml +++ b/reference/phar/functions/pharfileinfo-setuncompressed.xml @@ -1,5 +1,5 @@ - + PharFileInfo->setUncompressed @@ -13,7 +13,7 @@ - This method causes the file referenced to be uncompressed and re-saved. + This method decompresses the file inside the Phar archive. Depending on how the file is compressed, the bzip2 or zlib extensions must be enabled to take advantage of this feature. As with all functionality that modifies the contents of @@ -40,13 +40,17 @@ setCompressedGZ(); -var_dump($file->isCompressed()); -$p['myfile.txt']->setUncompressed(); -var_dump($file->isCompressed()); +try { + $p = new Phar('/path/to/my.phar', 0, 'my.phar'); + $p['myfile.txt'] = 'hi'; + $file = $p['myfile.txt']; + $file->setCompressedGZ(); + var_dump($file->isCompressed()); + $p['myfile.txt']->setUncompressed(); + var_dump($file->isCompressed()); +} catch (Exception $e) { + echo 'Create/modify failed for my.phar: ', $e; +} ?> ]]> diff --git a/reference/phar/ini.xml b/reference/phar/ini.xml index c24b6784dd..b0451d823d 100644 --- a/reference/phar/ini.xml +++ b/reference/phar/ini.xml @@ -1,5 +1,5 @@ - +
&reftitle.runtime; &extension.runtime; @@ -19,7 +19,7 @@ phar.readonly "1" - PHP_INI_SYSTEM + PHP_INI_SYSTEM disable/enable, PHP_INI_ALL enable Available Since version 1.0.0 @@ -53,7 +53,12 @@ - This setting can only be set in php.ini due to security reasons. + This setting can only be unset in php.ini due to security reasons. + If phar.readonly is disabled in php.ini, the + user may enable phar.readonly in a script + or disable it later. If phar.readonly is + enabled in php.ini, a script may harmlessly "re-enable" + the INI variable, but may not disable it. @@ -67,14 +72,17 @@ This option will force all opened Phar archives to contain some - kind of signature (currently md5 and sha1 are supported), and will + kind of signature (currently MD5 and SHA1 are supported), and will refuse to process any Phar archive that does not contain a signature. - The option can be disabled in the system level only, but can be - enabled using ini_set in a user script regardless - of the system setting. + This setting can only be unset in php.ini due to security reasons. + If phar.require_hash is disabled in php.ini, the + user may enable phar.require_hash in a script + or disable it later. If phar.require_hash is + enabled in php.ini, a script may harmlessly "re-enable" + the INI variable, but may not disable it. diff --git a/reference/phar/reference.xml b/reference/phar/reference.xml index 38161595f6..8c8efee76a 100644 --- a/reference/phar/reference.xml +++ b/reference/phar/reference.xml @@ -1,5 +1,5 @@ - + @@ -26,18 +26,30 @@ the bz2 extension is present. In addition, iteration and other features are available if the SPL extension is available. Phar signature verification using md5 or sha1 is natively - supported if the hash extension is available. + supported to ensure archive integrity. The original implementation for Phar archives was in the PEAR package PHP_Archive, and - the implementation details are very similar. + the implementation details are very similar, although the Phar extension + is more full-featured. PHP_Archive has more flexibility in Phar creation, + and helpful debugging tools like the PHP_Archive_Manager + class, and the Phar extension supports iteration, array access, and + directly manipulating Phar contents through a simple interface. PHP_Archive + supports creation of Phar archives that can be processed using the Phar + extension or PHP_Archive seamlessly, whereas the Phar extension is designed + to create extensions that function with the Phar extension. In addition, + the Phar extension will continue to work even if the + allow_url_include or + allow_url_fopen INI variables + are disabled, while PHP_Archive-based Phar archives (without the Phar extension) + will not function.
&reftitle.required; - Phar requires PHP 5.2.1 or newer. Additional features require the + Phar requires PHP 5.2.0 or newer. Additional features require the SPL extension in order to take advantage of iteration and array access to a Phar's file contents. The phar stream does not require any additional extensions to function. @@ -45,9 +57,7 @@ You may optionally wish to enable the zlib and bzip2 extensions to take - advantage of compressed phar support. In addition, the - hash extension can be - used for signing phars and verifying integrity. + advantage of compressed phar support.
&reference.phar.installation; diff --git a/reference/phar/using.xml b/reference/phar/using.xml index 774f7e2a53..b81d000e6f 100644 --- a/reference/phar/using.xml +++ b/reference/phar/using.xml @@ -1,5 +1,5 @@ - +
Using Phar Archives: Introduction @@ -70,7 +70,8 @@ try { // only executed. if (Phar::canWrite()) { $p = new Phar(dirname(__FILE__) . '/newphar.phar', 0, 'newphar.phar'); - // create transaction - nothing is written to disk until commit() is called + // create transaction - nothing is written to newphar.phar + // until commit() is called, although temporary storage is needed $p->begin(); // add a new file, set its contents $p['file1.txt'] = 'Information'; @@ -85,14 +86,16 @@ try { $p['images/wow.jpg']->setMetaData(array('mime-type' => 'image/jpeg')); $p['index.php'] = file_get_contents('index.php'); $p->setMetaData(array('bootstrap' => 'index.php')); - // save the Phar, and set the loader stub - $p->commit('setStub('getMetaData(); require "phar://" . __FILE__ . "/" . $m["bootstrap"]; __HALT_COMPILER();'); + // save the phar archive to disk + $p->commit(); } -} catch (BadMethodCallException $e) { +} catch (Exception $e) { echo 'Could not open Phar: ', $e; } ?> @@ -126,8 +129,9 @@ file_put_contents('phar://my.phar/somefile.php', 0, $context); The phar stream wrapper does not operate on remote files, and cannot operate on remote files, and so is allowed even when the - allow_url_fopen INI option - is disabled. + allow_url_fopen and + allow_url_include INI options + are disabled. Although it is possible to create phar archives from scratch just using @@ -146,16 +150,38 @@ file_put_contents('phar://my.phar/somefile.php', 0, $context); interface, files inside a Phar archive can be accessed as if they were part of an associative array. + + It is important to note that when creating a Phar archive, the full path + should be passed to the Phar object constructor. + Relative paths will fail to initialize. + Assuming that $p is a Phar object initialized as follows: ]]> - The following is possible: + An empty Phar archive will be created at /path/to/myphar.phar, + or if /path/to/myphar.phar already exists, it will be opened + again. The literal myphar.phar deomnstrates the concept of an alias + that can be used to reference /path/to/myphar.phar in URLs as in: + + + ]]> + + With the newly created $p Phar object, + the following is possible: