[prev in list] [next in list] [prev in thread] [next in thread]
List: pear-doc
Subject: [PEAR-DOC] svn: pear/peardoc/trunk/en/pyrus/
From: "Greg Beaver" <cellog () php ! net>
Date: 2009-07-14 3:02:46
Message-ID: svncellog1247540566 () svn ! php ! net
[Download RAW message or body]
cellog Tue, 14 Jul 2009 03:02:46 +0000
URL: http://svn.php.net/viewvc?view=revision&revision=284048
Changed paths:
A pear/peardoc/trunk/en/pyrus/extending/configuration.xml
A pear/peardoc/trunk/en/pyrus/extending/installation.xml
U pear/peardoc/trunk/en/pyrus/extending.xml
Log:
commit new docs on installation and configuration object API in pyrus (finally,
been sitting in my old cvs checkout for a week now)
[Attachment #3 (text/x-diff)]
Added: pear/peardoc/trunk/en/pyrus/extending/configuration.xml
===================================================================
--- pear/peardoc/trunk/en/pyrus/extending/configuration.xml \
(rev 0)
+++ pear/peardoc/trunk/en/pyrus/extending/configuration.xml 2009-07-14 03:02:46 UTC \
(rev 284048) @@ -0,0 +1,152 @@
+<?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.configuration"> + <info><title>Pyrus's configuration \
API</title></info> +
+ <section xml:id="pyrus.extending.configuration.intro">
+ <info><title>Introduction</title></info>
+ <para>
+ This documentation describes how to use Pyrus's public class API to access
+ configuration values. Before reading further, you should be familiar
+ with the documentation on Pyrus's <link \
linkend="pyrus.configuration">configuration</link>. + </para>
+ <para>
+ Pyrus's configuration is controlled by the <literal>pear2\Pyrus\Config</literal>
+ class, which is implemented as a multiton mapping Pyrus installation location
+ to a configuration object. In addition, the current configuration (most
+ recently instantiated) is also accessible to create configuration-agnostic
+ functionality.
+ </para>
+ <para>
+ Configuration variables are accessed by referring to them as class
+ properties. Here is an example requesting the <literal>doc_dir</literal>
+ configuration variable, and setting the <literal>test_dir</literal>
+ configuration variable:
+ </para>
+ <para>
+ <programlisting role="php">
+ <![CDATA[
+<?php
+$docdir = pear2\Pyrus\Config::current()->doc_dir;
+pear2\Pyrus\Config::current()->test_dir = '/path/to/tests';
+?>
+ ]]>
+ </programlisting>
+ </para>
+ <para>
+ The user configuration in use is also accessible from each configuration
+ in the same manner as the installation-specific configuration. Here is
+ an example requesting <literal>preferred_state</literal> and setting
+ <literal>verbose</literal>:
+ </para>
+ <para>
+ <programlisting role="php">
+ <![CDATA[
+<?php
+$pref = pear2\Pyrus\Config::current()->preferred_state;
+pear2\Pyrus\Config::current()->verbose = 3;
+?>
+ ]]>
+ </programlisting>
+ </para>
+ </section>
+ <section xml:id="pyrus.extending.configuration.special">
+ <title>Special variables available</title>
+ <para>
+ In addition to the configuration variables, Pyrus also defines a few
+ other values that are available, and cannot be used as the names
+ of custom configuration variables:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>path</literal> - the complete <constant>PATH_SEPARATOR</constant>
+ separated list of cascading directories this configuration represents.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>location</literal> - the writable pyrus installation this \
configuration + represents
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>registry</literal> - the registry corresponding to the configuration
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>pluginregistry</literal> - the registry corresponding to the
+ location that <link linkend="pyrus.plugins">plugins</link> are installed
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>channelregistry</literal> - the channel registry corresponding to
+ the configuration
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>systemvars</literal> - an array of names of system configuration
+ variables, built-in and custom
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>uservars</literal> - an array of names of user configuration
+ variables, built-in and custom
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>channelvars</literal> - an array of channel-specific configuration
+ variables, built-in and custom
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>mainsystemvars</literal> - an array of names of built-in
+ system variables
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>mainuservars</literal> - an array of names of built-in user
+ variables
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>mainchannelvars</literal> - an array of names of built-in
+ channel-specific variables
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>userfile</literal> - path to the user configuration file in use
+ by this configuration.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>customsystemvars</literal> - an array of names of custom
+ system variables
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>customuservars</literal> - an array of names of custom user
+ variables
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>customchannelvars</literal> - an array of names of custom
+ channel-specific variables
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+</section>
Property changes on: pear/peardoc/trunk/en/pyrus/extending/configuration.xml
___________________________________________________________________
Added: svn:keywords
+ Id Revision
Added: pear/peardoc/trunk/en/pyrus/extending/installation.xml
===================================================================
--- pear/peardoc/trunk/en/pyrus/extending/installation.xml \
(rev 0)
+++ pear/peardoc/trunk/en/pyrus/extending/installation.xml 2009-07-14 03:02:46 UTC \
(rev 284048) @@ -0,0 +1,118 @@
+<?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.installation"> + <info><title>Leveraging Pyrus's installation \
API</title></info> +
+ <section xml:id="pyrus.extending.installation.intro">
+ <info><title>Introduction</title></info>
+ <para>
+ Pyrus provides a very simple API for performing installation tasks. This
+ API begins with the ability to pass any packagename that can be
+ specified on the command-line to a <literal>pear2\Pyrus\Package</literal>
+ object:
+ </para>
+ <para>
+ <programlisting role="php">
+ <![CDATA[
+<?php
+// examples of the range of valid package names
+$package = new \pear2\Pyrus\Package('package.xml');
+$package = new \pear2\Pyrus\Package('/full/path/to/package.xml');
+$package = new \pear2\Pyrus\Package('Package-1.2.3.tgz');
+$package = new \pear2\Pyrus\Package('/full/path/to/Package-1.2.3.zip');
+$package = new \pear2\Pyrus\Package('RemotePackage');
+$package = new \pear2\Pyrus\Package('RemotePackage-alpha');
+$package = new \pear2\Pyrus\Package('RemotePackage-1.2.3');
+$package = new \pear2\Pyrus\Package('channelname/RemotePackage');
+$package = new \pear2\Pyrus\Package('http://example.com/RemotePackage-1.2.3.phar');
+?>
+ ]]>
+ </programlisting>
+ </para>
+ <para>
+ If there is a problem with the package name as passed to the constructor,
+ an exception is thrown. This can be any of a wide variety of exceptions
+ ranging from a <literal>pear2\Pyrus\PackageFile\Exception</literal> for
+ invalid package.xml, a <literal>pear2\Pyrus\Package\Exception</literal> for
+ higher-level errors (file does not exist, invalid abstract package name),
+ a <literal>pear2\Pyrus\Package\InstalledException</literal> if an abstract
+ remote package was requested and a newer version is installed, and
+ a <literal>pear2\Pyrus\Channel\Exception</literal> if any problems with
+ retrieving remote REST information occur. Also possible are
+ <literal>pear2\Pyrus\Package\Phar\Exception</literal> for errors relating
+ to local <literal>tar</literal>, <literal>tgz</literal>, <literal>zip</literal>
+ or <literal>phar</literal> archives.
+ </para>
+ </section>
+ <section xml:id="pyrus.extending.installation.install">
+ <info><title>Installing and Uninstalling packages</title></info>
+ <para>
+ Once you have a valid package object, installation is very simple. Pyrus
+ conducts all installation activities within a transaction, meaning that all
+ changes are applied nearly simultaneously, and any failure mid-transaction
+ does not leave an invalid installation lying around.
+ </para>
+ <para>
+ <programlisting role="php">
+ <![CDATA[
+<?php
+// import the class names into the current scope
+// this step is optional, you can also use the full class names
+// like pear2\Pyrus\Installer::begin()
+use pear2\Pyrus\Installer as Installer,
+ pear2\Pyrus\Package as Package;
+
+try {
+ $p1 = new Package('package.xml');
+ $p2 = new Package('Package.tgz');
+ $p3 = new Package('pear2/RemotePackage');
+
+ // here is the meat of the installation transaction
+ Installer::begin();
+
+ Installer::prepare($p1);
+ Installer::prepare($p2);
+ Installer::prepare($p3);
+
+ Installer::commit();
+} catch (\Exception $e) {
+ echo "Install failed\n";
+}
+?>
+ ]]>
+ </programlisting>
+ </para>
+ <para>
+ Uninstalling a package is even simpler:
+ </para>
+ <para>
+ <programlisting role="php">
+ <![CDATA[
+<?php
+// import the class names into the current scope
+// this step is optional, you can also use the full class names
+// like pear2\Pyrus\Uninstaller::begin()
+use pear2\Pyrus\Uninstaller as Uninstaller;
+
+try {
+ $p1 = new Package('package.xml');
+ $p2 = new Package('Package.tgz');
+ $p3 = new Package('pear2/RemotePackage');
+
+ // here is the meat of the installation transaction
+ Uninstaller::begin();
+
+ Uninstaller::prepare('pear2.php.net/Package1');
+ Uninstaller::prepare('pear.php.net/Package');
+ Uninstaller::prepare('__uri/Package');
+
+ Uninstaller::commit();
+} catch (\Exception $e) {
+ echo "Uninstall failed\n";
+}
+?>
+ ]]>
+ </programlisting>
+ </para>
+ </section>
+</section>
Property changes on: pear/peardoc/trunk/en/pyrus/extending/installation.xml
___________________________________________________________________
Added: svn:keywords
+ Id Revision
Modified: pear/peardoc/trunk/en/pyrus/extending.xml
===================================================================
--- pear/peardoc/trunk/en/pyrus/extending.xml 2009-07-14 02:40:32 UTC (rev 284047)
+++ pear/peardoc/trunk/en/pyrus/extending.xml 2009-07-14 03:02:46 UTC (rev 284048)
@@ -20,4 +20,6 @@
</para>
&pyrus.extending.packagefile;
+ &pyrus.extending.configuration;
+ &pyrus.extending.installation;
</chapter>
--
PEAR Documentation List Mailing List (http://pear.php.net/)
To unsubscribe, visit: http://www.php.net/unsub.php
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic