Subversion-Projekte lars-tiefland.php_share

<refentry id="{@id}">

 <refnamediv>

  <refname>Introduction to using VersionControl_SVN</refname>

  <refpurpose>Using VersionControl_SVN to manage a Subversion repository</refpurpose>

 </refnamediv>

 <refsynopsisdiv>

  <refsynopsisdivinfo>

   <author>

    Clay Loveless

    <authorblurb>{@link mailto:clay@killersoft.com clay@killersoft.com}</authorblurb>

   </author>

   <copyright>Copyright 2004, Clay Loveless</copyright>

  </refsynopsisdivinfo>

 </refsynopsisdiv>

 {@toc}

 <refsect1 id="{@id intro}">

  <title>Introduction</title>

  <para>

   VersionControl_SVN is a simple Object-Oriented interface for the <literal>svn</literal>

   command-line application that makes up the core of {@link http://subversion.tigris.org/ Subversion},

   a free/open-source version control system.

  </para>

  <para>

   Subversion can be used to manage trees of source code, text files, image files --

   just about <emphasis>any</emphasis> collection of files.

  </para>

  <para>

   VersionControl_SVN's features include:

   <unorderedlist>

    <listitem><para>Full support of <literal>svn</literal> subcommands.</para></listitem>

    <listitem><para>Flexible error reporting provided by {@link http://pear.php.net/manual/en/core.pear.pear-errorstack.php PEAR_ErrorStack}</para></listitem>

    <listitem><para>Multi-object factory design.</para></listitem>

    <listitem><para>Fully documented source code</para></listitem>

   </unorderedlist>

   The power of a version control system like Subversion, when accessed through VersionControl_SVN, can be

   extended far beyond typical "source code" repositories.

  </para>

  <simpara>

   For example, what content management system (CMS) couldn't benefit from version control functionality?

   For many non-programmers, version control is a confusing subject to get a firm grasp on. With VersionControl_SVN,

   developers are now able to customize the interface to Subversion with the ease-of-use goals of their

   particular audience in mind. VersionControl_SVN lets you leverage the strengths of version control without burdening

   end-users with the learning curve of change control fundamentals.

  </simpara>

 </refsect1>

 <refsect1 id="{@id example1}">

  <title>A Simple Example</title>

  <para>

   So you've got Subversion repository set up somewhere, and you want to take a look at what's

   inside with a PHP script. With the {@link VersionControl_SVN::VersionControl_SVN_List()} command,

   you're just a few steps away.

  </para>

  <para>

   <programlisting role="php">

<![CDATA[

<?php

require_once 'VersionControl/SVN.php';

// Setup error handling -- always a good idea!

$svnstack = &PEAR_ErrorStack::singleton('VersionControl_SVN');

// Set up runtime options.

$options = array('fetchmode' => VERSIONCONTROL_SVN_FETCHMODE_ARRAY);

// Request list class from factory

$svn = VersionControl_SVN::factory('list', $options);

// Define any switches and aguments we may need

$switches = array('username' => 'user', 'password' => 'pass');

$args = array('svn://svn.example.com/repos/TestProject');

// Run command

if ($output = $svn->run($args, $switches)) {

    print_r($output);

} else {

    if (count($errs = $svnstack->getErrors())) {

        foreach ($errs as $err) {

            echo '<br />'.$err['message']."<br />\n";

            echo "Command used: " . $err['params']['cmd'];

        }

    }

}

?>

]]>

   </programlisting>

  </para>

  <simpara>

   If your example repository above happened to have the VersionControl_SVN source in it,

   your output would be something like this:

  </simpara>

  <para>

   <programlisting role="php">

<![CDATA[

<?php

Array

(

    [0] => Array

        (

            [name] => docs

            [type] => D

        )

    [1] => Array

        (

            [name] => package.xml

            [type] => F

        )

    [2] => Array

        (

            [name] => SVN.php

            [type] => F

        )

    [3] => Array

        (

            [name] => SVN

            [type] => D

        )

    [4] => Array

        (

            [name] => tests

            [type] => D

        )

)

?>

]]>

   </programlisting>

  </para>

  <para>

   Note that in the above output, directories are flagged as type <literal>D</literal>, and

   files are flagged as type <literal>F</literal>.

  </para>

  <para>

   <emphasis>Note:</emphasis> For additional information in the output, try setting <literal>verbose</literal> to

   <literal>true</literal> in your <literal>$options</literal> array.

  </para>

 </refsect1>

 <refsect1 id="{@id example1}">

  <title>One Factory To Rule Them All</title>

  <para>

   Have a script that needs to utilize several VersionControl_SVN subclasses? At the expense of a little overhead, you

   can be sure your <literal>$svn</literal> objects are fully-loaded by using the {@link VersionControl_SVN::factory()} command

   keyword <emphasis><literal>__ALL__</literal></emphasis>.

  </para>

  <para>

   For example, in a basic script to get the list of current files in a repository, you just need the {@link VersionControl_SVN::VersionControl_SVN_List()}

   subclass.

  </para>

  <para>

   <programlisting role="php">

<![CDATA[

<?php

require_once 'VersionControl/SVN.php';

// Setup error handling -- always a good idea!

$svnstack = &PEAR_ErrorStack::singleton('VersionControl_SVN');

// Set up runtime options.

$options = array('fetchmode' => VERSIONCONTROL_SVN_FETCHMODE_ARRAY);

// Request list class from factory

$svn = VersionControl_SVN::factory('list', $options);

// Define any switches and aguments we may need

$switches = array('username' => 'user', 'password' => 'pass');

$args = array('svn://svn.example.com/repos/TestProject');

// Run command

if ($output = $svn->run($args, $switches)) {

    print_r($output);

} else {

    if (count($errs = $svnstack->getErrors())) {

        foreach ($errs as $err) {

            echo '<br />'.$err['message']."<br />\n";

            echo "Command used: " . $err['params']['cmd'];

        }

    }

}

?>

]]>

   </programlisting>

  </para>

  <simpara>

   However, if you need to get a recursive list of files in a repository, look up the recent log activity for those files,

   and view the annotated source for those files, you've got two options.

  </simpara>

  <para>

   <programlisting role="php">

<![CDATA[

<?php

require_once 'VersionControl/SVN.php';

// Setup error handling -- always a good idea!

$svnstack = &PEAR_ErrorStack::singleton('VersionControl_SVN');

// Set up runtime options.

$options = array('fetchmode' => VERSIONCONTROL_SVN_FETCHMODE_RAW);

// METHOD ONE: Lowest Overhead

// Create svn object with subcommands we need listed out individually

$svn = VersionControl_SVN::factory(array('list', 'log', 'blame'), $options);

// Define any switches and aguments we may need

$switches = array('username' => 'user', 'password' => 'pass');

$args = array('svn://svn.example.com/repos/TestProject');

print_r($svn->list->run($args, $switches));

// Pick files out of the above output, and see who did what

$args = array('svn://svn.example.com/repos/TestProject/trunk/index.php');

echo "<pre>" . $svn->blame->run($args) . "</pre>";

// METHOD TWO: Put all available commands at your disposal

// Load up all subcommands - higher overhead, but convenient for certain occasions

$svn = VersionControl_SVN::factory('__ALL__', $options);

// Now you may run whatever you need to ...

$svn->cat->run($args, $switches);

$svn->info->run($args, $switches);

// ... and so on.

?>

]]>

   </programlisting>

  </para>

 </refsect1>

 <refsect1 id="{@id reading}">

  <title>Further Reading</title>

  <para>

   If you are interested in learning more about Subversion, see the following:

   <unorderedlist>

    <listitem><para>{@link http://svnbook.red-bean.com/ Version Control with Subversion} - The primary reference

     manual for all things related to Subversion, from general use to repository administration.</para></listitem>

    <listitem><para>{@link http://subversion.tigris.org/ Subversion Website} - The official Subversion website

     offers a FAQ, mailing list, and of course, the Subversion source code. Also included are links to

     GUI Subversion applications.</para></listitem>

   </unorderedlist>

  </para>

 </refsect1>

</refentry>