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

cellog                                   Thu, 06 Aug 2009 04:33:18 +0000

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

Log:
begin documenting pyrus registry

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

Added: pear/peardoc/trunk/en/pyrus/extending/registry.xml
===================================================================
--- pear/peardoc/trunk/en/pyrus/extending/registry.xml	                        (rev 0)
+++ pear/peardoc/trunk/en/pyrus/extending/registry.xml	2009-08-06 04:33:18 UTC (rev 286864)
@@ -0,0 +1,136 @@
+<?xml version="1.0" encoding="utf-8"?>
+<section xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="lillet"
+         xml:id="pyrus.extending.registry">
+ <info><title>Working with installed packages and channels: The Registry API</title></info>
+
+ <section xml:id="pyrus.extending.registry.intro">
+  <info><title>Introduction</title></info>
+  <para>
+   Pyrus provides a very simple API for accessing its registry.  Pyrus stores
+   meta-information on installed packages in redundant registries.  There are
+   three kinds of registries that Pyrus recognizes, <literal>Sqlite3</literal>,
+   <literal>Xml</literal> and the legacy <literal>Pear1</literal> registry.  A
+   pyrus-based installation can have up to all three kinds of registries
+   redundantly storing the installed packages and the known channels.  By default
+   the <literal>Sqlite3</literal> registry is the primary registry used for
+   querying information, with the <literal>Xml</literal> registry as a backup.
+  </para>
+  <para>
+   When Pyrus is used to manage an installation, it checks to see which
+   registries are already present, if any, and will use the existing registries.
+   This fact can be used to provide more flexible installation options.  For
+   instance, Pyrus can be used to manage an existing legacy PEAR installation
+   without any special configuration, it will simply detect that the legacy
+   registry is present and use it.  If a package is extracted into a bundled
+   location, Pyrus will detect its extracted package.xml as belonging to the
+   Xml registry, and will use only that registry for installation purposes,
+   which allows upgrading the extracted package and avoids placing any
+   absolute paths into the installation.
+  </para>
+  <para>
+   Pyrus provides full atomic installation transactions for all of its
+   registry types, including the legacy Pear1 registry, unlike the PEAR
+   installer.  In addition, each registry provides a single method which
+   can be used to remove it from disk, and there is also a single method which
+   can be used for converting from one registry type to another.  Another method
+   is available for repairing a corrupted registry from one of its redundant
+   registries.
+  </para>
+  <para>
+   Pyrus provides a separate logical registry for storing channels from the registry
+   that stores packages.  Each registry handles this slightly differently.  The
+   Sqlite3 registry, for instance, stores all information in a single database.
+   The Xml registry stores information in separate files, like the legacy Pear1
+   registry.
+  </para>
+ </section>
+ <section xml:id="pyrus.extending.registry.basic">
+  <info><title>Basic Registry principles</title></info>
+  <para>
+   All registry classes implement the <literal>pear2\Pyrus\IChannel</literal>
+   interface, and all channelregistry classes implement the
+   <literal>pear2\Pyrus\ChannelRegistry</literal> interface.  The
+   <literal>pear2\Pyrus\Registry</literal> class acts as an aggregator of
+   underlying registries, and implements the ability to cascade to parent
+   registries, as does the <literal>pear2\Pyrus\ChannelRegistry</literal>
+   class.
+  </para>
+  <para>
+   The simplest way to retrieve a registry object is to use the one strongly
+   tied to the <link linkend="pyrus.extending.configuration">pear2\Pyrus\Config</link>
+   object:
+  </para>
+  <programlisting role="php">
+   <![CDATA[
+<?php
+$reg = pear2\Pyrus\Config::current()->registry;
+$creg = pear2\Pyrus\Config::current()->channelregistry;
+?>
+   ]]>
+  </programlisting>
+  <para>
+   Accessing a specific installed package retrieves an object that is
+   API-identical to a <link linkend="pyrus.extending.packagefile">PackageFile</link>
+   object.  The registry is implemented logically as an associative array.
+   By requesting a package's logical name, which is <literal>channel/packagename</literal>,
+   we get an object that can be manipulated just as if it were the package prior
+   to installation
+  </para>
+  <programlisting role="php">
+   <![CDATA[
+<?php
+$package = pear2\Pyrus\Config::current()->registry->package['pear2.php.net/PEAR2_Pyrus_Developer'];
+$remotepackage = new pear2\Pyrus\Package('pear2.php.net/PEAR2_Pyrus_Developer');
+// both packages can be queried with the same API
+?>
+   ]]>
+  </programlisting>
+  <para>
+   The same principle applies to channels:
+  </para>
+  <programlisting role="php">
+   <![CDATA[
+<?php
+$channel = pear2\Pyrus\Config::current()->channelregistry['pear2.php.net'];
+$localchannel = new pear2\Pyrus\ChannelFile('channel.xml');
+// both channels can be queried with the same API
+?>
+   ]]>
+  </programlisting>
+  <para>
+   Iteration also works with both just as it would for an array:
+  </para>
+  <programlisting role="php">
+   <![CDATA[
+<?php
+foreach (pear2\Pyrus\Config::current()->registry->package as $name => $package) {
+    // $name is channel/package
+    // $package is a packagefile object
+}
+foreach (pear2\Pyrus\Config::current()->channelregistry as $name => $channel) {
+    // $name is the channel name
+    // $channel is a channelfile object
+}
+?>
+   ]]>
+  </programlisting>
+ </section>
+ <section xml:id="pyrus.extending.registry.installation">
+  <info><title>Installation-related API tasks</title></info>
+  <para>
+   This document is a work in progress.
+  </para>
+ </section>
+ <section xml:id="pyrus.extending.registry.querying">
+  <info><title>Specialized querying of the registry</title></info>
+  <para>
+   This document is a work in progress.
+  </para>
+ </section>
+ <section xml:id="pyrus.extending.registry.channelregistry">
+  <info><title>Channel registry</title></info>
+  <para>
+   This document is a work in progress.
+  </para>
+ </section>
+</section>

Modified: pear/peardoc/trunk/en/pyrus/extending.xml
===================================================================
--- pear/peardoc/trunk/en/pyrus/extending.xml	2009-08-06 03:38:03 UTC (rev 286863)
+++ pear/peardoc/trunk/en/pyrus/extending.xml	2009-08-06 04:33:18 UTC (rev 286864)
@@ -22,4 +22,5 @@
   &pyrus.extending.packagefile;
   &pyrus.extending.configuration;
   &pyrus.extending.installation;
+  &pyrus.extending.registry;
  </chapter>