guoyu07 / php-viewvc-api-react

Simple, async access to your ViewVC web interface, built on top of React PHP

clue/viewvc-api-react

Simple, async API-like access to your ViewVC web interface (Subversion/CVS browser), built on top of React PHP.

Table of Contents

• Quickstart example
• Usage
  • Client
    • Actions
    • Promises
    • Blocking
    • Streaming
• Install
• License

Quickstart example

Once installed, you can use the following code to fetch a directory listing from the given ViewVC URL:

$loop = React\EventLoop\Factory::create();
$browser = new Clue\React\Buzz\Browser($loop);
$client = new Client($browser->withBase('http://example.com/viewvc/'));

$client->fetchDirectory('/')->then(function ($files) {
    echo 'Files: ' . implode(', ', $files) . PHP_EOL;
});

$loop->run();

See also the examples.

Usage

Client

The Client is responsible for assembling and sending HTTP requests to the remote ViewVC web interface. It requires a Browser object bound to the main EventLoop in order to handle async requests:

$loop = React\EventLoop\Factory::create();
$browser = new Clue\React\Buzz\Browser($loop);

$client = new Client($browser->withBase('http://example.com/viewvc/'));

The Client API uses relative URIs to reference files and directories in your ViewVC installation, so make sure to apply the base URI as depicted above.

If you need custom DNS or proxy settings, you can explicitly pass a custom Browser instance.

Actions

ViewVC does not officially expose an API. However, its REST-like URLs make it easy to construct the right requests and scrape the results from its HTML output. All public methods resemble these respective actions otherwise available in the ViewVC web interface.

$client->fetchDirectory($path, $revision = null);
$client->fetchFile($path, $revision = null);
$client->fetchPatch($path, $r1, $r2);
$client->fetchLog($path, $revision = null);

// many more…

All actions support async operation by returning promises.

Listing all available actions is out of scope here, please refer to the class outline.

Promises

Sending requests is async (non-blocking), so you can actually send multiple requests in parallel. ViewVC will respond to each request with a response message, the order is not guaranteed. Sending requests uses a Promise-based interface that makes it easy to react to when a request is fulfilled (i.e. either successfully resolved or rejected with an error).

$client->fetchFile($path)->then(
    function ($contents) {
        // file contents received
    },
    function (Exception $e) {
        // an error occured while executing the request
    }
});

If this looks strange to you, you can also use the more traditional blocking API.

Blocking

As stated above, this library provides you a powerful, async API by default.

If, however, you want to integrate this into your traditional, blocking environment, you should look into also using clue/block-react.

The resulting blocking code could look something like this:

use Clue\React\Block;

$loop = React\EventLoop\Factory::create();
$browser = new Clue\React\Buzz\Browser($loop);

$client = new Client($browser->withBase($uri /* change me */));
$promise = $client->fetchFile($path /* change me */);

try {
    $contents = Block\await($promise, $loop);
    // file contents received
} catch (Exception $e) {
    // an error occured while executing the request
}

Refer to clue/block-react for more details.

Streaming

The following API endpoint resolves with the file contents as a string:

$client->fetchFile($path);

Keep in mind that this means the whole string has to be kept in memory. This is easy to get started and works reasonably well for smaller files.

For bigger files it's usually a better idea to use a streaming approach, where only small chunks have to be kept in memory. This works for (any number of) files of arbitrary sizes.

The following API endpoint complements the default Promise-based API and returns an instance implementing ReadableStreamInterface instead:

$stream = $client->fetchFileStream($path);

$stream->on('data', function ($chunk) {
    echo $chunk;
});

$stream->on('error', function (Exception $error) {
    echo 'Error: ' . $error->getMessage() . PHP_EOL;
});

$stream->on('close', function () {
    echo '[DONE]' . PHP_EOL;
});

Install

The recommended way to install this library is through Composer. New to Composer?

This will install the latest supported version:

$ composer require clue/viewvc-api-react:^0.4

See also the CHANGELOG for details about version upgrades.

License

MIT