From 831ba60a41b5578dd2f1b18f565c4921d6877318 Mon Sep 17 00:00:00 2001 From: Greg Beaver Date: Sun, 28 Jan 2007 21:45:44 +0000 Subject: [PATCH] docs are complete now for phar git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@228347 c90b9560-bf6c-de11-be94-00142212c4b1 --- reference/phar/functions/Phar-getMetaData.xml | 98 ++++++++ reference/phar/functions/Phar-setMetaData.xml | 116 +++++++++ reference/phar/reference.xml | 3 +- reference/phar/using.xml | 232 ++++++++++++++++++ 4 files changed, 448 insertions(+), 1 deletion(-) create mode 100644 reference/phar/functions/Phar-getMetaData.xml create mode 100644 reference/phar/functions/Phar-setMetaData.xml create mode 100644 reference/phar/using.xml diff --git a/reference/phar/functions/Phar-getMetaData.xml b/reference/phar/functions/Phar-getMetaData.xml new file mode 100644 index 0000000000..0e59d18d17 --- /dev/null +++ b/reference/phar/functions/Phar-getMetaData.xml @@ -0,0 +1,98 @@ + + + + + Phar->getMetaData + Returns phar archive meta-data + + + &reftitle.description; + + intPhar->getMetaData + + + + + + + + + &reftitle.parameters; + + + + + &reftitle.returnvalues; + + any PHP variable that can be serialized and is stored as meta-data for the Phar archive, + or &null; if no meta-data is stored. + + + + + &reftitle.examples; + + + A <function>Phar->getMetaData</function> example + + + +setMetaData(array('bootstrap' => 'file.php')); +var_dump($p->getMetaData()); +?> +]]> + + &example.outputs; + + + string(8) "file.php" +} +]]> + + + + + + + &reftitle.seealso; + + + PharFileInfo->setMetaData + + + + + + + diff --git a/reference/phar/functions/Phar-setMetaData.xml b/reference/phar/functions/Phar-setMetaData.xml new file mode 100644 index 0000000000..2dccabea89 --- /dev/null +++ b/reference/phar/functions/Phar-setMetaData.xml @@ -0,0 +1,116 @@ + + + + + Phar->setMetaData + Sets phar archive meta-data + + + &reftitle.description; + + intPhar->setMetaData + + + + + setMetaData should only 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 significantly slow down the performance of loading a phar + archive if the data is large. 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 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()); +?> +]]> + + &example.outputs; + + + string(8) "file.php" +} +]]> + + + + + + + &reftitle.seealso; + + + Phar->getMetaData + + + + + + + diff --git a/reference/phar/reference.xml b/reference/phar/reference.xml index 8d096de989..168f17ef08 100644 --- a/reference/phar/reference.xml +++ b/reference/phar/reference.xml @@ -1,5 +1,5 @@ - + @@ -74,6 +74,7 @@ + &reference.phar.using; &reference.phar.fileformat; &reference.phar.functions; diff --git a/reference/phar/using.xml b/reference/phar/using.xml new file mode 100644 index 0000000000..7f9c4eec05 --- /dev/null +++ b/reference/phar/using.xml @@ -0,0 +1,232 @@ + + +
+ Using Phar Archives: Introduction + + Phar archives are similar in concept to Java JAR archives, but are + tailored to the needs and to the flexibility of PHP applications. A + Phar archive is used to distribute a complete PHP application + or library in a single file. Unlike Java's implementation of JAR archives, + no external tool is required to process or run a PHP Phar archive. A + Phar archive application is processed exactly like any other PHP application: + + + + + + Using a Phar archive library is identical to using any other PHP library: + + + + ]]> + + + What makes Phar archives incredibly useful is the phar + stream wrapper, which is explained in depth here. + Using this stream wrapper, it is possible to access + individual files within a phar as if the phar were its own filesystem. + The phar stream wrapper supports all read/write operations + on files, and opendir on directories. + + + + ]]> + + + Also provided with the Phar extension is the Phar class, + which allows accessing the files of the Phar archive as if it were an + associative array, and other functionality. The Phar class is explained + here. + + + getFileName() . "\n"; + echo $file . "\n"; // display contents; + } + if (isset($p['internal/file.php'])) { + var_dump($p['internal/file.php']->getMetaData()); + } + + // create a new phar - phar.readonly must be 0 in php.ini + // phar.readonly is enabled by default for security reasons. + // On production servers, Phars need never be created, + // only executed. + if (Phar::canWrite()) { + $p = new Phar(dirname(__FILE__) . '/newphar.phar', 0, 'newphar.phar'); + // create transaction - nothing is written to disk until commit() is called + $p->begin(); + // add a new file, set its contents + $p['file1.txt'] = 'Information'; + $fp = fopen('hugefile.dat', 'rb'); + // copy from the stream + $p['data/hugefile.dat'] = $fp; + if (Phar::canCompress()) { + $p['data/hugefile.dat']->setCompressedGZ(); + } + $p['images/wow.jpg'] = file_get_contents('images/wow.jpg'); + // any value can be saved as file-specific meta-data + $p['images/wow.jpg']->setMetaData(array('mime-type' => 'image/jpeg')); + $p['index.php'] = file_get_contents('index.php'); + $p->setMetaData(array('bootstrap' => 'index.php')); + // save the Phar, and set the loader stub + $p->commit('getMetaData(); +require "phar://" . __FILE__ . "/" . $m["bootstrap"]; +__HALT_COMPILER();'); + } +} catch (BadMethodCallException $e) { + echo 'Could not open Phar: ', $e; +} +?> + ]]> + +
+
+ Using Phar Archives: the phar stream wrapper + + The Phar stream wrapper fully supports fopen for + read, write or append, unlink, stat, + fstat, fseek, rename + and directory stream operation opendir. The Phar stream wrapper + does not support creating or erasing a directory, as files are stored only + as files, and the concept of an abstract directory does not exist. + + + Individual file compression and per-file metadata can also be manipulated + in a Phar archive using stream contexts: + + + + array('compression' => Phar::GZ)), + array('metadata' => array('user' => 'cellog'))); +file_put_contents('phar://my.phar/somefile.php', 0, $context); +?> + ]]> + + + The phar stream wrapper does not operate on remote files, + and cannot operate on remote files, and so is allowed even when the + allow_url_fopen INI option + is disabled. + + + Although it is possible to create phar archives from scratch just using + stream operations, it is best to use the functionality built into + the Phar class. The stream wrapper is best used for read operations. + +
+
+ Using Phar Archives: the Phar class + + The Phar class supports reading and manipulation + of Phar archives, as well as iteration through inherited functionality of + the + RecursiveDirectoryIterator + class. With support for the ArrayAccess + interface, files inside a Phar archive can be accessed as if they were + part of an associative array. + + + Assuming that $p is a Phar object initialized as follows: + + + ]]> + + The following is possible: + + + + $a = $p['file.php'] creates a PharFileInfo + class that refers to the contents of phar://myphar.phar/file.php + + + + + $p['file.php'] = $v creates a new file + (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. + + + + + isset($p['file.php']) can be used to determine + whether phar://myphar.phar/file.php exists within + myphar.phar. + + + + + unset($p['file.php']) erases + phar://myphar.phar/file.php from + myphar.phar. + + + + + + In addition, the Phar object is the only way to access + Phar-specific metadata, through + Phar->getMetaData, + and the only way to set or retrieve a Phar archive's PHP loader stub through + Phar->getStub and + Phar->commit. + Additionally, compression for the entire Phar archive at once can only be manipulated + using the Phar class. + + + The full list of Phar object functionality is documented + below. + + + The PharFileInfo class extends the + SplFileInfo + class, and adds several methods for manipulating Phar-specific details of a file + contained within a Phar, such as manipulating compression and metadata. + +
+ + \ No newline at end of file