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

cellog                                   Thu, 06 Aug 2009 18:15:01 +0000

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

Log:
continue pyrus registry documentation

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 17:21:42 UTC (rev 286894)
+++ pear/peardoc/trunk/en/pyrus/extending/registry.xml	2009-08-06 18:15:01 UTC (rev 286895)
@@ -223,8 +223,168 @@
  <section xml:id="pyrus.extending.registry.querying">
   <info><title>Specialized querying of the registry</title></info>
   <para>
-   This document is a work in progress.
+   Other methods for querying the registry include:
+   <itemizedlist>
+    <listitem>
+     <simpara>
+      <function>info</function>
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <function>listPackages</function>
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <function>getDependentPackages</function>
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <function>detectFileConflicts</function>
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <function>detectRegistries</function>
+     </simpara>
+    </listitem>
+    <listitem>
+     <simpara>
+      <function>removeRegistry</function>
+     </simpara>
+    </listitem>
+   </itemizedlist>
   </para>
+  <section xml:id="pyrus.extending.registry.querying.info">
+   <title><function>info</function></title>
+   <para>
+    The <function>info</function> method provides a way of peeking at
+    a single attribute of a package.  When used with the <literal>Sqlite3</literal>
+    registry, it is extremely efficient both in terms of memory use and speed.
+    Both the <literal>Xml</literal> and <literal>Pear1</literal> registries are
+    far slower because they must load the complete packagefile into memory for
+    every query.  For these registries, it is better to simply retrieve a
+    packagefile and query it using the
+    <link linkend="pyrus.extending.packagefile">PackageFile API</link>.
+   </para>
+   <para>
+    Parameters to <function>info</function> are the package name, package channel,
+    and the field name to retrieve.
+   </para>
+   <para>
+    All of the
+    <link linkend="pyrus.extending.packagefile.basic">Basic package.xml properties</link>
+    can be directly accessed using <function>info</function>.  In addition, two
+    special properties, <literal>installedfiles</literal> and <literal>dirtree</literal>
+    are available.
+   </para>
+   <para>
+    <literal>installedfiles</literal> returns a list of files and their properties
+    as they have been installed.  Here is a sample return value:
+   </para>
+   <programlisting role="php">
+    <![CDATA[
+<?php
+array(
+      '/full/path/todocs/PEAR2_SimpleChannelServer/pear2.php.net/examples/update_channel.php' =>
+      array(
+        'role' => 'doc',
+        'name' => 'examples/update_channel.php',
+        'installed_as' => '/full/path/to/docs/PEAR2_SimpleChannelServer/pear2.php.net/examples/update_channel.php',
+        'relativepath' => 'PEAR2_SimpleChannelServer/pear2.php.net/examples/update_channel.php',
+        'configpath' => '/full/path/to/docs',
+           ),
+      // ... and so on
+     );
+?>
+    ]]>
+   </programlisting>
+   <para>
+    <literal>dirtree</literal> returns a list of every directory that would have
+    been created if installing the package in a new installation.  This can
+    be used to prune empty directories after uninstalling.  Here is a sample
+    return value:
+   </para>
+   <programlisting role="php">
+    <![CDATA[
+<?php
+array (
+      '/full/path/to/php/PEAR2/SimpleChannelServer/REST',
+      '/full/path/to/php/PEAR2/SimpleChannelServer/Categories',
+      '/full/path/to/php/PEAR2/SimpleChannelServer',
+      '/full/path/to/php/PEAR2',
+      '/full/path/to/php',
+      '/full/path/to/docs/PEAR2_SimpleChannelServer/pear2.php.net/examples',
+      '/full/path/to/docs/PEAR2_SimpleChannelServer/pear2.php.net',
+      '/full/path/to/docs/PEAR2_SimpleChannelServer',
+      '/full/path/to/docs',
+      '/full/path/to/bin',
+    );
+?>
+    ]]>
+   </programlisting>
+  </section>
+  <section xml:id="pyrus.extending.registry.querying.listpackages">
+   <title><function>listPackages</function></title>
+   <para>
+    This method accepts a channel name as an argument, and returns an array
+    of the names of installed packages from that channel.
+   </para>
+  </section>
+  <section xml:id="pyrus.extending.registry.querying.getdependentpackages">
+   <title><function>getDependentPackages</function></title>
+   <para>
+    <function>getDependentPackages</function> requires a single argument,
+    a <literal>pear2\Pyrus\IPackageFile</literal> object.
+    This method returns an array of <literal>pear2\Pyrus\Package</literal>
+    objects representing installed packages that depend upon the package
+    passed in.  If the optional second boolean parameter is set to true
+    (which it is by default), performance is improved when querying an
+    <literal>Sqlite3</literal> database by returning packages containing only
+    the name of the package and its dependencies.
+   </para>
+  </section>
+  <section xml:id="pyrus.extending.registry.querying.detectfileconflicts">
+   <title><function>detectFileConflicts</function></title>
+   <para>
+    This method is used to implement file conflict detection to prevent
+    overwriting installed files with those from another package.  It accepts a
+    single argument, a <literal>pear2\Pyrus\IPackageFile</literal> object.
+    The <literal>Pear1</literal> registry is the most efficient at this
+    operation (at the expense of drastically decreased efficiency at installation or
+    uninstallation), the <literal>Sqlite3</literal> is the next most
+    efficient, and the <literal>Xml</literal> registry is the least efficient,
+    and in fact is so inefficient, this method should only be called
+    on an Xml registry that is for a very small installation.
+   </para>
+  </section>
+  <section xml:id="pyrus.extending.registry.querying.detectregistries">
+   <title><function>detectRegistries</function></title>
+   <para>
+    This static method accepts a string containing the path to check for registries,
+    and returns an array containing the names of registries
+    found.  The possible return values include <literal>Sqlite3</literal>,
+    <literal>Xml</literal> and <literal>Pear1</literal>.  Note that only a call
+    to <function>pear2\Pyrus\Registry::detectRegistries</function> will return
+    a list of all registries found.  A call to
+    <function>pear2\Pyrus\Registry\Sqlite3::detectRegistries</function> will
+    only return either <literal>array()</literal> or
+    <literal>array('Sqlite3')</literal> depending on whether the registry exists.
+   </para>
+  </section>
+  <section xml:id="pyrus.extending.registry.querying.removeregistry">
+   <title><function>removeRegistry</function></title>
+   <para>
+    This static method accepts a string containing the path to remove a registry
+    from.  A call to <function>pear2\Pyrus\Registry::removeRegistry</function>
+    will completely remove all traces of a PEAR installation.  A call to
+    an individual registry's removeRegistry, such as a call to
+    <function>pear2\Pyrus\Registry\Pear1::removeRegistry</function> will only
+    remove that registry from the installation path.
+   </para>
+  </section>
  </section>
  <section xml:id="pyrus.extending.registry.channelregistry">
   <info><title>Channel registry</title></info>