cvs: peardoc / manual.xml /en/guide/users concepts.xml /en/guide/users/concepts maintainer.xml /en/pyrus extending.xml /en/pyrus/extending packagefile.xml

http://cvs.php.net/viewvc.cgi/peardoc/manual.xml?r1=1.10&r2=1.11&diff_format=u
Index: peardoc/manual.xml
diff -u peardoc/manual.xml:1.10 peardoc/manual.xml:1.11
--- peardoc/manual.xml:1.10	Wed Jul  1 19:18:31 2009
+++ peardoc/manual.xml	Thu Jul  9 04:53:24 2009
@@ -77,6 +77,7 @@
   &pyrus.differences;
   &pyrus.plugins;
   &pyrus.developers;
+  &pyrus.extending;
  </book>
 
  <book xml:id="developers">
http://cvs.php.net/viewvc.cgi/peardoc/en/guide/users/concepts.xml?r1=1.2&r2=1.3&diff_format=u
Index: peardoc/en/guide/users/concepts.xml
diff -u peardoc/en/guide/users/concepts.xml:1.2 peardoc/en/guide/users/concepts.xml:1.3
--- peardoc/en/guide/users/concepts.xml:1.2	Wed Jul  1 19:12:43 2009
+++ peardoc/en/guide/users/concepts.xml	Thu Jul  9 04:53:24 2009
@@ -15,6 +15,7 @@
   &guide.users.concepts.api;
   &guide.users.concepts.stability;
   &guide.users.concepts.version;
+  &guide.users.concepts.maintainer;
   &guide.users.concepts.abstractpackage;
   &guide.users.concepts.channel;
   &guide.users.concepts.filerole;

http://cvs.php.net/viewvc.cgi/peardoc/en/guide/users/concepts/maintainer.xml?view=markup&rev=1.1
Index: peardoc/en/guide/users/concepts/maintainer.xml
+++ peardoc/en/guide/users/concepts/maintainer.xml
<?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="guide.users.concepts.maintainer">
 <info><title>Maintainers and maintainer roles</title></info>

 <para>
  PEAR and PEAR2 calls its developers <literal>maintainers</literal>, and
  classifies maintainers by their level of contribution to a package, or
  their <literal>role</literal>.  In addition, each maintainer must choose a
  handle which can be used to refer
  to them in package.xml and in bug reports.  A handle is an alphanumeric
  word with all lower-cased letters such as <literal>cellog</literal>
  or <literal>tony2001</literal>.  If you are developing for pear.php.net,
  pear2.php.net or pecl.php.net, this handle is the account name you use
  to log into the website.
 </para>
 <para>
  Developer roles are <literal>lead</literal>, <literal>developer</literal>,
  <literal>contributor</literal> and <literal>helper</literal>.  Only lead
  maintainers have the permission to release a package.  Both lead and
  developer maintainers may create and modify package roadmaps, and
  all developers can directly log into pear.php.net and change the status of
  bugs for the packages that they maintain.
 </para>
 <para>
  For channels outside of pear.php.net, pecl.php.net, and pear2.php.net, these
  handles are still required, and have no special meaning beyond what the channel
  defines them to be.  However, both the Pyrus simple channel server and other
  external channel server implementations require the lead developer of a
  package to perform releases.
 </para>
</section>

http://cvs.php.net/viewvc.cgi/peardoc/en/pyrus/extending.xml?view=markup&rev=1.1
Index: peardoc/en/pyrus/extending.xml
+++ peardoc/en/pyrus/extending.xml
<?xml version="1.0" encoding="utf-8"?>
<chapter xmlns="http://docbook.org/ns/docbook" version="lillet" xml:id="pyrus.extending">
  <info>
   <title>Using Pyrus in your programs: Pyrus's Public API</title>
   <author><personname><firstname>Gregory</firstname><surname>Beaver</surname></personname></author>
   <date>2009-07-08</date>
  </info>

  <para>
   If you are doing advanced work with Pyrus, it is important to understand how
   to access its internals through its public <link linkend="guide.users.concepts.api">API</link>.
   This guide documents how to perform common tasks such as accessing components
   of a package.xml, managing installation tasks, and accessing configuration
   settings.
  </para>
  <para>
   The section on developing <link linkend="pyrus.plugins">plugins for Pyrus</link>
   is a good starting point for understanding how to extend Pyrus, this guide
   is more specific to using the actual classes contained within Pyrus.
  </para>

  &pyrus.extending.packagefile;
 </chapter>

