PHP Library

The PHP API Library provides a set of routines for fetching data from and posting data to Get Satisfaction. It includes functions for fetching companies, people, products, tags, and topics, as well as functions for writing back with an authorized Get Satisfaction account, include posting, starring and flagging topics.

Requirements

In addition to this you need MySQL to turn on the caching features.

Using the library

To use the library you only need to include Satisfaction.php, i.e. <?php require_once("Satisfaction.php"); (Remember to use the correct path to the file.)

To use the caching features you will need to have a MySQL database with the following schema installed:

API Object Identifiers

Every object in the Get Satisfaction API has an ID, which is a URL that uniquely identifies it. This ID can be used to fetch a representation of the object over HTTP. Because these IDs can be quite long, each one is also identified by a numeric ID distinguishing it from others of the same type; this is called the object's sfn:id or sfn_id. For example, the number 89521 is the sfn:id of a topic, but it might also be the sfn:id of a company, a person, or some other kind of object.

Many functions in the PHP Get Satisfaction API library accept just the ID or just the sfn:id of an object. Some functions accept one or the other, auto-detecting the sort of ID it has been given. Which type of ID a function accepts is made clear in its documentation.

Each function has a short comment describing its behavior in Satisfaction.php.

Companies

Function Arguments Note
company_hcard $company_id Returns the vCard data of a company; it accepts an ID or an sfn:id.
company_name $company_id Returns the name of a company, given $company_id as either kind of ID.

People

Function Arguments Note
get_person $url Returns the vCard data for a person, given by URL (including an ID).
get_me_person $consumer_data, $session_creds Given OAuth session credentials $session_creds, it returns the vCard data for the user authorized under those credentials. $consumer_data argument gives the OAuth consumer data, which is provided when you sign up to use the Get Satisfaction API.
get_person_from_string $str vCard data for an individual person can include the fields fn, photo, URL, role, and canonical_name. The fn field is the user's full name, which may be in use by other users. The canonical_name is a string that uniquely identifies the person; it can be seen as the person's primary key.
employee_list $company_sfnid Returns a list of employees for given the company (having sfn:id $company_sfnid), in the form of minimal vCards. These "minimal" vCards need only contain the fields URL and role; hence the employees function is generally more useful.
employees $company_sfnid Returns a list of employees of the given company, as full-fledged vCards, containing all the usual person fields as well as role and role_name (see below).
get_person_role $company_sfnid, $person_url Returns the role of the given person at the given company, as a pair list ($role, $role_name)

Note: The role_name field is a human-readable string describing the role; the role field is a token that identifies the role uniquely; currently the only roles are company_admin, company_rep and employee. Distinct roles may have the same human-readable role_name. A person may or may not have a role at a given company, and may have roles at more than one company. Thus "role" and "role_name" fields are only included in vCards returned by the employees() function.

Products

Function Arguments Note
product_list $company_sfnid Returns a list of the products associated with the given company.
products $company_sfnid Returns a list of the products associated with the given company, as product records.
get_product $url Fetches a product from $url, which may be an ID.

Note: Product records have fields name, uri, and image.

Tags

Function Arguments Note
tags $url Returns the tags found at $url.

Topics

Function Arguments Note
topic $company_sfnid, $topic_id Fetches all the data for a single topic by ID.
topics $company_sfnid, $options, $at_least Fetches a list of at least $at_least topics (defaulting to at least 1) under company $company_sfnid, according to the criteria specified in $options. The option can be 'product', 'tag', 'query', 'person', 'followed', or 'related'. It can also contain any of the options style and frequently_asked. If left empty it returns all the topics for the company.

The result of topic is an associative array containing:

  • replies
    An array containing the items in the topic's feed; this includes a first item, which is the topic "head", or starting post, and a list of replies to that post. Each item is in turn a record with fields corresponding to the data elements from the feed, plus some additional fields, described below under "Feed Entries"
  • particip
    An array of "person" records for people participating in the topic. The role fields of these records taken with respect to the company $company_sfnid.
  • tags
    An array of tags on this topic, each a simple string.

The result of topics is an associative array containing:

  • topics
    The list of topics, each formatted as described under "Feed Entries"
  • totals
    An associative array whose fields count the number of topics of various kinds (total, unanswered, questions, problems, and ideas) that are beneath the specified company.

Feed Entries

The 'updated' field (the date of last update, in epoch format) also drives 'updated_relative' (a string like "45 minutes ago") and 'updated_formatted' (something like "June 1, 2008") which are useful for use in the templates. Note that the first item in the 'replies' array is different: it is the "head" or "lead_item", the post the started the topic. It has different properties than the other items.

There are some fields available for each item which need to be separately fetched and thus could be expensive. To make this information available without paying the cost by default, there is a set of extra functions which modify a feed by adding in this additional information. These functions include resolve_authors and resolve_companies.

