PEAR Manual
Prev | Chapter 58. Tools and Utilities | Next

# VersionControl_SVN

VersionControl_SVN is a simple Object-Oriented interface for the svn command-line application that makes up the core of Subversion, a free/open-source version control system.

## Introduction

Subversion can be used to manage trees of source code, text files, image files -- just about any collection of files.

VersionControl_SVN's features include:

- Full support of `svn` subcommands.

- Flexible error reporting provided by PEAR_ErrorStack.

- Multi-object factory design.

- Fully documented source code

The power of a version control system like Subversion, when accessed through VersionControl_SVN, can be extended far beyond typical "source code" repositories.

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.

## A Simple Example

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 VersionControl_SVN::VersionControl_SVN_List() command, you're just a few steps away.

Example 58-1. Reading the content of a Subversion repository
    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'];
            }
        }
    }

If your example repository above happened to have the VersionControl_SVN source in it, your output would be something like this:

    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
            )

    )

Note that in the above output, directories are flagged as type `D`, and files are flagged as type `F`.

> Note: For additional information in the output, try setting `verbose` to `TRUE` in your `$options` array.

## One Factory To Rule Them All

Have a script that needs to utilize several VersionControl_SVN subclasses? At the expense of a little overhead, you can be sure your `$svn` objects are fully-loaded by using the VersionControl_SVN::factory() command keyword `__ALL__`.

For example, in a basic script to get the list of current files in a repository, you just need the VersionControl_SVN::VersionControl_SVN_List() subclass.

Example 58-2. Getting the list of current files in a repository
    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'];
            }
        }
    }

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.

Example 58-3. Recursively getting the list of current files in a repository
    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.

## Further Reading

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

- Version Control with Subversion - The primary reference manual for all things related to Subversion, from general use to repository administration.

- 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.

Prev | Home | Next
Tools and Utilities | Up | XML