UserVoice PHP library for API connections

This library allows you to easily:

Generate SSO token for creating SSO users / logging them into UserVoice (http://uservoice.com).
Do 3-legged and 2-legged UserVoice API calls safely without having to worry about the cryptographic details (unless you want).

Installation

For installing OAuth, you should check if your operating system packaging system has PHP OAuth and MCrypt packages available. For example, for PHP 5.4 Homebrew comes with packages php54-oauth and php54-mcrypt. If your packaging systems is unable to install OAuth for PHP, you just need to install PECL/PEAR.

After getting PEAR you should have the command 'pecl' available, so run (detailed instructions. Homebrew equivalent: brew install php54-oauth):

sudo pecl install oauth

You also need mcrypt (detailed instructions. Homebrew equivalent: brew install php54-mcrypt):

When you get mcrypt and oauth installed, specify them in your php.ini file:

extension=oauth.so
extension=mcrypt.so

Finally, install Composer and place composer.phar in your PATH. Add uservoice/uservoice in your composer.json:

"uservoice/uservoice": ">=0.0.5"

Then install project dependencies using Composer:

composer.phar install

Now you should be good to go!

Examples

Prerequisites:

The mcrypt and oauth need to be installed. Check installation instructions above.
Place the following configuration parameters somewhere in your application:

# Suppose your UserVoice site is at http://uservoice-subdomain.uservoice.com/
$USERVOICE_SUBDOMAIN = 'uservoice-subdomain';
$SSO_KEY = '982c88f2df72572859e8e23423eg87ed'; # Admin Console -> Settings -> General -> User Authentication

# Define an API client at: Admin Console -> Settings -> Channels -> API
$API_KEY = 'oQt2BaunWNuainc8BvZpAm';
$API_SECRET = '3yQMSoXBpAwuK3nYHR0wpY6opE341inL9a2HynGF2';

// Use autoload.php of Composer to use the library and its dependencies:
require_once('vendor/autoload.php');

SSO-token generation using uservoice library

SSO-token can be used to create sessions for SSO users. They are capable of synchronizing the user information from one system to another. Generating the SSO token from SSO key and given uservoice subdomain can be done by calling UserVoice\SSO::generate_sso_token method like this:

<?php
    $sso_token = \UserVoice\SSO::generate_token($USERVOICE_SUBDOMAIN, $SSO_KEY, array(
        'display_name' => "John Doe",
        'email' => 'john.doe@example.com'
    ), 5*60); // the token will be valid for 5 minutes (5*60 seconds) by default

    echo 'https://' . $USERVOICE_SUBDOMAIN . '.uservoice.com/?sso='.$sso_token."\n";
?>

Making API calls

You need to create an instance of UserVoice\Client. Get $API_KEY and $API_SECRET for an API client which you can create from Admin Console. Go to Settings -> Channels -> API.

<?

try {
    $client = new \UserVoice\Client($USERVOICE_SUBDOMAIN, $API_KEY, $API_SECRET);

    // Get users of a subdomain (requires trusted client, but no user)
    $users = $client->get_collection("/api/v1/users");

    print "Subdomain \"" . $USERVOICE_SUBDOMAIN . "\" has " . count($users) . " users.\n";

    foreach($users as $user) {
        print("User: \"${user['name']}\", Profile URL: ${user['url']}\n");
    }


    // Now, let's login as mailaddress@example.com, a regular user
    $regular_access_token = $client->login_as('mailaddress@example.com');

    // Example request #1: Get current user.
    $r = $regular_access_token->get("/api/v1/users/current");
    $user = $r['user'];

    print("User: \"${user['name']}\", Profile URL: ${user['url']}\n");

    // Login as account owner
    $owner_access_token = $client->login_as_owner();

    // Example request #2: Create a new private forum limited to only example.com email domain.
    $r = $owner_access_token->post("/api/v1/forums", array(
        'forum' => array(
            'name' => 'PHP Client Private Feedback',
            'private' => true,
            'allow_by_email_domain' => true,
            'allowed_email_domains' => array(
                array('domain' => 'example.com')
            )
        )
    ));
    $forum = $r['forum'];

    print("Forum \"${forum['name']}\" created! URL: ${forum['url']}\n");
} catch (\UserVoice\Unauthorized $e) {
    /* Thrown usually due to faulty tokens, untrusted client or if attempting
     * operations without Admin Privileges
     */
    var_dump($e);
} catch (\UserVoice\NotFound $e) {
    // Thrown when attempting an operation to a resource that does not exist
    var_dump($e);
}

?>

Verifying a UserVoice user

If you want to make calls on behalf of a user, but want to make sure he or she actually owns certain email address in UserVoice, you need to use 3-Legged API calls. Just pass your user an authorize link to click, so that user may grant your site permission to access his or her data in UserVoice.