From 7dc7b75cb81980c642e45b18e64db003ea76c4e1 Mon Sep 17 00:00:00 2001 From: Greg Beaver Date: Sun, 28 Jan 2007 05:31:52 +0000 Subject: [PATCH] add docs for new functionality, update docs for old, fix a small typo git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@228280 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/phar/functions/Phar-beginWrite.xml | 111 ++++++++++++++++ reference/phar/functions/Phar-commitWrite.xml | 117 +++++++++++++++++ reference/phar/functions/Phar-count.xml | 5 +- .../phar/functions/Phar-getSignature.xml | 58 +++++++++ reference/phar/functions/Phar-getStub.xml | 112 +++++++++++++++++ .../functions/PharFileInfo-getMetaData.xml | 100 +++++++++++++++ .../PharFileInfo-setCompressedBZIP2.xml | 98 +++++++++++++++ .../PharFileInfo-setCompressedGZ.xml | 98 +++++++++++++++ .../functions/PharFileInfo-setMetaData.xml | 119 ++++++++++++++++++ .../PharFileInfo-setUncompressed.xml | 98 +++++++++++++++ reference/phar/reference.xml | 4 +- 11 files changed, 916 insertions(+), 4 deletions(-) create mode 100644 reference/phar/functions/Phar-beginWrite.xml create mode 100644 reference/phar/functions/Phar-commitWrite.xml create mode 100644 reference/phar/functions/Phar-getSignature.xml create mode 100644 reference/phar/functions/Phar-getStub.xml create mode 100644 reference/phar/functions/PharFileInfo-getMetaData.xml create mode 100644 reference/phar/functions/PharFileInfo-setCompressedBZIP2.xml create mode 100644 reference/phar/functions/PharFileInfo-setCompressedGZ.xml create mode 100644 reference/phar/functions/PharFileInfo-setMetaData.xml create mode 100644 reference/phar/functions/PharFileInfo-setUncompressed.xml diff --git a/reference/phar/functions/Phar-beginWrite.xml b/reference/phar/functions/Phar-beginWrite.xml new file mode 100644 index 0000000000..9c62b7787c --- /dev/null +++ b/reference/phar/functions/Phar-beginWrite.xml @@ -0,0 +1,111 @@ + + + + + Phar->beginWrite + Begin a Phar modification transaction + + + &reftitle.description; + + voidPhar->beginWrite + + + + + Although technically unnecessary, the beginWrite method + can provide a significant performance boost when creating or modifying a + Phar archive with a large number of files. Ordinarily, every time a file + within a Phar archive is created or modified in any way, the entire Phar + archive will be recreated with the changes. In this way, the archive will + be up-to-date with the activity performed on it. + + + However, this can be unnecessary when simply creating a new Phar archive, + when it would make more sense to write the entire archive out at once. + Similarly, it is often necessary to make a series of changes and to ensure + that they all are possible before making any changes on disk, similar to the + relational database concept of transactions. the + beginWrite/commitWrite pair + of methods is provided for this purpose. + + + Phar transactions are per-archive, a transaction active on the + foo.phar Phar archive does not affect changes + to the bar.phar Phar archive. + + + + + + &reftitle.examples; + + + A <function>Phar->beginWrite</function> example + + + +count() . " entries\n"; +$p->beginWrite(); +$p['file.txt'] = 'hi'; +$p['file2.txt'] = 'there'; +$p['file2.txt']->setCompressedGZ(); +$p['file3.txt'] = 'babyface'; +$p['file3.txt']->setMetaData(42); +$p->commitWrite(""); +?> +]]> + + + + + + + &reftitle.seealso; + + + Phar->commitWrite + Phar->getStub + + + + + + + diff --git a/reference/phar/functions/Phar-commitWrite.xml b/reference/phar/functions/Phar-commitWrite.xml new file mode 100644 index 0000000000..95644b0142 --- /dev/null +++ b/reference/phar/functions/Phar-commitWrite.xml @@ -0,0 +1,117 @@ + + + + + Phar->commitWrite + End a Phar modification transaction by writing the Phar archive to disk + + + &reftitle.description; + + voidPhar->commitWrite + + + + + Although technically unnecessary, the beginWrite method + can provide a significant performance boost when creating or modifying a + Phar archive with a large number of files. Ordinarily, every time a file + within a Phar archive is created or modified in any way, the entire Phar + archive will be recreated with the changes. In this way, the archive will + be up-to-date with the activity performed on it. + + + However, this can be unnecessary when simply creating a new Phar archive, + when it would make more sense to write the entire archive out at once. + Similarly, it is often necessary to make a series of changes and to ensure + that they all are possible before making any changes on disk, similar to the + relational database concept of transactions. the + beginWrite/commitWrite pair + of methods is provided for this purpose. + + + Phar transactions are per-archive, a transaction active on the + foo.phar Phar archive does not affect changes + to the bar.phar Phar archive. + + + + + + &reftitle.examples; + + + A <function>Phar->commitWrite</function> example + + + +commitWrite(); +var_dump($p->getStub()); +$p->commitWrite(""); +var_dump($p->getStub()); +?> +]]> + + &example.outputs; + +" +]]> + + + + + + + &reftitle.seealso; + + + Phar->beginWrite + Phar->getStub + + + + + + + diff --git a/reference/phar/functions/Phar-count.xml b/reference/phar/functions/Phar-count.xml index f5916b9f09..aced68f86c 100644 --- a/reference/phar/functions/Phar-count.xml +++ b/reference/phar/functions/Phar-count.xml @@ -1,5 +1,5 @@ - + Phar->count @@ -24,7 +24,8 @@ &reftitle.returnvalues; - The number of files containd within this phar, or 0 (the number zero) if none. + The number of files contained within this phar, or 0 (the number zero) + if none. diff --git a/reference/phar/functions/Phar-getSignature.xml b/reference/phar/functions/Phar-getSignature.xml new file mode 100644 index 0000000000..a56e6e1e1c --- /dev/null +++ b/reference/phar/functions/Phar-getSignature.xml @@ -0,0 +1,58 @@ + + + + + Phar->getSignature + Return MD5/SHA1 signature of a Phar archive + + + &reftitle.description; + + stringPhar->getSignature + + + + + Returns the verification signature of a phar archive in a hexadecimal string. + + + + + &reftitle.parameters; + + + + + &reftitle.returnvalues; + + The opened archive's signature. This signature is a hash calculated on the + entire phar's contents, and may be used to verify the integrity of the archive. + A valid signature is absolutely required of all phars if the + phar.require_hash INI variable + is set to true. + + + + + + + diff --git a/reference/phar/functions/Phar-getStub.xml b/reference/phar/functions/Phar-getStub.xml new file mode 100644 index 0000000000..6874c36c67 --- /dev/null +++ b/reference/phar/functions/Phar-getStub.xml @@ -0,0 +1,112 @@ + + + + + Phar->getStub + Return the PHP loader or bootstrap stub of a Phar archive + + + &reftitle.description; + + stringPhar->getStub + + + + + One of the features that differentiates a Phar archive from other familiar archive + formats like tar or zip is that a Phar archive is explicitly designed to be + included to allow distributing an application or library that can be + run without extraction directly from the archive. In order to accomplish + this, Phar archives contain a bootstrap loader, or stub + written in PHP that can perform any action. + + + + All stubs must end with + __HALT_COMPILER(); or the file is not a valid Phar archive. + + + + + &reftitle.returnvalues; + + Returns a string containing the contents of the bootstrap loader (stub) of + the current Phar archive. + + + + + &reftitle.examples; + + + A <function>Phar->getStub</function> example + +getStub(); +echo "==NEXT==\n"; +$p->commitWrite(""); +echo $p->getStub(); +]]> + + &example.outputs; + + +]]> + + + + + + + &reftitle.seealso; + + + Phar->commitWrite + Phar->beginWrite + + + + + + + + diff --git a/reference/phar/functions/PharFileInfo-getMetaData.xml b/reference/phar/functions/PharFileInfo-getMetaData.xml new file mode 100644 index 0000000000..2edaa280f9 --- /dev/null +++ b/reference/phar/functions/PharFileInfo-getMetaData.xml @@ -0,0 +1,100 @@ + + + + + PharFileInfo->getMetaData + Returns file-specific meta-data saved with a file + + + &reftitle.description; + + intPharFileInfo->getMetaData + + + + + + + + + &reftitle.parameters; + + + + + &reftitle.returnvalues; + + any PHP variable that can be serialized and is stored as meta-data for the file, + or &null; if no meta-data is stored. + + + + + &reftitle.examples; + + + A <function>PharFileInfo->getMetaData</function> example + + + +setMetaData(array('user' => 'bill', 'mime-type' => 'text/plain')); +var_dump($p['file.txt']->getMetaData()); +?> +]]> + + &example.outputs; + + + string(4) "bill" + ["mime-type"]=> + string(10) "text/plain" +} +]]> + + + + + + + &reftitle.seealso; + + + PharFileInfo->setMetaData + + + + + + + diff --git a/reference/phar/functions/PharFileInfo-setCompressedBZIP2.xml b/reference/phar/functions/PharFileInfo-setCompressedBZIP2.xml new file mode 100644 index 0000000000..a95fbeb838 --- /dev/null +++ b/reference/phar/functions/PharFileInfo-setCompressedBZIP2.xml @@ -0,0 +1,98 @@ + + + + + PharFileInfo->setCompressedBZIP2 + Compresses the current Phar entry within the phar using Bzip2 compression + + + &reftitle.description; + + boolPharFileInfo->setCompressedBZIP2 + + + + + This method causes the file referenced to be compressed using bzip2 compression. + The bzip2 extension must be enabled to take + advantage of this feature. In addition, if the file is already compressed using + gzip compression, the zlib extension must be enabled in order + 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. + + + + + &reftitle.errors; + + Throws BadMethodCallException if + the phar.readonly + INI variable is on, or if the bzip2 + extension is not available. + + + + + &reftitle.examples; + + + A <function>PharFileInfo->setCompressedBZIP2</function> example + +isCompressedBZIP2()); +$p['myfile.txt']->setCompressedBZIP2(); +var_dump($file->isCompressedBZIP2()); +?> +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + + PharFileInfo->getCompressedSize + PharFileInfo->isCompressedGZ + PharFileInfo->isCompressed + PharFileInfo->isCompressedGZ + PharFileInfo->isCompressed + + + + + + + diff --git a/reference/phar/functions/PharFileInfo-setCompressedGZ.xml b/reference/phar/functions/PharFileInfo-setCompressedGZ.xml new file mode 100644 index 0000000000..321553ef39 --- /dev/null +++ b/reference/phar/functions/PharFileInfo-setCompressedGZ.xml @@ -0,0 +1,98 @@ + + + + + PharFileInfo->setCompressedGZ + Compresses the current Phar entry within the phar using gz compression + + + &reftitle.description; + + boolPharFileInfo->setCompressedGZ + + + + + This method causes the file referenced to be compressed using gzip compression. + The zlib extension must be enabled to take + advantage of this feature. In addition, if the file is already compressed using + bzip2 compression, the bzip2 extension must be enabled in order + 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. + + + + + &reftitle.errors; + + Throws BadMethodCallException if + the phar.readonly + INI variable is on, or if the zlib + extension is not available. + + + + + &reftitle.examples; + + + A <function>PharFileInfo->setCompressedGZ</function> example + +isCompressedGZ()); +$p['myfile.txt']->setCompressedGZ(); +var_dump($file->isCompressedGZ()); +?> +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + + PharFileInfo->getCompressedSize + PharFileInfo->isCompressedBZIP2 + PharFileInfo->isCompressed + PharFileInfo->isCompressedBZIP2 + PharFileInfo->isCompressed + + + + + + + diff --git a/reference/phar/functions/PharFileInfo-setMetaData.xml b/reference/phar/functions/PharFileInfo-setMetaData.xml new file mode 100644 index 0000000000..22ff597dfb --- /dev/null +++ b/reference/phar/functions/PharFileInfo-setMetaData.xml @@ -0,0 +1,119 @@ + + + + + PharFileInfo->getMetaData + Sets file-specific meta-data saved with a file + + + &reftitle.description; + + intPharFileInfo->setMetaData + + + + + setMetaData should only be used to store customized data in a file + that cannot be represented with existing information stored with a file. + Meta-data can significantly slow down the performance of loading a phar + archive if the data is large, or if there are many files containing meta-data. + It is important to note that file permissions are natively supported inside a + phar, and you can use chmod to change the permissions of + files inside a phar. As with all functionality that modifies the contents of + a phar, the phar.readonly INI variable must be + off in order to succeed. + + + Some possible uses for meta-data include passing a user/group that should be set + when a file is extracted from the phar to disk. Other uses could include + explicitly specifying a MIME type to return. However, any useful data that + describes a file, but should not be contained inside of it may be stored. + + + + + + &reftitle.parameters; + + + + metadata + + + Any PHP variable containing information to store alongside a file + + + + + + + + + &reftitle.examples; + + + A <function>PharFileInfo->setMetaData</function> example + + + +setMetaData(array('user' => 'bill', 'mime-type' => 'text/plain')); +var_dump($p['file.txt']->getMetaData()); +?> +]]> + + &example.outputs; + + + string(4) "bill" + ["mime-type"]=> + string(10) "text/plain" +} +]]> + + + + + + + &reftitle.seealso; + + + PharFileInfo->getMetaData + + + + + + + diff --git a/reference/phar/functions/PharFileInfo-setUncompressed.xml b/reference/phar/functions/PharFileInfo-setUncompressed.xml new file mode 100644 index 0000000000..812e3e01d8 --- /dev/null +++ b/reference/phar/functions/PharFileInfo-setUncompressed.xml @@ -0,0 +1,98 @@ + + + + + PharFileInfo->setUncompressed + Uncompresses the current Phar entry within the phar, if it is compressed + + + &reftitle.description; + + boolPharFileInfo->setUncompressed + + + + + This method causes the file referenced to be uncompressed and re-saved. + 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. + + + + + &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->setUncompressed</function> example + +setCompressedGZ(); +var_dump($file->isCompressed()); +$p['myfile.txt']->setUncompressed(); +var_dump($file->isCompressed()); +?> +]]> + + &example.outputs; + + + + + + + + + &reftitle.seealso; + + + PharFileInfo->getCompressedSize + PharFileInfo->isCompressedGZ + PharFileInfo->isCompressedBZIP2 + PharFileInfo->isCompressedGZ + PharFileInfo->isCompressed + + + + + + + diff --git a/reference/phar/reference.xml b/reference/phar/reference.xml index 75f46663bf..8d096de989 100644 --- a/reference/phar/reference.xml +++ b/reference/phar/reference.xml @@ -1,5 +1,5 @@ - + @@ -37,7 +37,7 @@
&reftitle.required; - Phar requires PHP 5.2.0 or newer. Additional features require the + Phar requires PHP 5.2.1 or newer. Additional features require the SPL extension in order to take advantage of iteration and array access to a Phar's file contents. The phar stream does not require any additional extensions to function.