cvs: peardoc /en/pyrus/extending packagefile.xml

cellog		Thu Jul  9 15:54:36 2009 UTC

  Modified files:              
    /peardoc/en/pyrus/extending	packagefile.xml 
  Log:
  docs on accessing package.xml files directly
  
http://cvs.php.net/viewvc.cgi/peardoc/en/pyrus/extending/packagefile.xml?r1=1.2&r2=1.3&diff_format=u
Index: peardoc/en/pyrus/extending/packagefile.xml
diff -u peardoc/en/pyrus/extending/packagefile.xml:1.2 peardoc/en/pyrus/extending/packagefile.xml:1.3
--- peardoc/en/pyrus/extending/packagefile.xml:1.2	Thu Jul  9 15:19:18 2009
+++ peardoc/en/pyrus/extending/packagefile.xml	Thu Jul  9 15:54:36 2009
@@ -426,8 +426,135 @@
  <section xml:id="pyrus.extending.packagefile.files">
   <info><title>Accessing files</title></info>
   <para>
-   This document is a work in progress.
+   There are two reasons to access the files within a package.xml
+   <orderedlist>
+    <listitem>
+     <para>
+      <link linkend="pyrus.extending.packagefile.files.iterate">iterating over contents</link>
+     </para>
+    </listitem>
+    <listitem>
+     <para>
+      <link linkend="pyrus.extending.packagefile.files.setting">adding new files/setting properties</link>
+     </para>
+    </listitem>
+   </orderedlist>
   </para>
+  <section xml:id="pyrus.extending.packagefile.files.iterate">
+   <info><title>Iterating over package.xml contents</title></info>
+   <para>
+    Pyrus supports several use cases for iterating over package.xml:
+    <itemizedlist>
+     <listitem><simpara>Iterating for installation purposes</simpara></listitem>
+     <listitem><simpara>Iterating for packaging purposes</simpara></listitem>
+     <listitem><simpara>Iterating for traversing a deep package.xml tree</simpara></listitem>
+     <listitem><simpara>General-purpose iteration</simpara></listitem>
+    </itemizedlist>
+    All of these use cases are illustrated in the following example:
+   </para>
+   <para>
+    <programlisting role="php">
+     <![CDATA[
+<?php
+// *************** installation iteration ***************
+foreach ($package->installcontents as $file) {
+    // retrieve actual file path to be used with fopen
+    $path = $package->getFilePath($file->packagedname);
+    // retrieve open file pointer
+    $fp = $package->getFileContents($file->packagedname, true);
+    // retrieve file contents as string
+    $contents = $package->getFileContents($file->packagedname);
+
+    // get file properties (XML attributes of the <file> tag)
+    $role = $file->role;
+    if ($file->md5sum) {
+        $md5sum = $file->md5sum;
+    }
+    // get relative path of file after applying all modifications such
+    // as <install name="" as=""/>
+    $relativepath = $file->name;
+    // get the path as specified in the <contents> <file> tag
+    // This is the same as $file->name if no <install as> tags exist
+    $originalpath = $file->packagedname;
+
+    // get the tasks associated with this file
+    $tasks = file->tasks;
+    // iterate over the tasks
+    $lastversion = '1.0.0'; // last version of $package that was installed, or null
+    foreach (new \pear2\Pyrus\Package\Creator\TaskIterator($tasks, $package,
+                                                          \pear2\Pyrus\Task\Common::INSTALL, $lastversion)
+              as $name => $task) {
+        // $name is the task name, $task is the actual task object, which can be
+        // processed with $task->startSession(resource $fp, '/full/final/install/path');
+    }
+}
+
+// *************** packaging iteration ***************
+$packagingloc = '/tmp/example';
+foreach ($package->packagingcontents as $packageat => $info) {
+    // $packageat is the location in which the file will reside in package.xml,
+    // which is often the same relative path it will end up being installed into
+    // $info is an array representing the actual file XML
+    $name = $info['attribs']['name'];
+    // this retrieves an open file pointer to the file in order to process it
+    $contents = $package->getFileContents($info['attribs']['name'], true);
+    if (!file_exists(dirname($packagingloc . DIRECTORY_SEPARATOR . $packageat))) {
+        mkdir(dirname($packagingloc . DIRECTORY_SEPARATOR . $packageat), 0777, true);
+    }
+    $fp = fopen($packagingloc . DIRECTORY_SEPARATOR . $packageat, 'wb+');
+    ftruncate($fp, 0);
+    // copy from the source directory to the packaging location
+    stream_copy_to_stream($contents, $fp);
+    fclose($contents);
+    rewind($fp);
+    $lastversion = '1.0.0'; // last version of $package that was installed, or null
+    foreach (new \pear2\Pyrus\Package\Creator\TaskIterator($info, $package,
+                                                          \pear2\Pyrus\Task\Common::PACKAGE,
+                                                          $lastversion) as $task) {
+        // do pre-processing of file contents
+        try {
+            $task->startSession($fp, $packageat);
+        } catch (\Exception $e) {
+            // handle task processing problems here
+        }
+    }
+    fclose($fp);
+}
+
+// *************** traversing deep tree iteration ***************
+foreach ($package->contents as $file) {
+    // retrieve actual file path to be used with fopen
+    $path = $package->getFilePath($file->name);
+    // retrieve open file pointer
+    $fp = $package->getFileContents($file->name, true);
+    // retrieve file contents as string
+    $contents = $package->getFileContents($file->name);
+
+    // get file properties (XML attributes of the <file> tag)
+    $role = $file->role;
+    if ($file->md5sum) {
+        $md5sum = $file->md5sum;
+    }
+
+    // unlike installcontents, <install as> tags are not applied, so
+    // $file->name == $file->packagedname
+    $relativepath = $file->name;
+}
+// *************** general purpose iteration ***************
+foreach ($package->files as $relativepath => $infoarray) {
+    // $relativepath is the same as $file->name in the other examples
+    // $infoarray is the same array returned by the packagingcontents
+    // iterator
+}
+?>
+     ]]>
+    </programlisting>
+   </para>
+  </section>
+  <section xml:id="pyrus.extending.packagefile.files.setting">
+   <info><title>Adding new files, changing file properties</title></info>
+   <para></para>
+  </section>
  </section>
  <section xml:id="pyrus.extending.packagefile.pecl">
   <info><title>Accessing PECL properties</title></info>