diff --git a/reference/phar/Phar/buildFromDirectory.xml b/reference/phar/Phar/buildFromDirectory.xml new file mode 100644 index 0000000000..f278dabc39 --- /dev/null +++ b/reference/phar/Phar/buildFromDirectory.xml @@ -0,0 +1,128 @@ + + + + + Phar::buildFromDirectory + Construct a phar archive from the files within a directory. + + + + &reftitle.description; + + arrayPhar::buildFromDirectory + stringbase_dir + stringregex + + &phar.write; + + Populate a phar archive from a directory contents. The optional second + parameter is a regular expression (pcre) that is used to exclude files. + Any filename that matches the regular expression will be included, all others will be + excluded. For more fine-grained control, use Phar::buildFromIterator. + + + + &reftitle.examples; + + A <function>Phar::buildFromDirectory</function> example + + + + + + buildFromDirectory(dirname(__FILE__) . '/project'); +$phar->setStub($phar->createDefaultWebStub('cli/index.php', 'www/index.php')); + +$phar2 = new Phar('project2.phar', 0, 'project2.phar'); +// add all files in the project, only include php files +$phar->buildFromDirectory(dirname(__FILE__) . '/project', '/\.php$/'); +$phar->setStub($phar->createDefaultWebStub('cli/index.php', 'www/index.php')); +?> + ]]> + + + + + + + &reftitle.parameters; + + + + base_dir + + + The full or relative path to the directory that contains all files + to add to the archive. + + + + + regex + + + An optional pcre regular expression that is used to filter the + list of files. Only file paths matching the regular expression + will be included in the archive. + + + + + + + + + &reftitle.returnvalues; + + Phar::buildFromDirectory returns an associative array + mapping internal path of file to the full path of the file on the + filesystem. + + + + + &reftitle.errors; + + This method throws BadMethodCallException when unable + to instantiate the internal directory iterators, + or a PharException if there were errors + saving the phar archive. + + + + + &reftitle.seealso; + + + Phar::buildFromIterator + + + + + + + diff --git a/reference/phar/Phar/buildFromIterator.xml b/reference/phar/Phar/buildFromIterator.xml index c1ea20ce58..5037323e75 100644 --- a/reference/phar/Phar/buildFromIterator.xml +++ b/reference/phar/Phar/buildFromIterator.xml @@ -1,5 +1,5 @@ - + Phar::buildFromIterator @@ -167,14 +167,15 @@ $phar->setStub($phar->createDefaultWebStub('cli/index.php', 'www/index.php')); - + diff --git a/reference/phar/Phar/canCompress.xml b/reference/phar/Phar/canCompress.xml index 567c7670fe..622878d3c8 100644 --- a/reference/phar/Phar/canCompress.xml +++ b/reference/phar/Phar/canCompress.xml @@ -1,5 +1,5 @@ - + Phar::canCompress @@ -67,19 +67,15 @@ if (Phar::canCompress()) { PharFileInfo::getCompressedSize - PharFileInfo::isCompressedBZIP2 PharFileInfo::isCompressed - PharFileInfo::isCompressedGZ - PharFileInfo::setCompressedBZIP2 - PharFileInfo::setUncompressed - PharFileInfo::setCompressedGZ + PharFileInfo::compress + PharFileInfo::decompress Phar::isCompressed - Phar::compressAllFilesBZIP2 - Phar::compressAllFilesGZ + Phar::compressFiles + Phar::decompressFiles Phar::getSupportedCompression - Phar::convertToPhar - Phar::convertToTar - Phar::uncompressAllFiles + Phar::convertToExecutable + Phar::convertToData diff --git a/reference/phar/Phar/compress.xml b/reference/phar/Phar/compress.xml index e0df78f418..bbca9c591c 100644 --- a/reference/phar/Phar/compress.xml +++ b/reference/phar/Phar/compress.xml @@ -1,5 +1,5 @@ - + Phar::compress @@ -11,6 +11,7 @@ objectPhar::compress intcompression + stringextension &phar.write; @@ -32,7 +33,8 @@ In addition, this method automatically renames the archive, appending .gz, .bz2 or removing the extension if passed Phar::NONE to - remove compression. + remove compression. Alternatively, a file extension may be specified with the second + parameter. A Phar object is returned. @@ -53,6 +55,18 @@ + + extension + + + By default, the extension is .phar.gz + or .phar.bz2 for compressing phar archives, and + .phar.tar.gz or .phar.tar.bz2 for + compressing tar archives. For decompressing, the default file extensions + are .phar and .phar.tar. + + + @@ -95,18 +109,16 @@ $p3 = $p2->compress(Phar::NONE); // exception: /path/to/my.phar already exists PharFileInfo::getCompressedSize - PharFileInfo::isCompressedBZIP2 PharFileInfo::isCompressed - PharFileInfo::isCompressedGZ - PharFileInfo::setCompressedBZIP2 - PharFileInfo::setUncompressed - PharFileInfo::setCompressedGZ + PharFileInfo::compress + PharFileInfo::decompress PharData::compress Phar::canCompress Phar::isCompressed - Phar::compressAllFilesBZIP2 + Phar::decompress Phar::getSupportedCompression - Phar::uncompressAllFiles + Phar::compressFiles + Phar::decompressFiles diff --git a/reference/phar/Phar/compressAllFilesBZIP2.xml b/reference/phar/Phar/compressAllFilesBZIP2.xml index 00fc86c8ad..1632ba48d3 100644 --- a/reference/phar/Phar/compressAllFilesBZIP2.xml +++ b/reference/phar/Phar/compressAllFilesBZIP2.xml @@ -1,5 +1,5 @@ - + Phar::compressAllFilesBZIP2 @@ -13,7 +13,8 @@ boolPhar::compressAllFilesBZIP2 - &phar.write; + &phar.removed.pharcompress; + &phar.write; This method compresses all files in the Phar archive using bzip2 compression. @@ -106,8 +107,6 @@ bool(false) Phar::isCompressed Phar::compressAllFilesGZ Phar::getSupportedCompression - Phar::convertToPhar - Phar::convertToTar Phar::uncompressAllFiles diff --git a/reference/phar/Phar/compressAllFilesGZ.xml b/reference/phar/Phar/compressAllFilesGZ.xml index b6720f3cdb..9b1407e600 100644 --- a/reference/phar/Phar/compressAllFilesGZ.xml +++ b/reference/phar/Phar/compressAllFilesGZ.xml @@ -1,5 +1,5 @@ - + Phar::compressAllFilesGZ @@ -12,7 +12,8 @@ boolPhar::compressAllFilesGZ - &phar.write; + &phar.removed.pharcompress; + &phar.write; For tar-based phar archives, this method compresses the entire archive using @@ -111,8 +112,6 @@ bool(true) Phar::isCompressed Phar::compressAllFilesBZIP2 Phar::getSupportedCompression - Phar::convertToPhar - Phar::convertToTar Phar::uncompressAllFiles diff --git a/reference/phar/Phar/compressFiles.xml b/reference/phar/Phar/compressFiles.xml new file mode 100644 index 0000000000..367cec3ff7 --- /dev/null +++ b/reference/phar/Phar/compressFiles.xml @@ -0,0 +1,158 @@ + + + + + Phar::compressFiles + Compresses all files in the current Phar archive + + + + &reftitle.description; + + boolPhar::compressFiles + intcompression + + &phar.write; + + + For tar-based phar archives, this method throws a + BadMethodCallException, as compression of individual + files within a tar archive is not supported by the file format. Use + Phar::compress to compress an entire tar-based phar archive. + + + For Zip-based and phar-based phar archives, this method compresses all files in the + Phar archive using the specified compression. + The zlib or bzip2 + extensions must be enabled to take advantage of this feature. In addition, if any files + are already compressed using bzip2/zlib compression, the respective extension must be + enabled in order to decompress the files prior to re-compressing. + As with all functionality that modifies the contents of a phar, the + phar.readonly INI variable must be off + in order to succeed. + + + + + &reftitle.parameters; + + + + compression + + + Compression must be one of Phar::GZ, + Phar::BZ2 to add compression, or Phar::NONE + to remove 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>Phar::compressFiles</function> example + +getFileName()); + var_dump($file->isCompressed()); + var_dump($file->isCompressed(Phar::BZ2)); + var_dump($file->isCompressed(Phar::GZ)); +} +$p->compressFiles(Phar::GZ); +foreach ($p as $file) { + var_dump($file->getFileName()); + var_dump($file->isCompressed()); + var_dump($file->isCompressed(Phar::BZ2)); + var_dump($file->isCompressed(Phar::GZ)); +} +?> +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + + PharFileInfo::getCompressedSize + PharFileInfo::isCompressed + PharFileInfo::compress + PharFileInfo::decompress + Phar::canCompress + Phar::isCompressed + Phar::decompressFiles + Phar::getSupportedCompression + Phar::compress + Phar::decompress + + + + + + + diff --git a/reference/phar/Phar/convertToData.xml b/reference/phar/Phar/convertToData.xml new file mode 100644 index 0000000000..de22c1219b --- /dev/null +++ b/reference/phar/Phar/convertToData.xml @@ -0,0 +1,166 @@ + + + + + Phar::convertToData + Convert a phar archive to a non-executable tar or zip file + + + + + &reftitle.description; + + PharDataPhar::convertToData + intformat + intcompression + stringextension + + + + This method is used to convert an executable phar archive to either a + tar or zip file. To make the tar or zip non-executable, the phar + stub and phar alias files are removed from the newly created archive. + + + If no changes are specified, this method throws a BadMethodCallException + if the archive is in phar file format. For archives in tar or zip file format, + this method converts the archive to a non-executable archive. + + + If successful, the method creates a new archive on disk and returns a PharData + object. The old archive is not removed from disk, and should be done manually after + the process has finished. + + + + + &reftitle.parameters; + + + + format + + + This should be one of Phar::TAR + or Phar::ZIP. If set to &null;, the existing file format + will be preserved. + + + + + compression + + + This should be one of Phar::NONE for no whole-archive + compression, Phar::GZ for zlib-based compression, and + Phar::BZ2 for bzip-based compression. + + + + + extension + + + This parameter is used to override the default file extension for a + converted archive. Note that .phar cannot be used + anywhere in the filename for a non-executable tar or zip archive. + + + If converting to a tar-based phar archive, the + default extensions are .tar, .tar.gz, + and .tar.bz2 depending on specified compression. + For zip-based archives, the + default extension is .zip. + + + + + + + + + &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 Phar::startBuffering and + has not concluded with Phar::stopBuffering, + and a PharException if any problems are encountered + during the phar creation process. + + + + + &reftitle.examples; + + + A <function>Phar::convertToData</function> example + + Using Phar::convertToData(): + + +comvertToData(); + // convert to non-executable zip format, creates myphar.zip + $zip = $tarphar->convertToData(Phar::ZIP); + // create myphar.tbz + $tgz = $tarphar->convertToData(Phar::TAR, Phar::BZ2, '.tbz'); + // creates myphar.phar.tgz + $phar = $tarphar->convertToData(Phar::PHAR); // throws exception +} catch (Exception $e) { + // handle the error here +} +?> +]]> + + + + + + + &reftitle.seealso; + + + Phar::convertToExecutable + PharData::convertToExecutable + PharData::convertToData + + + + + + + diff --git a/reference/phar/Phar/convertToExecutable.xml b/reference/phar/Phar/convertToExecutable.xml new file mode 100644 index 0000000000..1822831492 --- /dev/null +++ b/reference/phar/Phar/convertToExecutable.xml @@ -0,0 +1,165 @@ + + + + + Phar::convertToExecutable + Convert a phar archive to another executable phar archive file format + + + + + &reftitle.description; + + PharPhar::convertToExecutable + intformat + intcompression + stringextension + + &phar.write; + + This method is used to convert a phar archive to another file format. For instance, + it can be used to create a tar-based executable phar archive from a zip-based + executable phar archive, or from an executable phar archive in the phar file format. In + addition, it can be used to apply whole-archive compression to a tar or phar-based + archive. + + + If no changes are specified, this method throws a BadMethodCallException. + + + If successful, the method creates a new archive on disk and returns a Phar + object. The old archive is not removed from disk, and should be done manually after + the process has finished. + + + + + &reftitle.parameters; + + + + format + + + This should be one of Phar::PHAR, Phar::TAR, + or Phar::ZIP. If set to &null;, the existing file format + will be preserved. + + + + + compression + + + This should be one of Phar::NONE for no whole-archive + compression, Phar::GZ for zlib-based compression, and + Phar::BZ2 for bzip-based compression. + + + + + extension + + + This parameter is used to override the default file extension for a + converted archive. Note that all zip- and tar-based phar archives must contain + .phar in their file extension in order to be processed as a + phar archive. + + + If converting to a phar-based archive, the default extensions are + .phar, .phar.gz, or .phar.bz2 + depending on the specified compression. For tar-based phar archives, the + default extensions are .phar.tar, .phar.tar.gz, + and .phar.tar.bz2. For zip-based phar archives, the + default extension is .phar.zip. + + + + + + + + + &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 Phar::startBuffering and + has not concluded with Phar::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>Phar::convertToExecutable</function> example + + Using Phar::convertToExecutable(): + + +convertToExecutable(Phar::PHAR); // creates myphar.phar + $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php')); + // creates myphar.phar.tgz + $compressed = $phar->convertToExecutable(Phar::TAR, Phar::GZ, '.phar.tgz'); +} catch (Exception $e) { + // handle the error here +} +?> +]]> + + + + + + + &reftitle.seealso; + + + Phar::convertToData + PharData::convertToExecutable + PharData::convertToData + + + + + + + diff --git a/reference/phar/Phar/convertToPhar.xml b/reference/phar/Phar/convertToPhar.xml deleted file mode 100644 index e392620ef9..0000000000 --- a/reference/phar/Phar/convertToPhar.xml +++ /dev/null @@ -1,123 +0,0 @@ - - - - - Phar::convertToPhar - Convert the phar archive to the phar file format - - - - - &reftitle.description; - - boolPhar::convertToPhar - stringextension - - &phar.write; - - This method is used to convert a phar archive in tar or zip format to - the 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 Phar::startBuffering and - has not concluded with Phar::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>Phar::convertToPhar</function> example - - Using Phar::convertToPhar(): - - -convertToPhar(); - $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php')); -} catch (Exception $e) { - // handle the error here -} -?> -]]> - - - - - - - &reftitle.seealso; - - - PharData::convertToPhar - Phar::convertToTar - Phar::convertToZip - Phar::compress - - - - - - - diff --git a/reference/phar/Phar/convertToTar.xml b/reference/phar/Phar/convertToTar.xml deleted file mode 100644 index b6f3b202f0..0000000000 --- a/reference/phar/Phar/convertToTar.xml +++ /dev/null @@ -1,120 +0,0 @@ - - - - - Phar::convertToTar - Convert the phar archive to the tar file format, optionally compressing the entire archive using gzip or bzip2 compression - - - - &reftitle.description; - - boolPhar::convertToTar - intcompression - - &phar.write; - - - This method is used to convert a phar archive in phar or zip format to - the tar file format. - - - - - &reftitle.parameters; - - - - compression - - - This can be one of Phar::GZ or Phar::BZ2. - By default, no compression is applied. - - - - - - - - - &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. - - - - - &reftitle.errors; - - This method throws BadMethodCallException when unable - to compress, an unknown compression method has been specified, the requested - archive is buffering with Phar::startBuffering and - has not concluded with Phar::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>Phar::convertToTar</function> example - - Using Phar::convertToTar(): - - -convertToTar(); - $phar->setStub(' -]]> - - - - - - - &reftitle.seealso; - - - Phar::convertToPhar - Phar::convertToZip - Phar::compressAllFilesGZ - Phar::compressAllFilesBZIP2 - - - - - - - diff --git a/reference/phar/Phar/convertToZip.xml b/reference/phar/Phar/convertToZip.xml deleted file mode 100644 index 8de8d5ca44..0000000000 --- a/reference/phar/Phar/convertToZip.xml +++ /dev/null @@ -1,109 +0,0 @@ - - - - - Phar::convertToZip - Convert the phar archive to the zip file format - - - - &reftitle.description; - - boolPhar::convertToZip - - - &phar.write; - - - This method is used to convert a phar archive in phar or tar format to - the zip file format. - - - - - &reftitle.parameters; - - No parameters are accepted. - - - - - - &reftitle.returnvalues; - - - - - - &reftitle.errors; - - This method throws BadMethodCallException when the - requested archive is buffering with Phar::startBuffering and - has not concluded with Phar::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>Phar::convertToZip</function> example - - Using Phar::convertToZip(): - - -convertToZip(); - $phar->setStub(' -]]> - - - - - - - &reftitle.seealso; - - - Phar::compressAllFilesGZ - Phar::convertToPhar - Phar::convertToTar - - - - - - - diff --git a/reference/phar/Phar/decompress.xml b/reference/phar/Phar/decompress.xml new file mode 100644 index 0000000000..777c76e5c4 --- /dev/null +++ b/reference/phar/Phar/decompress.xml @@ -0,0 +1,133 @@ + + + + + Phar::decompress + Decompresses the entire Phar archive + + + + &reftitle.description; + + objectPhar::decompress + stringextension + + &phar.write; + + + For tar-based and phar-based phar archives, this method decompresses the entire archive. + + + For Zip-based phar archives, this method fails with an exception. + The zlib extension must be enabled to decompress + an archive compressed with with gzip compression, and the + bzip2 extension must be + enabled in order to decompress an archive compressed 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. + + + In addition, this method automatically changes the file extension of the archive, + .phar + by default for phar archives, or .phar.tar for tar-based phar archives. + Alternatively, a file extension may be specified with the second + parameter. + + + A Phar object is returned. + + + + + &reftitle.parameters; + + + + extension + + + For decompressing, the default file extensions + are .phar and .phar.tar. + Use this parameter to specify another file extension. Be aware + that all executable phar archives must contain .phar + in their filename. + + + + + + + + + + &reftitle.errors; + + Throws BadMethodCallException if + the phar.readonly + INI variable is on, the zlib + extension is not available, or the bzip2 extension + is not enabled. + + + + + &reftitle.examples; + + + A <function>Phar::decompress</function> example + +decompress(); // creates /path/to/my.phar +?> +]]> + + + + + + + &reftitle.seealso; + + + PharFileInfo::getCompressedSize + PharFileInfo::isCompressed + PharFileInfo::compress + PharFileInfo::decompress + PharData::compress + Phar::canCompress + Phar::isCompressed + Phar::compress + Phar::getSupportedCompression + Phar::compressFiles + Phar::decompressFiles + + + + + + + diff --git a/reference/phar/Phar/decompressFiles.xml b/reference/phar/Phar/decompressFiles.xml new file mode 100644 index 0000000000..d95fce9217 --- /dev/null +++ b/reference/phar/Phar/decompressFiles.xml @@ -0,0 +1,139 @@ + + + + + Phar::decompressFiles + Decompresses all files in the current Phar archive + + + + &reftitle.description; + + boolPhar::decompressFiles + + + &phar.write; + + + For tar-based phar archives, this method throws a + BadMethodCallException, as compression of individual + files within a tar archive is not supported by the file format. Use + Phar::compress to compress an entire tar-based phar archive. + + + For Zip-based and phar-based phar archives, this method decompresses all files in the + Phar archive. + The zlib or bzip2 + extensions must be enabled to take advantage of this feature if any files + are compressed using bzip2/zlib compression. + As with all functionality that modifies the contents of a phar, the + phar.readonly INI variable must be off + in order to succeed. + + + + + &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>Phar::decompressFiles</function> example + +compressFiles(Phar::GZ); +foreach ($p as $file) { + var_dump($file->getFileName()); + var_dump($file->isCompressed()); + var_dump($file->isCompressed(Phar::BZ2)); + var_dump($file->isCompressed(Phar::GZ)); +} +$p->decompressFiles(); +foreach ($p as $file) { + var_dump($file->getFileName()); + var_dump($file->isCompressed()); + var_dump($file->isCompressed(Phar::BZ2)); + var_dump($file->isCompressed(Phar::GZ)); +} +?> +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + + PharFileInfo::getCompressedSize + PharFileInfo::isCompressed + PharFileInfo::compress + PharFileInfo::decompress + Phar::canCompress + Phar::isCompressed + Phar::compressFiles + Phar::getSupportedCompression + Phar::compress + Phar::decompress + + + + + + + diff --git a/reference/phar/Phar/getSupportedCompression.xml b/reference/phar/Phar/getSupportedCompression.xml index a76fcfedc1..d7275a4aac 100644 --- a/reference/phar/Phar/getSupportedCompression.xml +++ b/reference/phar/Phar/getSupportedCompression.xml @@ -1,5 +1,5 @@ - + Phar::getSupportedCompression @@ -38,19 +38,15 @@ PharFileInfo::getCompressedSize - PharFileInfo::isCompressedBZIP2 PharFileInfo::isCompressed - PharFileInfo::isCompressedGZ - PharFileInfo::setCompressedBZIP2 - PharFileInfo::setUncompressed - PharFileInfo::setCompressedGZ + PharFileInfo::compress + PharFileInfo::decompress + Phar::compress + Phar::decompress Phar::canCompress Phar::isCompressed - Phar::compressAllFilesBZIP2 - Phar::compressAllFilesGZ - Phar::convertToPhar - Phar::convertToTar - Phar::uncompressAllFiles + Phar::compressFiles + Phar::decompressFiles diff --git a/reference/phar/Phar/isCompressed.xml b/reference/phar/Phar/isCompressed.xml index f14344231e..af538b410c 100644 --- a/reference/phar/Phar/isCompressed.xml +++ b/reference/phar/Phar/isCompressed.xml @@ -1,5 +1,5 @@ - + Phar::isCompressed @@ -72,19 +72,15 @@ bool(true) PharFileInfo::getCompressedSize - PharFileInfo::isCompressedBZIP2 PharFileInfo::isCompressed - PharFileInfo::isCompressedGZ - PharFileInfo::setCompressedBZIP2 - PharFileInfo::setUncompressed - PharFileInfo::setCompressedGZ + PharFileInfo::decompress + PharFileInfo::compress + Phar::decompress + Phar::compress Phar::canCompress - Phar::compressAllFilesBZIP2 - Phar::compressAllFilesGZ + Phar::compressFiles + Phar::decompressFiles Phar::getSupportedCompression - Phar::convertToPhar - Phar::convertToTar - Phar::uncompressAllFiles diff --git a/reference/phar/Phar/isPhar.xml b/reference/phar/Phar/isPhar.xml index a13ef37904..e4ec755357 100644 --- a/reference/phar/Phar/isPhar.xml +++ b/reference/phar/Phar/isPhar.xml @@ -1,5 +1,5 @@ - + Phar::isPhar @@ -35,8 +35,8 @@ Phar::isTar Phar::isZip - Phar::convertToTar - Phar::convertToZip + Phar::convertToExecutable + Phar::convertToData diff --git a/reference/phar/Phar/isTar.xml b/reference/phar/Phar/isTar.xml index c38ce747d0..3c71506abc 100644 --- a/reference/phar/Phar/isTar.xml +++ b/reference/phar/Phar/isTar.xml @@ -1,5 +1,5 @@ - + Phar::isTar @@ -36,8 +36,8 @@ Phar::isPhar Phar::isZip - Phar::convertToPhar - Phar::convertToZip + Phar::convertToExecutable + Phar::convertToData diff --git a/reference/phar/Phar/isZip.xml b/reference/phar/Phar/isZip.xml index 7030472297..62e4a3dc00 100644 --- a/reference/phar/Phar/isZip.xml +++ b/reference/phar/Phar/isZip.xml @@ -1,5 +1,5 @@ - + Phar::isZip @@ -35,8 +35,8 @@ Phar::isPhar Phar::isTar - Phar::convertToPhar - Phar::convertToTar + Phar::convertToExecutable + Phar::convertToData diff --git a/reference/phar/Phar/uncompressAllFiles.xml b/reference/phar/Phar/uncompressAllFiles.xml index d342d1c4a4..74c1fac343 100644 --- a/reference/phar/Phar/uncompressAllFiles.xml +++ b/reference/phar/Phar/uncompressAllFiles.xml @@ -1,5 +1,5 @@ - + Phar::uncompressAllFiles @@ -11,6 +11,7 @@ boolPhar::uncompressAllFiles + &phar.removed.pharcompress; &phar.write; @@ -112,8 +113,6 @@ bool(false) Phar::compressAllFilesBZIP2 Phar::compressAllFilesGZ Phar::getSupportedCompression - Phar::convertToPhar - Phar::convertToTar diff --git a/reference/phar/PharData/compress.xml b/reference/phar/PharData/compress.xml new file mode 100644 index 0000000000..f9428292c3 --- /dev/null +++ b/reference/phar/PharData/compress.xml @@ -0,0 +1,129 @@ + + + + + PharData::compress + Compresses the entire tar/zip archive using Gzip or Bzip2 compression + + + + &reftitle.description; + + objectPharData::compress + intcompression + stringextension + + + + For tar archives, this method compresses the entire archive using + gzip compression or bzip2 compression. The resulting file can be processed with the + gunzip command/bunzip command, or accessed directly and transparently with the Phar + extension. + + + For zip archives, this method fails with an exception. + The zlib extension must be enabled to compress + with gzip compression, the bzip2 extension must be + enabled in order to compress with bzip2 compression. + + + In addition, this method automatically renames the archive, appending .gz, + .bz2 or removing the extension if passed Phar::NONE to + remove compression. Alternatively, a file extension may be specified with the second + parameter. + + + A PharData object is returned. + + + + + &reftitle.parameters; + + + + compression + + + Compression must be one of Phar::GZ, + Phar::BZ2 to add compression, or Phar::NONE + to remove compression. + + + + + extension + + + By default, the extension is .tar.gz or .tar.bz2 + for compressing a tar, and .tar for decompressing. + + + + + + + + + + &reftitle.errors; + + Throws BadMethodCallException if + the zlib + extension is not available, or the bzip2 extension + is not enabled. + + + + + &reftitle.examples; + + + A <function>PharData::compress</function> example + +compress(Phar::GZ); // copies to /path/to/my.phar.gz +$p2 = $p->compress(Phar::BZ2); // copies to /path/to/my.phar.bz2 +$p3 = $p2->compress(Phar::NONE); // exception: /path/to/my.phar already exists +?> +]]> + + + + + + + &reftitle.seealso; + + + Phar::compress + + + + + + + diff --git a/reference/phar/PharData/compressAllFilesBZIP2.xml b/reference/phar/PharData/compressAllFilesBZIP2.xml deleted file mode 100644 index 78f21188a9..0000000000 --- a/reference/phar/PharData/compressAllFilesBZIP2.xml +++ /dev/null @@ -1,125 +0,0 @@ - - - - - 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/compressFiles.xml b/reference/phar/PharData/compressFiles.xml new file mode 100644 index 0000000000..fa271c97b5 --- /dev/null +++ b/reference/phar/PharData/compressFiles.xml @@ -0,0 +1,154 @@ + + + + + PharData::compressFiles + Compresses all files in the current tar/zip archive + + + + &reftitle.description; + + boolPharData::compressFiles + intcompression + + + + For tar-based archives, this method throws a + BadMethodCallException, as compression of individual + files within a tar archive is not supported by the file format. Use + PharData::compress to compress an entire tar-based archive. + + + For Zip-based archives, this method compresses all files in the + archive using the specified compression. + The zlib or bzip2 + extensions must be enabled to take advantage of this feature. In addition, if any files + are already compressed using bzip2/zlib compression, the respective extension must be + enabled in order to decompress the files prior to re-compressing. + + + + + &reftitle.parameters; + + + + compression + + + Compression must be one of Phar::GZ, + Phar::BZ2 to add compression, or Phar::NONE + to remove 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::compressFiles</function> example + +getFileName()); + var_dump($file->isCompressed()); + var_dump($file->isCompressed(Phar::BZ2)); + var_dump($file->isCompressed(Phar::GZ)); +} +$p->compressFiles(Phar::GZ); +foreach ($p as $file) { + var_dump($file->getFileName()); + var_dump($file->isCompressed()); + var_dump($file->isCompressed(Phar::BZ2)); + var_dump($file->isCompressed(Phar::GZ)); +} +?> +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + + PharFileInfo::getCompressedSize + PharFileInfo::isCompressed + PharFileInfo::compress + PharFileInfo::decompress + Phar::canCompress + Phar::isCompressed + PharData::decompressFiles + Phar::getSupportedCompression + PharData::compress + PharData::decompress + + + + + + + diff --git a/reference/phar/PharData/convertToData.xml b/reference/phar/PharData/convertToData.xml new file mode 100644 index 0000000000..0cd3af65b1 --- /dev/null +++ b/reference/phar/PharData/convertToData.xml @@ -0,0 +1,165 @@ + + + + + PharData::convertToData + Convert a phar archive to a non-executable tar or zip file + + + + + &reftitle.description; + + PharDataPharData::convertToData + intformat + intcompression + stringextension + + + + This method is used to convert a non-executable tar or zip archive to another + non-executable format. + + + If no changes are specified, this method throws a BadMethodCallException. + This method should be used to convert a tar archive to zip format or vice-versa. Although + it is possible to simply change the compression of a tar archive using this method, + it is better to use the PharData::compress method for logical + consistency. + + + If successful, the method creates a new archive on disk and returns a PharData + object. The old archive is not removed from disk, and should be done manually after + the process has finished. + + + + + &reftitle.parameters; + + + + format + + + This should be one of Phar::TAR + or Phar::ZIP. If set to &null;, the existing file format + will be preserved. + + + + + compression + + + This should be one of Phar::NONE for no whole-archive + compression, Phar::GZ for zlib-based compression, and + Phar::BZ2 for bzip-based compression. + + + + + extension + + + This parameter is used to override the default file extension for a + converted archive. Note that .phar cannot be used + anywhere in the filename for a non-executable tar or zip archive. + + + If converting to a tar-based phar archive, the + default extensions are .tar, .tar.gz, + and .tar.bz2 depending on specified compression. + For zip-based archives, the + default extension is .zip. + + + + + + + + + &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 phar creation process. + + + + + &reftitle.examples; + + + A <function>PharData::convertToData</function> example + + Using PharData::convertToData(): + + +convertToData(Phar::ZIP); + // create myphar.tbz + $tgz = $zip->convertToData(Phar::TAR, Phar::BZ2, '.tbz'); + // creates myphar.phar.tgz + $phar = $tarphar->convertToData(Phar::PHAR); // throws exception +} catch (Exception $e) { + // handle the error here +} +?> +]]> + + + + + + + &reftitle.seealso; + + + Phar::convertToExecutable + Phar::convertToData + PharData::convertToExecutable + + + + + + + diff --git a/reference/phar/PharData/convertToExecutable.xml b/reference/phar/PharData/convertToExecutable.xml new file mode 100644 index 0000000000..d93e16cac6 --- /dev/null +++ b/reference/phar/PharData/convertToExecutable.xml @@ -0,0 +1,163 @@ + + + + + PharData::convertToExecutable + Convert a non-executable tar/zip archive to an executable phar archive + + + + + &reftitle.description; + + PharPharData::convertToExecutable + intformat + intcompression + stringextension + + &phar.write; + + This method is used to convert a non-executable tar or zip archive to an + executable phar archive. Any of the three executable file formats + (phar, tar or zip) can be used, and whole-archive compression can also be performed. + + + If no changes are specified, this method throws a BadMethodCallException. + + + If successful, the method creates a new archive on disk and returns a Phar + object. The old archive is not removed from disk, and should be done manually after + the process has finished. + + + + + &reftitle.parameters; + + + + format + + + This should be one of Phar::PHAR, Phar::TAR, + or Phar::ZIP. If set to &null;, the existing file format + will be preserved. + + + + + compression + + + This should be one of Phar::NONE for no whole-archive + compression, Phar::GZ for zlib-based compression, and + Phar::BZ2 for bzip-based compression. + + + + + extension + + + This parameter is used to override the default file extension for a + converted archive. Note that all zip- and tar-based phar archives must contain + .phar in their file extension in order to be processed as a + phar archive. + + + If converting to a phar-based archive, the default extensions are + .phar, .phar.gz, or .phar.bz2 + depending on the specified compression. For tar-based phar archives, the + default extensions are .phar.tar, .phar.tar.gz, + and .phar.tar.bz2. For zip-based phar archives, the + default extension is .phar.zip. + + + + + + + + + &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::convertToExecutable</function> example + + Using PharData::convertToExecutable(): + + +convertToExecutable(Phar::PHAR); // creates myphar.phar + $phar->setStub($phar->createDefaultStub('cli.php', 'web/index.php')); + // creates myphar.phar.tgz + $compressed = $tarphar->convertToExecutable(Phar::TAR, Phar::GZ, '.phar.tgz'); +} catch (Exception $e) { + // handle the error here +} +?> +]]> + + + + + + + &reftitle.seealso; + + + Phar::convertToExecutable + Phar::convertToData + PharData::convertToData + + + + + + + diff --git a/reference/phar/PharData/convertToPhar.xml b/reference/phar/PharData/convertToPhar.xml deleted file mode 100644 index bec3cf6b38..0000000000 --- a/reference/phar/PharData/convertToPhar.xml +++ /dev/null @@ -1,120 +0,0 @@ - - - - - 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 deleted file mode 100644 index bd6c9adb71..0000000000 --- a/reference/phar/PharData/convertToTar.xml +++ /dev/null @@ -1,113 +0,0 @@ - - - - - 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 deleted file mode 100644 index bdb3b47bb0..0000000000 --- a/reference/phar/PharData/convertToZip.xml +++ /dev/null @@ -1,115 +0,0 @@ - - - - - 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/decompress.xml b/reference/phar/PharData/decompress.xml new file mode 100644 index 0000000000..f714f8f3a8 --- /dev/null +++ b/reference/phar/PharData/decompress.xml @@ -0,0 +1,127 @@ + + + + + PharData::decompress + Decompresses the entire Phar archive + + + + &reftitle.description; + + objectPharData::decompress + stringextension + + + + For tar-based archives, this method decompresses the entire archive. + + + For Zip-based archives, this method fails with an exception. + The zlib extension must be enabled to decompress + an archive compressed with with gzip compression, and the + bzip2 extension must be + enabled in order to decompress an archive compressed with bzip2 compression. + + + In addition, this method automatically renames the file extension of the archive, + .tar by default. + Alternatively, a file extension may be specified with the second + parameter. + + + A PharData object is returned. + + + + + &reftitle.parameters; + + + + extension + + + For decompressing, the default file extension + is .phar.tar. + Use this parameter to specify another file extension. Be aware + that no non-executable archives cannot contain .phar + in their filename. + + + + + + + + + + &reftitle.errors; + + Throws BadMethodCallException if + the zlib + extension is not available, or the bzip2 extension + is not enabled. + + + + + &reftitle.examples; + + + A <function>PharData::decompress</function> example + +decompress(); // creates /path/to/my.tar +?> +]]> + + + + + + + &reftitle.seealso; + + + PharFileInfo::getCompressedSize + PharFileInfo::isCompressed + PharFileInfo::compress + PharFileInfo::decompress + PharData::compress + Phar::canCompress + Phar::isCompressed + PharData::compress + Phar::getSupportedCompression + PharData::compressFiles + PharData::decompressFiles + + + + + + + diff --git a/reference/phar/PharData/compressAllFilesGZ.xml b/reference/phar/PharData/decompressFiles.xml similarity index 53% rename from reference/phar/PharData/compressAllFilesGZ.xml rename to reference/phar/PharData/decompressFiles.xml index aaa55fed49..36ce4a5f26 100644 --- a/reference/phar/PharData/compressAllFilesGZ.xml +++ b/reference/phar/PharData/decompressFiles.xml @@ -1,30 +1,31 @@ - + - PharData::compressAllFilesGZ - Compresses all files in the current tar/zip archive using Gzip compression + PharData::decompressFiles + Decompresses all files in the current zip archive &reftitle.description; - boolPharData::compressAllFilesGZ - + boolPharData::decompressFiles + + &phar.write; - 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 tar-based archives, this method throws a + BadMethodCallException, as compression of individual + files within a tar archive is not supported by the file format. Use + PharData::compress to compress an entire tar-based archive. - 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. + For Zip-based archives, this method decompresses all files in the + archive. + The zlib or bzip2 + extensions must be enabled to take advantage of this feature if any files + are compressed using bzip2/zlib compression. @@ -32,8 +33,7 @@ &reftitle.errors; Throws BadMethodCallException if - the phar.readonly - INI variable is on, the zlib + the zlib extension is not available, or if any files are compressed using bzip2 compression and the bzip2 extension is not enabled. @@ -44,25 +44,26 @@ &reftitle.examples; - A <function>PharData::compressAllFilesGZ</function> example + A <function>PharData::decompressFiles</function> example compressFiles(Phar::GZ); foreach ($p as $file) { var_dump($file->getFileName()); var_dump($file->isCompressed()); - var_dump($file->isCompressedBZIP2()); - var_dump($file->isCompressedGZ()); + var_dump($file->isCompressed(Phar::BZ2)); + var_dump($file->isCompressed(Phar::GZ)); } -$p->compressAllFilesGZ(); +$p->decompressFiles(); foreach ($p as $file) { var_dump($file->getFileName()); var_dump($file->isCompressed()); - var_dump($file->isCompressedBZIP2()); - var_dump($file->isCompressedGZ()); + var_dump($file->isCompressed(Phar::BZ2)); + var_dump($file->isCompressed(Phar::GZ)); } ?> ]]> @@ -71,21 +72,21 @@ foreach ($p as $file) { @@ -96,8 +97,16 @@ bool(true) &reftitle.seealso; - Phar::compressAllFilesGZ + PharFileInfo::getCompressedSize + PharFileInfo::isCompressed + PharFileInfo::compress + PharFileInfo::decompress + Phar::canCompress + Phar::isCompressed + PharData::compressFiles + Phar::getSupportedCompression PharData::compress + PharData::decompress diff --git a/reference/phar/PharData/offsetUnset.xml b/reference/phar/PharData/offsetUnset.xml new file mode 100644 index 0000000000..229546cd85 --- /dev/null +++ b/reference/phar/PharData/offsetUnset.xml @@ -0,0 +1,110 @@ + + + + + PharData::offsetUnset + remove a file from a tar/zip archive + + + &reftitle.description; + + boolPharData::offsetUnset + stringoffset + + + + + This is an implementation of the ArrayAccess interface allowing + direct manipulation of the contents of a tar/zip archive using + array access brackets. offsetUnset is used for deleting an + existing file, and is called by the unset + language construct. + + + + + + &reftitle.parameters; + + + + offset + + + The filename (relative path) to modify in the tar/zip archive. + + + + + + + + + &reftitle.returnvalues; + + &return.success; + + + + + &reftitle.errors; + + Throws + PharException if there are any problems flushing + changes made to the tar/zip archive to disk. + + + + + &reftitle.examples; + + + A <function>PharData::offsetUnset</function> example + + +]]> + + + + + + + &reftitle.seealso; + + + Phar::offsetUnset + + + + + + + diff --git a/reference/phar/PharData/setMetadata.xml b/reference/phar/PharData/setMetadata.xml new file mode 100644 index 0000000000..4622ca7b16 --- /dev/null +++ b/reference/phar/PharData/setMetadata.xml @@ -0,0 +1,117 @@ + + + + + Phar::setMetadata + Sets phar archive meta-data + + + + + &reftitle.description; + + voidPhar::setMetadata + mixedmetadata + + &phar.write; + + + Phar::setMetadata should be used to store customized data + that describes something about the phar archive as a complete entity. + PharFileInfo::setMetadata should be used for file-specific meta-data. + Meta-data can slow down the performance of loading a phar archive if the data is large. + + + Some possible uses for meta-data include specifying which file within the archive + should be used to bootstrap the archive, or the location of a file manifest + like PEAR's package.xml file. + However, any useful data that describes the phar archive may be stored. + + + + + + &reftitle.parameters; + + + + metadata + + + Any PHP variable containing information to store that describes the phar archive + + + + + + + + + &reftitle.examples; + + + A <function>Phar::setMetadata</function> example + + + +setMetadata(array('bootstrap' => 'file.php')); + var_dump($p->getMetadata()); +} catch (Exception $e) { + echo 'Could not create and/or modify phar:', $e; +} +?> +]]> + + &example.outputs; + + + string(8) "file.php" +} +]]> + + + + + + + &reftitle.seealso; + + + Phar::getMetadata + Phar::delMetadata + Phar::hasMetadata + + + + + + + diff --git a/reference/phar/PharData/setSignatureAlgorithm.xml b/reference/phar/PharData/setSignatureAlgorithm.xml new file mode 100644 index 0000000000..aed1c2bc13 --- /dev/null +++ b/reference/phar/PharData/setSignatureAlgorithm.xml @@ -0,0 +1,91 @@ + + + + + Phar::setSignatureAlgorithm + set the signature algorithm for a phar and apply it. The + + + + &reftitle.description; + + arrayPhar::setSignatureAlgorithm + intsigtype + + &phar.write; + + + set the signature algorithm for a phar and apply it. The + signature algorithm must be one of Phar::MD5, + Phar::SHA1, Phar::SHA256, + Phar::SHA512, or Phar::PGP + (pgp not yet supported and falls back to SHA-1). + + + + + &reftitle.parameters; + + + + sigtype + + + One of Phar::MD5, + Phar::SHA1, Phar::SHA256, + Phar::SHA512, or Phar::PGP + + + + + + + + + &reftitle.returnvalues; + + + + + + &reftitle.errors; + + Throws UnexpectedValueException for many errors, + BadMethodCallException if called for a zip- or + a tar-based phar archive, and a PharException + if any problems occur flushing changes to disk. + + + + + &reftitle.seealso; + + + Phar::getSupportedSignatures + Phar::getSignature + + + + + + + diff --git a/reference/phar/PharFileInfo/chmod.xml b/reference/phar/PharFileInfo/chmod.xml index c61e923f1b..4cec90cf9f 100644 --- a/reference/phar/PharFileInfo/chmod.xml +++ b/reference/phar/PharFileInfo/chmod.xml @@ -1,5 +1,5 @@ - + PharFileInfo::chmod @@ -17,6 +17,11 @@ file permissions bit, as well as read-only bits. Writeable bits are ignored, and set at runtime based on the phar.readonly INI variable. + As with all functionality that modifies the contents of + a phar, the phar.readonly INI variable + must be off in order to succeed if the file is within a Phar + archive. Files within PharData archives do not have + this restriction. diff --git a/reference/phar/PharFileInfo/compress.xml b/reference/phar/PharFileInfo/compress.xml new file mode 100644 index 0000000000..a4970482eb --- /dev/null +++ b/reference/phar/PharFileInfo/compress.xml @@ -0,0 +1,112 @@ + + + + + PharFileInfo::compress + Compresses the current Phar entry with either zlib or bzip2 compression + + + &reftitle.description; + + boolPharFileInfo::compress + intcompression + + + + This method compresses the file inside the Phar archive using either bzip2 compression + or zlib compression. + The bzip2 or zlib + extension must be enabled to take + advantage of this feature. In addition, if the file is already compressed, + the respective 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 if the file is within a Phar + archive. Files within PharData archives do not have + this restriction. + + + + + &reftitle.errors; + + Throws BadMethodCallException if + the phar.readonly + INI variable is on, or if the bzip2/zlib + extension is not available. + + + + + &reftitle.examples; + + + A <function>PharFileInfo::compress</function> example + +isCompressed(Phar::BZ2)); + $p['myfile.txt']->compress(Phar::BZ2); + var_dump($file->isCompressed(Phar::BZ2)); +} catch (Exception $e) { + echo 'Create/modify operations on my.phar failed: ', $e; +} +?> +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + + PharFileInfo::getCompressedSize + PharFileInfo::isCompressed + PharFileInfo::decompress + Phar::canCompress + Phar::isCompressed + Phar::compressFiles + Phar::decompressFiles + Phar::compress + Phar::decompress + Phar::getSupportedCompression + + + + + + + diff --git a/reference/phar/PharFileInfo/decompress.xml b/reference/phar/PharFileInfo/decompress.xml new file mode 100644 index 0000000000..8c03340d75 --- /dev/null +++ b/reference/phar/PharFileInfo/decompress.xml @@ -0,0 +1,109 @@ + + + + + PharFileInfo::decompress + Decompresses the current Phar entry within the phar + + + &reftitle.description; + + boolPharFileInfo::decompress + + + + + 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 + a phar, the phar.readonly INI variable + must be off in order to succeed if the file is within a Phar + archive. Files within PharData archives do not have + this restriction. + + + + + &reftitle.errors; + + Throws BadMethodCallException if + the phar.readonly + INI variable is on, or if the bzip2/zlib + extension is not available. + + + + + &reftitle.examples; + + + A <function>PharFileInfo::decompress</function> example + +compress(Phar::GZ); + var_dump($file->isCompressed()); + $p['myfile.txt']->decompress(); + var_dump($file->isCompressed()); +} catch (Exception $e) { + echo 'Create/modify failed for my.phar: ', $e; +} +?> +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + + PharFileInfo::getCompressedSize + PharFileInfo::isCompressed + PharFileInfo::compress + Phar::canCompress + Phar::isCompressed + Phar::compressFiles + Phar::decompressFiles + Phar::compress + Phar::decompress + Phar::getSupportedCompression + + + + + + + diff --git a/reference/phar/PharFileInfo/delMetadata.xml b/reference/phar/PharFileInfo/delMetadata.xml index cc79059c39..7764bcdcbc 100644 --- a/reference/phar/PharFileInfo/delMetadata.xml +++ b/reference/phar/PharFileInfo/delMetadata.xml @@ -1,5 +1,5 @@ - + PharFileInfo::delMetadata @@ -28,6 +28,11 @@ &reftitle.returnvalues; Returns &true; if successful, &false; if the entry had no metadata. + As with all functionality that modifies the contents of + a phar, the phar.readonly INI variable + must be off in order to succeed if the file is within a Phar + archive. Files within PharData archives do not have + this restriction. diff --git a/reference/phar/PharFileInfo/getCompressedSize.xml b/reference/phar/PharFileInfo/getCompressedSize.xml index aa7c419289..80768bbdb5 100644 --- a/reference/phar/PharFileInfo/getCompressedSize.xml +++ b/reference/phar/PharFileInfo/getCompressedSize.xml @@ -1,5 +1,5 @@ - + PharFileInfo::getCompressedSize @@ -58,20 +58,16 @@ try { &reftitle.seealso; - PharFileInfo::isCompressedBZIP2 PharFileInfo::isCompressed - PharFileInfo::isCompressedGZ - PharFileInfo::setCompressedBZIP2 - PharFileInfo::setUncompressed - PharFileInfo::setCompressedGZ + PharFileInfo::decompress + PharFileInfo::compress Phar::canCompress Phar::isCompressed - Phar::compressAllFilesBZIP2 - Phar::compressAllFilesGZ + Phar::compress + Phar::decompress Phar::getSupportedCompression - Phar::convertToPhar - Phar::convertToTar - Phar::uncompressAllFiles + Phar::decompressFiles + Phar::compressFiles diff --git a/reference/phar/PharFileInfo/isCompressed.xml b/reference/phar/PharFileInfo/isCompressed.xml index 406c2b02eb..4c5d310f0c 100644 --- a/reference/phar/PharFileInfo/isCompressed.xml +++ b/reference/phar/PharFileInfo/isCompressed.xml @@ -1,5 +1,5 @@ - + PharFileInfo::isCompressed @@ -64,19 +64,15 @@ bool(true) PharFileInfo::getCompressedSize - PharFileInfo::isCompressedBZIP2 - PharFileInfo::isCompressedGZ - PharFileInfo::setCompressedBZIP2 - PharFileInfo::setUncompressed - PharFileInfo::setCompressedGZ + PharFileInfo::decompress + PharFileInfo::compress + Phar::decompress + Phar::compress Phar::canCompress Phar::isCompressed - Phar::compressAllFilesBZIP2 - Phar::compressAllFilesGZ Phar::getSupportedCompression - Phar::convertToPhar - Phar::convertToTar - Phar::uncompressAllFiles + Phar::decompressFiles + Phar::compressFiles diff --git a/reference/phar/PharFileInfo/isCompressedBZIP2.xml b/reference/phar/PharFileInfo/isCompressedBZIP2.xml index 534ae1e30f..8d1cc3fd5c 100644 --- a/reference/phar/PharFileInfo/isCompressedBZIP2.xml +++ b/reference/phar/PharFileInfo/isCompressedBZIP2.xml @@ -1,5 +1,5 @@ - + PharFileInfo::isCompressedBZIP2 @@ -11,6 +11,7 @@ boolPharFileInfo::isCompressedBZIP2 + &phar.removed.pharfileinfocompress; This returns whether a file is compressed within a Phar archive @@ -79,8 +80,6 @@ bool(true) Phar::compressAllFilesBZIP2 Phar::compressAllFilesGZ Phar::getSupportedCompression - Phar::convertToPhar - Phar::convertToTar Phar::uncompressAllFiles diff --git a/reference/phar/PharFileInfo/isCompressedGZ.xml b/reference/phar/PharFileInfo/isCompressedGZ.xml index 003b7b15d5..ad1a9c0eb2 100644 --- a/reference/phar/PharFileInfo/isCompressedGZ.xml +++ b/reference/phar/PharFileInfo/isCompressedGZ.xml @@ -1,5 +1,5 @@ - + PharFileInfo::isCompressedGZ @@ -11,6 +11,7 @@ boolPharFileInfo::isCompressedGZ + &phar.removed.pharfileinfocompress; This returns whether a file is compressed within a Phar archive @@ -79,8 +80,6 @@ bool(false) Phar::compressAllFilesBZIP2 Phar::compressAllFilesGZ Phar::getSupportedCompression - Phar::convertToPhar - Phar::convertToTar Phar::uncompressAllFiles diff --git a/reference/phar/PharFileInfo/setCompressedBZIP2.xml b/reference/phar/PharFileInfo/setCompressedBZIP2.xml index 97a3efbc57..742c2e5a9c 100644 --- a/reference/phar/PharFileInfo/setCompressedBZIP2.xml +++ b/reference/phar/PharFileInfo/setCompressedBZIP2.xml @@ -1,5 +1,5 @@ - + PharFileInfo::setCompressedBZIP2 @@ -11,6 +11,7 @@ boolPharFileInfo::setCompressedBZIP2 + &phar.removed.pharfileinfocompress; This method compresses the file inside the Phar archive using bzip2 compression. @@ -80,8 +81,6 @@ bool(true) Phar::compressAllFilesBZIP2 Phar::compressAllFilesGZ Phar::getSupportedCompression - Phar::convertToPhar - Phar::convertToTar Phar::uncompressAllFiles diff --git a/reference/phar/PharFileInfo/setCompressedGZ.xml b/reference/phar/PharFileInfo/setCompressedGZ.xml index eb106b3e4a..255499bbb5 100644 --- a/reference/phar/PharFileInfo/setCompressedGZ.xml +++ b/reference/phar/PharFileInfo/setCompressedGZ.xml @@ -1,5 +1,5 @@ - + PharFileInfo::setCompressedGZ @@ -11,6 +11,7 @@ boolPharFileInfo::setCompressedGZ + &phar.removed.pharfileinfocompress; This method compresses the file inside the Phar archive using gzip compression. @@ -80,8 +81,6 @@ bool(true) Phar::compressAllFilesBZIP2 Phar::compressAllFilesGZ Phar::getSupportedCompression - Phar::convertToPhar - Phar::convertToTar Phar::uncompressAllFiles diff --git a/reference/phar/PharFileInfo/setMetadata.xml b/reference/phar/PharFileInfo/setMetadata.xml index 0619945594..d8898aeae4 100644 --- a/reference/phar/PharFileInfo/setMetadata.xml +++ b/reference/phar/PharFileInfo/setMetadata.xml @@ -1,5 +1,5 @@ - + PharFileInfo::setMetaData @@ -19,10 +19,11 @@ 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; 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. + 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 if the file is within a Phar + archive. Files within PharData archives do not have + this restriction. Some possible uses for meta-data include passing a user/group that should be set diff --git a/reference/phar/PharFileInfo/setUncompressed.xml b/reference/phar/PharFileInfo/setUncompressed.xml index ce63b253a0..9cbdc81849 100644 --- a/reference/phar/PharFileInfo/setUncompressed.xml +++ b/reference/phar/PharFileInfo/setUncompressed.xml @@ -1,5 +1,5 @@ - + PharFileInfo::setUncompressed @@ -11,6 +11,7 @@ boolPharFileInfo::setUncompressed + &phar.removed.pharfileinfocompress; This method decompresses the file inside the Phar archive. diff --git a/reference/phar/book.xml b/reference/phar/book.xml index 09d3cc8d2b..6013ae124d 100644 --- a/reference/phar/book.xml +++ b/reference/phar/book.xml @@ -1,5 +1,5 @@ - + @@ -18,7 +18,7 @@ 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. + Phar::convertToExecutable for one example. What is phar? Phar archives are best characterized as a convenient way to group diff --git a/reference/phar/fileformat.xml b/reference/phar/fileformat.xml index ce6e01c580..db80d780a2 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?
@@ -203,8 +203,7 @@ __HALT_COMPILER(); To compress an entire archive, use Phar::compress. - To decompress an entire archive, use Phar::compress with - the Phar::NONE constant. + To decompress an entire archive, use Phar::decompress.
diff --git a/reference/phar/using.xml b/reference/phar/using.xml index 9b665e05c4..c64ae66428 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 = $p->convertToTar()->compress(Phar::GZ); + $p = $p->convertToExecutable(Phar::TAR, Phar::GZ); // create transaction - nothing is written to newphar.phar // until stopBuffering() is called, although temporary storage is needed @@ -99,7 +99,7 @@ try { $p['data/hugefile.dat'] = $fp; if (Phar::canCompress(Phar::GZ)) { - $p['data/hugefile.dat']->setCompressedGZ(); + $p['data/hugefile.dat']->compress(Phar::GZ); } $p['images/wow.jpg'] = file_get_contents('images/wow.jpg'); @@ -138,7 +138,7 @@ try { - + 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 + again. The literal myphar.phar demonstrates the concept of an alias that can be used to reference /path/to/myphar.phar in URLs as in: @@ -298,7 +298,12 @@ $f = file_get_contents('phar://myphar.phar/whatever.txt'); (phar://myphar.phar/file.php), or overwrites an existing file within myphar.phar. $v can be either a string or an open file pointer, in which case the entire - contents of the file will be used to create the new file. + contents of the file will be used to create the new file. Note that + $p->addFromString('file.php', $v) is functionally + equivalent to the above. Also possible is to add the contents of a file + with $p->addFile('/path/to/file.php', 'file.php'). + Lastly, an empty directory can be created with + $p->addEmptyDir('empty').