svn: /pear/peardoc/trunk/en/pyrus/extending/ registry.xml

cellog                                   Thu, 06 Aug 2009 17:21:42 +0000

Revision: http://svn.php.net/viewvc?view=revision&revision=286894

Log:
continue documenting pyrus registry

Changed paths:
    U   pear/peardoc/trunk/en/pyrus/extending/registry.xml

Modified: pear/peardoc/trunk/en/pyrus/extending/registry.xml
===================================================================
--- pear/peardoc/trunk/en/pyrus/extending/registry.xml	2009-08-06 16:25:43 UTC (rev 286893)
+++ pear/peardoc/trunk/en/pyrus/extending/registry.xml	2009-08-06 17:21:42 UTC (rev 286894)
@@ -118,8 +118,107 @@
  <section xml:id="pyrus.extending.registry.installation">
   <info><title>Installation-related API tasks</title></info>
   <para>
-   This document is a work in progress.
+   There are 4 installation-related methods, as well as 3 transaction methods.
+   These methods are:
+   <itemizedlist>
+    <listitem>
+     <simpara>
+      <function>install</function> and <function>replace</function>
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <function>uninstall</function>
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <function>exists</function>
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <function>begin</function>, <function>commit</function> and
+      <function>rollback</function>.
+     </simpara>
+    </listitem>
+   </itemizedlist>
+   The <function>install</function> method registers a package as installed,
+   and sets its date/time to the current time so that the installation time
+   can be tracked.  The <function>replace</function> method registers a package
+   as installed, but does not modify its date/time.  This is useful for
+   repairing a corrupted entry, or simply storing a package as it is.  Both
+   methods accept a <literal>pear2\Pyrus\IPackageFile</literal> object.  A
+   packagefile object can be retrieved from a <literal>pear2\Pyrus\Package</literal>
+   object by calling its <function>getPackageFileObject</function> method.
+   A <literal>pear2\Pyrus\Registry\Exception</literal> is thrown on any errors.
   </para>
+  <para>
+   The <function>uninstall</function> method accepts two parameters, the
+   name of the package, and the package's channel.  A
+   <literal>pear2\Pyrus\Registry\Exception</literal> is thrown on any errors.
+  </para>
+  <para>
+   The <function>exists</function> method also accepts two parameters, and
+   returns &true; or &false; depending on whether the package exists.  If
+   severe errors occur such as registry corruption, a
+   <literal>pear2\Pyrus\Registry\Exception</literal> object is thrown.
+  </para>
+  <para>
+   Note that array access can also be used to handle installation-related tasks:
+  </para>
+  <programlisting role="php">
+   <![CDATA[
+<?php
+$reg = pear2\Pyrus\Config::current()->registry;
+
+$package = new pear2\Pyrus\Package('/path/to/package.xml');
+
+// equivalent to $reg->install($package)
+$reg->package[] = $package;
+
+// equivalent to $reg->uninstall('Foo', 'pear2.php.net')
+unset($reg->package['pear2.php.net/Foo']);
+
+// equivalent to $reg->exists('Foo', 'pear2.php.net');
+isset($reg->package['pear2.php.net/Foo']);
+?>
+   ]]>
+  </programlisting>
+  <para>
+   When performing any installation or uninstallation task, it is recommended
+   to use the registry's built-in transaction support.  The
+   <literal>Sqlite3</literal> registry uses the database's native transaction
+   support.  Both the <literal>Xml</literal> and <literal>Pear1</literal>
+   registries use Pyrus's <literal>pear2\Pyrus\AtomicFileTransaction</literal>
+   for its transaction support.  Thus, it is always best to do a transaction
+   by first enabling the registry transaction, and then the atomic file transaction
+   within this registry transaction:
+  </para>
+  <programlisting role="php">
+   <![CDATA[
+<?php
+$reg = pear2\Pyrus\Config::current()->registry;
+$package = new pear2\Pyrus\Package('Whatever');
+try {
+    $reg->begin();
+    pear2\Pyrus\AtomicFileTransaction::begin();
+    $reg->install($package);
+    pear2\Pyrus\AtomicFileTransaction::commit();
+    $reg->commit();
+} catch (Exception $e) {
+    $reg->rollback();
+    pear2\Pyrus\AtomicFileTransaction::rollback();
+    throw $e;
+}
+?>
+   ]]>
+  </programlisting>
+  <para>
+   If using the <link linkend="pyrus.extending.installation">Installer API</link>,
+   the transactions and installation to registry is all automatic, this code is
+   only needed for customizing installation.
+  </para>
  </section>
  <section xml:id="pyrus.extending.registry.querying">
   <info><title>Specialized querying of the registry</title></info>