I dealt with this by adding an additional call that modifies the array, populating it with the additional data. The example is "resolve_companies" which fetches company data for each topic in a topics feed. I intend to use this technique to deal with such cases in the future.

Additional Feed Functions

Function Arguments Note
thread_items $feed, $root Given a feed as returned by topic(), convert it into "threaded" form. This means that the items in the resulting array are just the top-level replies; each of these has a 'replies' field which in turn contains a list of subordinate replies, formatted just as in the input. The $root parameter is the ID of the root item in the feed.
flatten_threads $items Given a threaded feed as returned by thread_items(), flatten it to a list by appending an item's replies after that item in the returned feed. This can be useful when preparing a threaded topic feed for use by a template; the flattened structure may be easier to use. The threading structure is still indicated by means of the 'in-reply-to' field of each item. As a convenience, the last item in each sub-thread is marked with a true value in a field thread_end.
filter_promoted $replies Filters a list of replies to the promoted items only, returning a pair of the company-promoted items and the star-promoted items, respectively.
company_partition $company_hcard, $topics Given a company, specified by its vCard, and a list $topics, separate $topics into those that partain to the given company and those that do not. The result is a pair list($company_topics, $other_topics).
  • Company-promoted items are those that a company representative has designated as useful.
  • Star-promoted items are those that have received a certain number of stars (currently 3) from Get Satisfaction users.

Posting

All posting operations use the OAuth standard and depend on having the authorization of a Get Satisfaction user account. OAuth provides a way for a user to authorize an API client to post on behalf of its account.

All OAuth requests are made on the basis of a "consumer key and secret," which are provided when you register to use the Get Satisfaction API. Each of the OAuth-related calls in this library accepts a $consumer_data parameter which is formatted as follows:

Make an API request, authenticated with OAuth

oauthed_request($consumer_data, $method, $url, $creds, $req_params, $query_params);

Arguments $method and $url specify the HTTP method to apply and the URL to apply it to. The $req_params specifies any additional parameters to the request—these are passed directly to the HTTP_Request object. The $query_params argument specifies additional URL query-string parameters (for a GET request) or request-body parameters (for a POST request).

The $creds argument gives the OAuth credentials of the user on whose behalf you are making the request. For example, to post a new topic as authored by a given user, use the credentials of that user. The $creds argument should be an array with fields 'token' and 'token_secret', containing the respective parts of the OAuth credentials.

Fetch an OAuth request token

get_oauth_request_token($consumer_data)

The result is a pair array($token, $token_secret) which can be used later, when the user returns from the authorization process, to identify the user. You might store this pair of tokens together with the user's cookie, so that you can match the ultimate authorization with a user session.

After obtaining the request_token, you should redirect the user to the URL provided by the oauth_authorization_url function, below, to permit the user to authorize that token.

URL to authorize (or deny) access to given token

oauth_authorization_url($token, $callback_url)

Returns a URL at which the user can authorize (or deny) access to the given token. If the user authorizes the token, he or she will be redirected to the given $callback_url, with an additional CGI parameter, oauth_token, whose value is the $token passed in.

For example, if the $token were 6cx2haob33pl and the $callback_url were

http://example.com/handle-oauth-return.php?foo=bar

Then, upon successful authorization, the user would be redirected to

http://example.com/handle-oauth-return.php?foo=bar&oauth_token=6cx2haob33pl

You can then use the request token and secret (as returned from get_oauth_request_token) to fetch the OAuth access token, using the get_oauth_access_token. Note the distinction between a request token and an access token: The request token is fetched before authorization, and is used to request authorization; the access token is fetched after authorization, and is used for all of that user's OAuth requests (such as posting a topic) during a the given session.

Fetch an authorized access token for the given request token

get_oauth_access_token($consumer_data, $request_token, $request_token_secret)

The access token can be used for writing back to Get Satisfaction by passing it to the oauthed_request function.

Once a user has authorized a request token, fetch an access token by calling get_oauth_access_token with the request token and secret that was returned by get_oauth_request_token for that particular user. This returns a new pair array($token, $token_secret) which constitutes a value for the $creds argument to oauthed_request. Once you've fetched the access token, the original request token for that user is no longer useful.

Utilities

Logging

For its internal use, and for the convenience of library users, the library offers three levels of logging, (debug, message, and error) which can be enabled or disabled using the globals.

  • $logging
    When set to false, no logging will occur. When set to true, error messages will be logged; debug messages and informational messages will be logged.
  • $verbose
    When set to false, no informational messages will be logged. When set true and logging is on (above) then informational messages will be logged.
  • $debugging
    When set to false, no debugging messages will be logged. When set to true and logging is on (above) then debugging messages will be logged.

The logging routines are as follows:

  • error($str)
    Send $str to the log as an error message.
  • message($str)
    Send $str to the log as an informational message.
  • debug($str)
    Send $str to the log as a debugging message.