http://cvs.php.net/viewvc.cgi/peardoc/en/pyrus/extending/packagefile.xml?view=markup&rev=1.1
Index: peardoc/en/pyrus/extending/packagefile.xml
+++ peardoc/en/pyrus/extending/packagefile.xml
<?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.packagefile">
 <info><title>Accessing package.xml properties with Pyrus</title></info>

 <section xml:id="pyrus.extending.packagefile.intro">
  <info><title>Introduction</title></info>
  <para>
   If you are not familiar with the package.xml format, you will need to read
   <link linkend="guide.developers.package2">The description of the file</link>.
  </para>
  <para>
   This guide is divided into several segments.
   <itemizedlist>
    <listitem>
     <para>
      If you want to access basic properties such as the name of the package,
      the channel, summary, description, license, version, stability, date,
      time, or notes, read the section on
      <link linkend="pyrus.extending.packagefile.basic">Accessing basic properties</link>
     </para>
    </listitem>
    <listitem>
     <para>
      To learn about how to manage maintainers of the package, read the section on
      <link linkend="pyrus.extending.packagefile.maintainers">Accessing package maintainers</link>.
     </para>
    </listitem>
    <listitem>
     <para>
      To learn about how to manage and iterate over dependencies, read the section on
      <link linkend="pyrus.extending.packagefile.deps">Accessing dependencies</link>.
     </para>
    </listitem>
    <listitem>
     <para>
      To understand how to iterate over and add files to both the contents
      and release sections of package.xml, read the section on
      <link linkend="pyrus.extending.packagefile.files">Accessing files</link>
     </para>
    </listitem>
    <listitem>
     <para>
      To learn about accessing PECL-specific properties such as configureoption,
      srcpackage, srcuri and providesextension, read the section on
      <link linkend="pyrus.extending.packagefile.pecl">Accessing PECL properties</link>
     </para>
    </listitem>
   </itemizedlist>
  </para>
  <para>
   The package.xml file is represented using a <literal>pear2\Pyrus\PackageFile\v2</literal>
   object, but most of the time you will access it using the most packagefile
   version-agnostic <literal>pear2\Pyrus\Package</literal> class, which supports
   the same API seamlessly for accessing any kind of package as well as a few
   higher level options such as directly accessing the source of a file in a package.
   This documentation assumes you are working with a <literal>pear2\Pyrus\Package</literal>
   object named <literal>$package</literal>.
  </para>
  <para>
   To instantiate a <literal>pear2\Pyrus\Package</literal>, simply pass in the
   path to a local package, a URI of a remote package, or an abstract remote package
   name to the constructor.
  </para>
  <para>
   <programlisting role="php">
    <![CDATA[
<?php
$package = new pear2\Pyrus\Package('package.xml');
$package = new pear2\Pyrus\Package('Release-1.2.3.tgz');
$package = new pear2\Pyrus\Package('http://example.com/Release-1.2.3.tgz');
$package = new pear2\Pyrus\Package('pear2/Release-1.2.3');
?>
    ]]>
   </programlisting>
  </para>
 </section>
 <section xml:id="pyrus.extending.packagefile.basic">
  <info><title>Accessing basic properties</title></info>
  <para>
   Basic properties can be accessed as if they were object properties:
  </para>
  <para>
   <programlisting role="php">
    <![CDATA[
<?php
echo "Package name is ", $package->name, "\n";
echo "Package channel is ", $package->channel, "\n";
echo "Package summary is ", $package->summary, "\n";
echo "Package description is ", $package->description, "\n";
echo "Package license name is ", $package->license['name'], "\n";
if ($package->license['uri']) {
    echo "Package license URI is ", $package->license['uri'], "\n";
}
if ($package->license['path']) {
    echo "Package license path within the package.xml is ", $package->license['path'], "\n";
}
echo "Package release version is ", $package->version['release'], "\n";
echo "Package API version is ", $package->version['api'], "\n";
echo "Package release stability is ", $package->stability['release'], "\n";
echo "Package API stability is ", $package->stability['api'], "\n";
echo "Package release date in YYYY-MM-DD format is ", $package->date, "\n";
if ($package->time) {
    echo "Package release time in HH:MM:SS format is ", $package->time, "\n";
}
echo "Package release notes is ", $package->notes, "\n";
?>
    ]]>
   </programlisting>
  </para>
  <para>
   By the same token, changing these properties is as simple as setting an object
   property:
  </para>
  <para>
   <programlisting role="php">
    <![CDATA[
<?php
$package->name = 'MyPackage';
// this must be full channel, not a shortcut like "pear2"
$package->channel = 'pear2.php.net';
$package->summary = "My package's short description";
$package->description = "My package's multi-line description
of how things are done with it.";

$package->license = 'BSD License';
// or
$package->license['name'] = 'BSD License';
$package->license['uri'] = 'http://www.opensource.org/licenses/bsd-license.php';
$package->license['path'] = 'LICENSE';

$package->version['release'] = '1.2.3';
$package->version['api'] = '1.0.0';

$package->stability['release'] = 'stable';
$package->version['api'] = 'stable';

$package->date = '2009-12-25';
$package->time = '00:00:01';

$package->notes = "This version of MyPackage has the blessing of the pope, so
it's way better than the last one.";
?>
    ]]>
   </programlisting>
  </para>
 </section>
 <section xml:id="pyrus.extending.packagefile.maintainers">
  <info><title>Accessing package maintainers</title></info>
  <para>
   Maintainers are accessed through the <literal>maintainer</literal>
   property.  An of maintainers organized by maintainer role can be obtained via
   the <literal>allmaintainers</literal> property, but it is also possible to
   iterate over the <literal>maintainer</literal> property to iterate over all
   maintainers.
  </para>
  <para>
   The <literal>maintainer</literal> property acts as an array organized by
   developer handle.  To learn more about maintainers in package.xml, see
   the <link linkend="guide.users.concepts.maintainer">concepts section on maintainers</link>
   in the user guide.
  </para>
  <para>
   An individual maintainer's properties are set via a fluent method call.  The
   order of method call is not important, but a call to the <function>role</function>
   method is required in order to properly save the data.
  </para>
  <para>
   <programlisting role="php">
    <![CDATA[
<?php
// setting a maintainer's properties
$package->maintainer['cellog']
    ->role('lead')
    ->name('Gregory Beaver')
    ->email('[email protected]')
    ->active('yes');

// access a maintainer's properties
echo "Maintainer cellog's name is ",
     $package->maintainer['cellog']->name, "\n"; // Gregory Beaver
echo "Maintainer cellog's role is ",
     $package->maintainer['cellog']->role, "\n"; // lead
echo "Maintainer cellog's handle is ",
     $package->maintainer['cellog']->user, "\n"; // cellog
echo "Maintainer cellog's email is ",
     $package->maintainer['cellog']->email, "\n"; // [email protected]
echo "Is maintainer cellog active? ",
     $package->maintainer['cellog']->active, "\n"; // yes
?>
    ]]>
   </programlisting>
  </para>
  <para>
   The maintainers can be iterated over as well, and even modified:
  </para>
  <para>
   <programlisting role="php">
    <![CDATA[
<?php
foreach ($package->maintainer as $handle => $maintainer) {
    echo "Maintainer $handle's name is ",
         $maintainer->name, "\n";
    echo "Maintainer $handle's role is ",
         $maintainer->role, "\n";
    echo "Maintainer $handle's handle is ",
         $maintainer->user, "\n";
    echo "Maintainer $handle's email is ",
         $maintainer->email, "\n";
    echo "Is maintainer $handle active? ",
         $maintainer->active, "\n";
    $maintainer->active('no'); // shows modifying a setting in iteration
}
?>
    ]]>
   </programlisting>
  </para>
  <para>
   The <literal>allmaintainers</literal> property returns an associative
   array of arrays of maintainer objects indexed by maintainer role.
  </para>
 </section>
 <section xml:id="pyrus.extending.packagefile.deps">
  <info><title>Accessing dependencies</title></info>
  <para>
   Before it is possible to understand how Pyrus provides access to dependencies,
   it is necessary to understand their format in package.xml, which is
   documented <link linkend="guide.developers.package2.dependencies">here</link>.
  </para>
  <para>
   Pyrus provides access to dependencies through the <literal>dependencies</literal>
   property.  In addition to supporting access to and creation of individual
   dependencies, it is possible to iterate over all dependencies, or over just
   required dependencies, or just a particular dependency type.
  </para>
  <para>
   Each of the dependency types (<literal>package</literal>, <literal>subpackage</literal>,
   <literal>pearinstaller</literal>, <literal>extension</literal>, <literal>php</literal>,
   <literal>arch</literal>, and <literal>os</literal>) is accessed slightly
   differently based on how they are used in package.xml.
  </para>
  <para>
   Perhaps the best introduction is 3 examples highlighting the different
   methods of accessing dependency properties.  First, an example highlighting
   the methods for reading existing dependency properties:
  </para>
  <para>
   <programlisting role="php">
    <![CDATA[
<?php
echo "First, required/optional dependencies:\n";

// these same principles apply to all properties for dependencies.
// isset() is used to test presence, ->get to retrieve.

echo "Minimum PHP version supported: ",
     $package->dependencies['required']->php->min, "\n";

echo "Minimum PEAR Installer/Pyrus version required: ",
     $package->dependencies['required']->pearinstaller->min, "\n";
if (isset($package->dependencies['required']->pearinstaller->max)) {
    echo "Maximum PEAR Installer/Pyrus version supported: ",
         $package->dependencies['required']->pearinstaller->max, "\n";
}

echo "PHP extension ext is required? "
     isset($package->dependencies['required']->extension['ext'])
         ? "Yes\n" : "No\n";

if (isset($package->dependencies['required']->os['windows'])) {
    echo "Conflicts with Windows operating system? "
         $package->dependencies['required']->os['windows']->conflicts
             ? "Yes\n" : "No\n";
}

if (isset($package->dependencies['required']->arch['*386*'])) {
    echo "Requires i386 processor? "
         $package->dependencies['required']->arch['*386*']->conflicts
             ? "No\n" : "Yes\n";
}

echo "Now for package and subpackage dependencies:\n";

echo "Is package foo from channel gronk.example.com required? ",
     isset($package->dependencies['required']->package['gronk.example.com/foo'])
         ? "Yes\n" : "No\n";

echo "Does this package conflict with our package? ",
     $package->dependencies['required']->package['gronk.example.com/foo']->conflicts
         ? "Yes\n" : "No\n";

echo "gronk.example.com/foo2 minimum version required is ",
     $package->dependencies['required']->subpackage['gronk.example.com/foo2']->min, "\n";

echo "gronk.example.com/foo2 incompatible versions:";
foreach ($package->dependencies['required']->subpackage['gronk.example.com/foo2']->exclude
         as $version) {
    echo "\n ", $version;
}

echo "\n";

echo "Optional dependencies are accessed the same way with optional index\n";

echo "Optional dependency gronk.example.com/foo3 minimum version allowed is ",
     $package->dependencies['optional']->subpackage['gronk.example.com/foo3']->min, "\n";

echo "Dependency groups are accessed with the group index\n";

echo "Dependency group foo hint is ",
     $package->dependencies['group']->foo->hint, "\n";

echo "channel pear2.php.net package Foo package dependency in dependency group",
     " foo minimum version is ",
     $package->dependecies['group']->foo->package['pear2.php.net/Foo']->min, "\n";

// and so on...
?>
    ]]>
   </programlisting>
  </para>
  <para>
   Iteration is similar to the access, in that each dependency object is the
   same object as that when accessed using the full access syntax:
  </para>
  <para>
   <programlisting role="php">
    <![CDATA[
<?php
// display all required and optional package and subpackage dependencies
foreach (array('required', 'optional') as $required) {
    foreach (array('package', 'subpackage') as $packagedep) {
        foreach ($package->dependencies[$required]->$packagedep as $dep) {
            echo $required, ' ', $packagedep, ' ', dependency,
                 $dep->channel, '/', $dep->name;
            if (isset($dep->uri)) {
                // the channel is "__uri" for all URI dependencies
                echo "\nPackage URI: ", $dep->uri;
            }
            if (isset($dep->min)) {
                echo "\nMinimum version: ", $dep->min;
            }
            if (isset($dep->recommended)) {
                echo "\nRecommended installation version: ", $dep->recommended;
            }
            echo "\n";
        }
    }
}

// iterating over dependency groups and their contents
foreach ($package->dependencies['group'] as $group) {
    echo "Optional dependency group ", $group->name,
         " (", $group->hint, ")\n";
    foreach ($group->extension as $ext) {
        echo "Extension ", $ext->name;
    }
    foreach (array('package', 'subpackage') as $type) {
        foreach ($group->$type as $dep) {
            echo ucfirst($type), ' ', $dep->channel, '/', $dep->name;
        }
    }
}
?>
    ]]>
   </programlisting>
  </para>
  <para>
   Finally, setting dependencies can be accomplished in several ways.
  </para>
  <para>
   This document is a work in progress.
  </para>
 </section>
 <section xml:id="pyrus.extending.packagefile.files">
  <info><title>Accessing files</title></info>
  <para>
   This document is a work in progress.
  </para>
 </section>
 <section xml:id="pyrus.extending.packagefile.pecl">
  <info><title>Accessing PECL properties</title></info>
  <para>
   This document is a work in progress.
  </para>
 </section>
</section>