From 85c97f2f3a0adfc258e29bf57bf775bd43f3a34c Mon Sep 17 00:00:00 2001 From: Greg Beaver Date: Tue, 25 Mar 2008 14:04:25 +0000 Subject: [PATCH] update phar docs to current API for 2.0 (still some work to do on modifying the compress\* methods of Phar) git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@256055 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/phar/Phar/compress.xml | 22 +- reference/phar/Phar/construct.xml | 4 +- reference/phar/Phar/convertToPhar.xml | 31 +-- reference/phar/Phar/convertToTar.xml | 8 +- reference/phar/Phar/setStub.xml | 20 +- reference/phar/PharData.xml | 83 ++++++++ reference/phar/PharData/buildFromIterator.xml | 194 ++++++++++++++++++ .../phar/PharData/compressAllFilesBZIP2.xml | 125 +++++++++++ .../phar/PharData/compressAllFilesGZ.xml | 126 ++++++++++++ reference/phar/PharData/construct.xml | 97 +++++++++ reference/phar/PharData/convertToPhar.xml | 120 +++++++++++ reference/phar/PharData/convertToTar.xml | 113 ++++++++++ reference/phar/PharData/convertToZip.xml | 115 +++++++++++ reference/phar/PharData/copy.xml | 119 +++++++++++ reference/phar/PharData/delMetadata.xml | 108 ++++++++++ reference/phar/PharData/offsetSet.xml | 121 +++++++++++ reference/phar/PharData/setAlias.xml | 82 ++++++++ reference/phar/PharData/setStub.xml | 77 +++++++ reference/phar/book.xml | 40 ++-- reference/phar/fileformat.xml | 25 ++- reference/phar/installation.xml | 5 +- reference/phar/setup.xml | 5 +- reference/phar/using.xml | 14 +- 23 files changed, 1605 insertions(+), 49 deletions(-) create mode 100644 reference/phar/PharData.xml create mode 100644 reference/phar/PharData/buildFromIterator.xml create mode 100644 reference/phar/PharData/compressAllFilesBZIP2.xml create mode 100644 reference/phar/PharData/compressAllFilesGZ.xml create mode 100644 reference/phar/PharData/construct.xml create mode 100644 reference/phar/PharData/convertToPhar.xml create mode 100644 reference/phar/PharData/convertToTar.xml create mode 100644 reference/phar/PharData/convertToZip.xml create mode 100644 reference/phar/PharData/copy.xml create mode 100644 reference/phar/PharData/delMetadata.xml create mode 100644 reference/phar/PharData/offsetSet.xml create mode 100644 reference/phar/PharData/setAlias.xml create mode 100644 reference/phar/PharData/setStub.xml diff --git a/reference/phar/Phar/compress.xml b/reference/phar/Phar/compress.xml index 21d2ab67bb..e0df78f418 100644 --- a/reference/phar/Phar/compress.xml +++ b/reference/phar/Phar/compress.xml @@ -1,5 +1,5 @@ - + Phar::compress @@ -39,6 +39,25 @@ + + &reftitle.parameters; + + + + compression + + + Compression must be one of Phar::GZ, + Phar::BZ2 to add compression, or Phar::NONE + to remove compression. + + + + + + + + &reftitle.errors; @@ -82,6 +101,7 @@ $p3 = $p2->compress(Phar::NONE); // exception: /path/to/my.phar already exists PharFileInfo::setCompressedBZIP2 PharFileInfo::setUncompressed PharFileInfo::setCompressedGZ + PharData::compress Phar::canCompress Phar::isCompressed Phar::compressAllFilesBZIP2 diff --git a/reference/phar/Phar/construct.xml b/reference/phar/Phar/construct.xml index c5a196e7d0..887957637a 100644 --- a/reference/phar/Phar/construct.xml +++ b/reference/phar/Phar/construct.xml @@ -1,5 +1,5 @@ - + Phar::__construct @@ -23,7 +23,7 @@ fname - Path to an existing Phar archive + Path to an existing Phar archive or to-be-created archive diff --git a/reference/phar/Phar/convertToPhar.xml b/reference/phar/Phar/convertToPhar.xml index d720b454b8..e392620ef9 100644 --- a/reference/phar/Phar/convertToPhar.xml +++ b/reference/phar/Phar/convertToPhar.xml @@ -1,9 +1,9 @@ - + Phar::convertToPhar - Convert the phar archive to the phar file format, optionally compressing the entire archive using gzip or bzip2 compression + Convert the phar archive to the phar file format @@ -11,7 +11,7 @@ &reftitle.description; boolPhar::convertToPhar - intcompression + stringextension &phar.write; @@ -25,11 +25,13 @@ - compression + extension - This can be one of Phar::GZ or Phar::BZ2. - By default, no compression is applied. + By default, the extension is .phar for converting + from uncompressed tar archives or any zip archive, .phar.gz for + conversion from zlib-compressed tar archives, or .phar.bz2 + for conversion from bzip2-compressed tar archives. @@ -40,9 +42,8 @@ &reftitle.returnvalues; - The method returns &true; on success, but it is safer to encase the - call within a try/catch block and assume success if an exception is - not thrown. + The method returns a Phar object on success and throws an + exception on failure. @@ -71,10 +72,10 @@ convertToPhar(Phar::GZ); + $tarphar = new Phar('myphar.tar.phar'); + // convert it to the phar file format + // note that myphar.tar.phar is *not* unlinked + $phar = $tarphar->convertToPhar(); $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php')); } catch (Exception $e) { // handle the error here @@ -90,10 +91,10 @@ try { &reftitle.seealso; + PharData::convertToPhar Phar::convertToTar Phar::convertToZip - Phar::compressAllFilesGZ - Phar::compressAllFilesBZIP2 + Phar::compress diff --git a/reference/phar/Phar/convertToTar.xml b/reference/phar/Phar/convertToTar.xml index c0133d5118..b6f3b202f0 100644 --- a/reference/phar/Phar/convertToTar.xml +++ b/reference/phar/Phar/convertToTar.xml @@ -1,5 +1,5 @@ - + Phar::convertToTar @@ -71,10 +71,8 @@ convertToPhar(Phar::BZ2); + $zip = new Phar('myphar.zip.phar'); + $tar = $zip->convertToTar(); $phar->setStub(' - + Phar::setStub @@ -43,6 +43,24 @@ include 'phar://myphar.phar/somefile.php'; + + &reftitle.parameters; + + + + stub + + + A string or an open stream handle to use as the executable stub for this + phar archive. + + + + + + + + &reftitle.errors; diff --git a/reference/phar/PharData.xml b/reference/phar/PharData.xml new file mode 100644 index 0000000000..c00c2ef444 --- /dev/null +++ b/reference/phar/PharData.xml @@ -0,0 +1,83 @@ + + + + + The PharData class + PharData + + + + +
+ &reftitle.intro; + + The PharData class provides a high-level interface to accessing and creating + non-executable tar and zip archives. Because these archives do not contain + a stub and cannot be executed by the phar extension, it is possible to create + and manipulate regular zip and tar files using the PharData class even if + phar.readonly php.ini setting is 1. + +
+ + +
+ &reftitle.classsynopsis; + + + + PharData + + + + + PharData + + + + extends + Phar + + + + + + Properties + + Methods + + + Inherited methods + + + + + +
+ + + + &reference.phar.entities.PharData; + + + + + diff --git a/reference/phar/PharData/buildFromIterator.xml b/reference/phar/PharData/buildFromIterator.xml new file mode 100644 index 0000000000..fb60e9727a --- /dev/null +++ b/reference/phar/PharData/buildFromIterator.xml @@ -0,0 +1,194 @@ + + + + + PharData::buildFromIterator + Construct a tar or zip archive from an iterator. + + + + &reftitle.description; + + arrayPharData::buildFromIterator + Iteratoriter + stringbase_directory + + + Populate a tar or zip archive from an iterator. Two styles of iterators are supported, + iterators that map the filename within the tar/zip to the name of a file on disk, + and iterators like DirectoryIterator that return + SplFileInfo objects. For iterators that return SplFileInfo objects, the second + parameter is required. + + + + &reftitle.examples; + + A <function>PharData::buildFromIterator</function> with SplFileInfo + + For most tar/zip archives, the archive will reflect an actual directory layout, and + the second style is the most useful. For instance, to create a tar/zip archive + containing the files in this sample directory layout: + + + + + + + + This code could be used to add these files to the "project.tar" tar archive: + + + + buildFromIterator( + new RecursiveIteratorIterator( + new RecursiveDirectoryIterator('/path/to/project')), + '/path/to/project'); +?> + ]]> + + + + The file project.tar can then be used immediately. buildFromIterator does not + set values such as compression, metadata, and this can be done after creating the + tar/zip archive. + + + As an interesting note, buildFromIterator can also be used to + copy the contents of an existing phar, tar or zip archive, as the PharData object descends + from DirectoryIterator: + + + + buildFromIterator( + new RecursiveIteratorIterator( + new Phar('/path/to/anotherphar.phar')), + 'phar:///path/to/anotherphar.phar/path/to/project'); +$phar->setStub($phar->createDefaultWebStub('cli/index.php', 'www/index.php')); +?> + ]]> + + + + + A <function>PharData::buildFromIterator</function> with other iterators + + The second form of the iterator can be used with any iterator that returns + a key => value mapping, such as an ArrayIterator: + + + + buildFromIterator( + new ArrayIterator( + array( + 'internal/file.php' => dirname(__FILE__) . '/somefile.php', + 'another/file.jpg' => fopen('/path/to/bigfile.jpg', 'rb'), + ))); +?> + ]]> + + + + + + + &reftitle.parameters; + + + + iter + + + Any iterator that either associatively maps tar/zip file to location or + returns SplFileInfo objects + + + + + base_directory + + + For iterators that return SplFileInfo objects, the portion of each + file's full path to remove when adding to the tar/zip archive + + + + + + + + + &reftitle.returnvalues; + + buildFromIterator returns an associative array + mapping internal path of file to the full path of the file on the + filesystem. + + + + + &reftitle.errors; + + This method returns UnexpectedValueException when the + iterator returns incorrect values, such as an integer key instead of a + string, a BadMethodCallException when an + SplFileInfo-based iterator is passed without a base_directory + parameter, or a PharException if there were errors + saving the phar archive. + + + + + &reftitle.seealso; + + + Phar::buildFromIterator + + + + + + + diff --git a/reference/phar/PharData/compressAllFilesBZIP2.xml b/reference/phar/PharData/compressAllFilesBZIP2.xml new file mode 100644 index 0000000000..78f21188a9 --- /dev/null +++ b/reference/phar/PharData/compressAllFilesBZIP2.xml @@ -0,0 +1,125 @@ + + + + + PharData::compressAllFilesBZIP2 + Compresses all files in the current tar/zip archive using Bzip2 compression + + + + + &reftitle.description; + + boolPharData::compressAllFilesBZIP2 + + + + + For tar archives, this method fails with a PharException, as + there is no provision in the tar file format to compress individual files. To compress + an entire tar archive, use PharData::compress. + + + This method compresses all files in the zip 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 files prior to re-compressing with bzip2 compression. + + + + + &reftitle.errors; + + Throws BadMethodCallException if + the bzip2 + extension is not available, or if any files are compressed using + gzip compression and the zlib extension + is not enabled. + + + + + &reftitle.examples; + + + A <function>PharData::compressAllFilesBZIP2</function> example + +getFileName()); + var_dump($file->isCompressed()); + var_dump($file->isCompressedBZIP2()); + var_dump($file->isCompressedGZ()); +} +$p->compressAllFilesBZIP2(); +foreach ($p as $file) { + var_dump($file->getFileName()); + var_dump($file->isCompressed()); + var_dump($file->isCompressedBZIP2()); + var_dump($file->isCompressedGZ()); +} +?> +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + + Phar::compressAllFilesBZIP2 + PharData::compress + + + + + + + diff --git a/reference/phar/PharData/compressAllFilesGZ.xml b/reference/phar/PharData/compressAllFilesGZ.xml new file mode 100644 index 0000000000..aaa55fed49 --- /dev/null +++ b/reference/phar/PharData/compressAllFilesGZ.xml @@ -0,0 +1,126 @@ + + + + + PharData::compressAllFilesGZ + Compresses all files in the current tar/zip archive using Gzip compression + + + + &reftitle.description; + + boolPharData::compressAllFilesGZ + + + + + For tar archives, this method fails with a PharException, as + there is no provision in the tar file format to compress individual files. To compress + an entire tar archive, use PharData::compress. + + + For zip archives, 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 files prior to re-compressing with gzip compression. + + + + + &reftitle.errors; + + Throws BadMethodCallException if + the phar.readonly + INI variable is on, the zlib + extension is not available, or if any files are compressed using + bzip2 compression and the bzip2 extension + is not enabled. + + + + + &reftitle.examples; + + + A <function>PharData::compressAllFilesGZ</function> example + +getFileName()); + var_dump($file->isCompressed()); + var_dump($file->isCompressedBZIP2()); + var_dump($file->isCompressedGZ()); +} +$p->compressAllFilesGZ(); +foreach ($p as $file) { + var_dump($file->getFileName()); + var_dump($file->isCompressed()); + var_dump($file->isCompressedBZIP2()); + var_dump($file->isCompressedGZ()); +} +?> +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + + Phar::compressAllFilesGZ + PharData::compress + + + + + + + diff --git a/reference/phar/PharData/construct.xml b/reference/phar/PharData/construct.xml new file mode 100644 index 0000000000..c24ea5e05d --- /dev/null +++ b/reference/phar/PharData/construct.xml @@ -0,0 +1,97 @@ + + + + + PharData::__construct + Construct a non-executable tar or zip archive object + + + &reftitle.description; + + voidPharData::__construct + stringfname + intflags + + + + + &reftitle.parameters; + + + + fname + + + Path to an existing tar/zip archive or to-be-created archive + + + + + flags + + + flags to pass to Phar parent class RecursiveDirectoryIterator. + See SPL RecursiveDirectoryIterator docs + + + + + + + + + &reftitle.errors; + + Throws BadMethodCallException if called twice, UnexpectedValueException + if the phar archive can't be opened. + + + + + + &reftitle.examples; + + + A <function>PharData::__construct</function> example + + + + ]]> + + + + + + + + + diff --git a/reference/phar/PharData/convertToPhar.xml b/reference/phar/PharData/convertToPhar.xml new file mode 100644 index 0000000000..bec3cf6b38 --- /dev/null +++ b/reference/phar/PharData/convertToPhar.xml @@ -0,0 +1,120 @@ + + + + + PharData::convertToPhar + Convert the tar/zip archive to the phar file format + + + + + &reftitle.description; + + boolPharData::convertToPhar + stringextension + + &phar.write; + + This method is used to convert a tar/zip archive to + the executable phar file format. + + + + + &reftitle.parameters; + + + + extension + + + By default, the extension is .phar for converting + from uncompressed tar archives or any zip archive, .phar.gz for + conversion from zlib-compressed tar archives, or .phar.bz2 + for conversion from bzip2-compressed tar archives. + + + + + + + + + &reftitle.returnvalues; + + The method returns a Phar object on success and throws an + exception on failure. + + + + + &reftitle.errors; + + This method throws BadMethodCallException when unable + to compress, an unknown compression method has been specified, the requested + archive is buffering with PharData::startBuffering and + has not concluded with PharData::stopBuffering, an + UnexpectedValueException if write support is disabled, + and a PharException if any problems are encountered + during the phar creation process. + + + + + &reftitle.examples; + + + A <function>PharData::convertToPhar</function> example + + Using PharData::convertToPhar(): + + +convertToPhar(); // creates myphar.phar + $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php')); +} catch (Exception $e) { + // handle the error here +} +?> +]]> + + + + + + + &reftitle.seealso; + + + Phar::convertToPhar + + + + + + + diff --git a/reference/phar/PharData/convertToTar.xml b/reference/phar/PharData/convertToTar.xml new file mode 100644 index 0000000000..bd6c9adb71 --- /dev/null +++ b/reference/phar/PharData/convertToTar.xml @@ -0,0 +1,113 @@ + + + + + PharData::convertToTar + Convert a zip archive to the tar file format + + + + &reftitle.description; + + boolPharData::convertToTar + stringextension + + + + This method is used to convert a phar archive in phar or zip format to + the tar file format. + + + + + &reftitle.parameters; + + + + extension + + + By default, the extension is .tar for converting + from zip archives. + + + + + + + + + &reftitle.returnvalues; + + The method returns a PharData object on success and throws an + exception on failure. + + + + + &reftitle.errors; + + This method throws BadMethodCallException when unable + to compress, an unknown compression method has been specified, the requested + archive is buffering with PharData::startBuffering and + has not concluded with PharData::stopBuffering, and a + PharException if any problems are encountered + during the tar creation process. + + + + + &reftitle.examples; + + + A <function>PharData::convertToTar</function> example + + Using PharData::convertToTar(): + + +convertToTar(); +} catch (Exception $e) { + // handle the error here +} +?> +]]> + + + + + + + &reftitle.seealso; + + + Phar::convertToTar + + + + + + + diff --git a/reference/phar/PharData/convertToZip.xml b/reference/phar/PharData/convertToZip.xml new file mode 100644 index 0000000000..bdb3b47bb0 --- /dev/null +++ b/reference/phar/PharData/convertToZip.xml @@ -0,0 +1,115 @@ + + + + + PharData::convertToZip + Convert a tar archive to the zip file format + + + + &reftitle.description; + + boolPharData::convertToZip + stringextension + + + + This method is used to convert a phar archive in phar or tar format to + the zip file format. + + + + + &reftitle.parameters; + + + + extension + + + By default, the extension is .zip for converting + from tar archives. + + + + + + + + + + + &reftitle.returnvalues; + + The method returns a PharData object on success and throws an + exception on failure. + + + + + &reftitle.errors; + + This method throws BadMethodCallException when the + requested archive is buffering with PharData::startBuffering and + has not concluded with PharData::stopBuffering, and + a PharException if any problems are encountered + during the zip creation process. + + + + + &reftitle.examples; + + + A <function>PharData::convertToZip</function> example + + Using PharData::convertToZip(): + + +convertToZip(); +} catch (Exception $e) { + // handle the error here +} +?> +]]> + + + + + + + &reftitle.seealso; + + + Phar::convertToZip + + + + + + + diff --git a/reference/phar/PharData/copy.xml b/reference/phar/PharData/copy.xml new file mode 100644 index 0000000000..2c27baa226 --- /dev/null +++ b/reference/phar/PharData/copy.xml @@ -0,0 +1,119 @@ + + + + + PharData::copy + Copy a file internal to the phar archive to another new file within the phar + + + + &reftitle.description; + + boolPharData::copy + stringoldfile + stringnewfile + + + + Copy a file internal to the tar/zip archive to another new file within the same archive. + This is an object-oriented alternative to using copy with + the phar stream wrapper. + + + + + &reftitle.parameters; + + + + oldfile + + + + + + + newfile + + + + + + + + + + + &reftitle.returnvalues; + + returns &true; on success, but it is safer to encase method call in a + try/catch block and assume success if no exception is thrown. + + + + + &reftitle.errors; + + throws UnexpectedValueException if the source file does not + exist, the destination file already exists, write access is disabled, opening either + file fails, reading the source file fails, or a PharException + if writing the changes to the phar fails. + + + + + &reftitle.examples; + + + A <function>PharData::copy</function> example + + This example shows using PharData::copy and the + equivalent stream wrapper performance of the same thing. The primary + difference between the two approaches is error handling. All PharData methods + throw exceptions, whereas the stream wrapper uses trigger_error. + + +copy('a', 'b'); + echo $phar['b']; // outputs "hi" +} catch (Exception $e) { + // handle error +} + +// the stream wrapper equivalent of the above code. +// E_WARNINGS are triggered on error rather than exceptions. +copy('phar://myphar.tar/a', 'phar//myphar.tar/c'); +echo file_get_contents('phar://myphar.tar/c'); // outputs "hi" +?> +]]> + + + + + + + + diff --git a/reference/phar/PharData/delMetadata.xml b/reference/phar/PharData/delMetadata.xml new file mode 100644 index 0000000000..9c3cd25ade --- /dev/null +++ b/reference/phar/PharData/delMetadata.xml @@ -0,0 +1,108 @@ + + + + + PharData::delMetadata + Deletes the global metadata of a zip archive + + + + &reftitle.description; + + intPharData::delMetadata + + + &phar.write; + + + Deletes the global metadata of the zip archive + + + + + &reftitle.parameters; + + + + + + &reftitle.returnvalues; + + returns &true; on success, but it is better to check for thrown exception, + and assume success if none is thrown. + + + + + &reftitle.errors; + + Throws PharException if errors occur while flushing + changes to disk. + + + + + + &reftitle.examples; + + + A <function>PharData::delMetaData</function> example + +getMetadata()); + $phar->setMetadata("hi there"); + var_dump($phar->getMetadata()); + $phar->delMetadata(); + var_dump($phar->getMetadata()); +} catch (Exception $e) { + // handle errors +} +?> +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + + Phar::delMetadata + + + + + + + diff --git a/reference/phar/PharData/offsetSet.xml b/reference/phar/PharData/offsetSet.xml new file mode 100644 index 0000000000..7eb5059a4d --- /dev/null +++ b/reference/phar/PharData/offsetSet.xml @@ -0,0 +1,121 @@ + + + + + PharData::offsetSet + set the contents of a file within the tar/zip to those of an external file or string + + + &reftitle.description; + + voidPharData::offsetSet + stringoffset + stringvalue + + + + + This is an implementation of the ArrayAccess interface allowing + direct manipulation of the contents of a tar/zip archive using + array access brackets. offsetSet is used for modifying an + existing file, or adding a new file to a tar/zip archive. + + + + + &reftitle.parameters; + + + + offset + + + The filename (relative path) to modify in a tar or zip archive. + + + + + value + + + Content of the file. + + + + + + + + &reftitle.returnvalues; + + No return values. + + + + + &reftitle.errors; + + Throws + PharException if there are any problems flushing + changes made to the tar/zip archive to disk. + + + + + &reftitle.examples; + + + A <function>PharData::offsetSet</function> example + + offsetSet should not be accessed directly, but instead used + via array access with the [] operator. + + + +]]> + + + + + + + &reftitle.seealso; + + + Phar::offsetSet + + + + + + + + diff --git a/reference/phar/PharData/setAlias.xml b/reference/phar/PharData/setAlias.xml new file mode 100644 index 0000000000..141c6bb73b --- /dev/null +++ b/reference/phar/PharData/setAlias.xml @@ -0,0 +1,82 @@ + + + + + PharData::setAlias + dummy function (Phar::setAlias is not valid for PharData) + + + + &reftitle.description; + + boolPharData::setAlias + stringalias + + + + Non-executable tar/zip archives cannot have an alias, so this method simply + throws an exception. + + + + + &reftitle.parameters; + + + + alias + + + A shorthand string that this archive can be referred to in phar + stream wrapper access. This parameter is ignored. + + + + + + + + + &reftitle.returnvalues; + + + + + + &reftitle.errors; + + Throws PharException on all method calls + + + + + &reftitle.seealso; + + + Phar::setAlias + + + + + + + diff --git a/reference/phar/PharData/setStub.xml b/reference/phar/PharData/setStub.xml new file mode 100644 index 0000000000..d8c0257e6b --- /dev/null +++ b/reference/phar/PharData/setStub.xml @@ -0,0 +1,77 @@ + + + + + PharData::setStub + dummy function (Phar::setStub is not valid for PharData) + + + &reftitle.description; + + voidPharData::setStub + stringstub + + + + + Non-executable tar/zip archives cannot have a stub, so this method simply + throws an exception. + + + + + &reftitle.parameters; + + + + stub + + + A string or an open stream handle to use as the executable stub for this + phar archive. This parameter is ignored. + + + + + + + + + + &reftitle.errors; + + Throws PharException on all method calls + + + + + &reftitle.seealso; + + + Phar::setStub + + + + + + + diff --git a/reference/phar/book.xml b/reference/phar/book.xml index eff20d966f..505bb94ebf 100644 --- a/reference/phar/book.xml +++ b/reference/phar/book.xml @@ -1,5 +1,5 @@ - + @@ -9,11 +9,24 @@ &reftitle.intro; + + The phar extension provides a way to put entire PHP applications into a single file + called a "phar" (PHP Archive) for easy distribution and installation. + In addition to providing this service, the phar extension also provides a file-format + abstraction method for creating and manipulating tar and zip files through the + PharData class, much as + PDO provides a unified interface for accessing different databases. Unlike PDO, + which cannot convert between different databases, Phar also can convert between tar, + zip and phar file formats with a single line of code. see + Phar::convertToTar for one example. + What is phar? Phar archives are best characterized as a convenient way to group several files into a single file. As such, a phar archive provides a way to distribute a complete PHP application in a single file and run it from that file - without the need to extract it to disk. + without the need to extract it to disk. Additionally, phar archives can be + executed by PHP as easily as any other file, both on the commandline and from + a web server. Phar is kind of like a thumb drive for PHP applications. Phar implements this functionality through a Stream @@ -71,22 +84,23 @@ Phar archives can be distributed as tar archives, - zip archives (if the zip - extension is enabled), or as the custom phar file format + zip archives, or as the custom phar file format designed specifically for the phar extension. Each file format has advantages and disadvantages. The tar and zip file formats can be read or extracted by any third-party tool that can read the format, but require the phar extension in order to - run with PHP. The phar file format is custom, and can only be created by the phar - extension, but has the advantage that applications created in this format will run - without having the phar extension installed. + run with PHP. The phar file format is customized and unique to the phar extension, + and can only be created by the phar extension or the PEAR package + PHP_Archive, but has the + advantage that applications created in this format will run even if the phar + extension is not enabled. In other words, even with the phar extension disabled, one can execute or include a phar-based archive. Accessing individual files within a phar archive is only - possible with the phar extension. + possible with the phar extension unless the phar archive was created by PHP_Archive. - The phar extension is capable of converting a phar archive from tar to zip or + The phar extension is also capable of converting a phar archive from tar to zip or to phar file format in a single command: @@ -103,7 +117,7 @@ - Phar is also capable of compressing individual files or an entire archive + Phar can compress individual files or an entire archive using gzip compression or bzip2 compression, and can verify archive integrity automatically through the use of md5, @@ -112,9 +126,10 @@ Lastly, the Phar extension is security-conscious, and disables write access - to phar archives by default, and requires system-level disabling of the + to executable phar archives by default, and requires system-level disabling of the phar.readonly php.ini setting in order to create or - modify phar archives. + modify phar archives. Normal tar and zip archives without an executable stub + can always be created or modified using the PharData class. If you are creating applications for distribution, you will want to read @@ -148,6 +163,7 @@ &reference.phar.creating; &reference.phar.fileformat; &reference.phar.Phar; + &reference.phar.PharData; &reference.phar.PharFileInfo; &reference.phar.PharException; diff --git a/reference/phar/fileformat.xml b/reference/phar/fileformat.xml index 1a9d44a5d7..ce6e01c580 100644 --- a/reference/phar/fileformat.xml +++ b/reference/phar/fileformat.xml @@ -1,5 +1,5 @@ - + What makes a phar a phar and not a tar or a zip?
@@ -148,6 +148,14 @@ __HALT_COMPILER(); Yes Yes + + Can be created/modified even if phar.readonly=1 + [3] + + No + Yes + Yes + @@ -172,6 +180,15 @@ __HALT_COMPILER(); + + + + [3] Only tar and zip archives without .phar in their + filename and without an executable stub .phar/stub.php + can be created if phar.readonly=1. + + +
Tar-based phars @@ -185,9 +202,9 @@ __HALT_COMPILER(); gzip or bzip2 format and still be executed by the Phar extension. - To compress an entire archive, use Phar::compressAllFilesGZ - or Phar::compressAllFilesBZIP2. To decompress an entire - archive, use Phar::uncompressAllFiles + To compress an entire archive, use Phar::compress. + To decompress an entire archive, use Phar::compress with + the Phar::NONE constant.
diff --git a/reference/phar/installation.xml b/reference/phar/installation.xml index 7d95e156a5..825fa4ca23 100644 --- a/reference/phar/installation.xml +++ b/reference/phar/installation.xml @@ -1,5 +1,5 @@ - +
&reftitle.install; @@ -8,14 +8,13 @@ - To install on Windows, follow the instructions above, modify your php.ini and restarting your web server. + To install on Windows, follow the instructions above, modify your php.ini and restart your web server. diff --git a/reference/phar/setup.xml b/reference/phar/setup.xml index bc6528f3ae..3d9b745057 100644 --- a/reference/phar/setup.xml +++ b/reference/phar/setup.xml @@ -1,5 +1,5 @@ - + &reftitle.setup; @@ -16,8 +16,7 @@ You may optionally wish to enable the zlib and bzip2 extensions to take - advantage of compressed phar support and the zip extension - to enable zip-based phar archive support (Phar version 1.3.0 or newer). + advantage of compressed phar support. Note that a bug in the zlib.deflate stream filter diff --git a/reference/phar/using.xml b/reference/phar/using.xml index eb0180ea98..9b665e05c4 100644 --- a/reference/phar/using.xml +++ b/reference/phar/using.xml @@ -1,5 +1,5 @@ - + Using Phar Archives @@ -84,7 +84,7 @@ try { if (Phar::canWrite()) { $p = new Phar('newphar.tar.phar', 0, 'newphar.tar.phar'); // make this a tar-based phar archive, compressed with gzip compression (.tar.gz) - $p->convertToTar(Phar::GZ); + $p = $p->convertToTar()->compress(Phar::GZ); // create transaction - nothing is written to newphar.phar // until stopBuffering() is called, although temporary storage is needed @@ -223,7 +223,7 @@ file_put_contents('phar://my.phar/somefile.php', 0, $context);
- Using Phar Archives: the Phar class + Using Phar Archives: the Phar and PharData class The Phar class supports reading and manipulation of Phar archives, as well as iteration through inherited functionality of @@ -233,6 +233,14 @@ 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. + + The PharData class extends the Phar, and + allows creating and modifying non-executable (data) tar and zip archives even if + phar.readonly=1 in php.ini. As such, + PharData::setAlias and PharData::setStub + are both disabled as the concept of alias and stub are unique to executable phar + archives. + It is important to note that when creating a Phar archive, the full path should be passed to the Phar object constructor.