Satisfaction-lib-docs

<!-- HTML file Satisfaction-lib-docs.html is auto-generated from Markdown -->

PHP Get Satisfaction Web API Library Documentation
==================================================

Synopsis
--------

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

Installation
------------

The library consists of a single PHP file which you can easily include from other PHP files; to use the caching features you will need to have a MySQL database with the following schema installed (just run this SQL command to create the table):

    create table http_cache (
      url varchar(1024),
      headers blob,
      content blob,
      fetched_on_server datetime not null,
      fetched_on timestamp not null
        default current_timestamp on update current_timestamp
    );

The interface consists of a set of functions for fetching API objects, posting data into the API, and manipulating the objects returned. This document describes the interface in detail.
 
Get Satisfaction API object identifiers
---------------------------------------

Every object in the Get Satisfaction web API has an ID, which is a URL that uniquely identifies it amongst all objects in the API (and indeed, anywhere else); this is called simply the object's ID. This ID can also 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. 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.

IDs in the Get Satisfaction API are opaque: you should not try to interpret the parts of the ID.

Many functions of 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.

Companies
---------

Companies are represented in the Get Satisfaction API using the vCard data model.

 * `company_hcard($company_id)`
 
   Returns the vCard data of a company; it accepts an ID or an sfn:id.

 * `company_name($compant_id)`
 
   Returns the name of a company, given `$company_id` as either kind of ID.

vCard data is an associative array. For companies, vCards may include the fields `fn` and `url`.

People
------

People are represented in the Get Satisfaction API using the vCard data model.

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.

 * `get_person($url)`
 
   Returns the vCard data for a person, given by URL (including an ID).
 
 * `get_me_person($consumer_data, $session_creds)`
 
   Returns the vCard data for "me". That is, given OAuth session credentials `$session_creds`, it returns the vCard data for the user authorized under those credentials. The `$consumer_data` argument gives the OAuth consumer data, which is provided when you sign up to use the Get Satisfaction API; it should be formatted as an array with keys `key` and `secret` containing the respective bits of data.

The following routines return a person's attributes with respect to a given company.

 * `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)`.

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 included in vCards returned by the `employees` function, but not in those returned by `get_person`, or `get_me_person`.

Products
--------

Product records have fields `name`, `uri`, and `image`.

 * `products($company_sfnid) `
 
   Teturns 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.

Tags
----

Tags can be fetched from a given URL using this routine.

* `tags($url)`
 
   Returns the tags found at `$url`.

Topics
------

Individual topics and lists of topics can be fetched with the following routines.

 * `topic($company_sfnid, $topic_id)`
 
   Fetches all the data for a single topic, by ID `$topic_id`; the result is a record containing these fields:

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

 * `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 array `$options` can contain at most one of the options `product`, `tag`, `query`, `person`, `followed`, or `related`. It can also contain any of the options `style` and `frequently_asked`.
   
   With no options, it returns all the topics for the company `$company_sfnid`. The options filter the returned list as follows:

    * `tag`
   
      Topics tagged with the given tag.
   
    * `product`
   
      Topics associated with the given product.
   
    * `person`
   
      Topics authored by the given person.
   
    * `related`
   
      Return topics related to the given string, according to the Get Satisfaction server.
   
    * `followed`
   
      Topics followed by the given person.
     
   The result is an associative array with fields:
   
    * `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 list of items returned by `topic` or `topics` is a list of feed items, the format of which is described here. Note that the items returned by `topics` are topics, but with `topic`, the first item is the "topic head"--it has the same fields as a topic in the `topics` result--but the other items are replies. Some fields are present for replies and not for topics, or vice versa

The format of each item is an array containing the following keys.

 * `id`
 
   The unique ID of the item (as a URI).
 
 * `sfn_id`
 
   The item's sfn:id, a number that uniquely distinguishes it from other items of the same kind (that is, from other topics, if this item is a topic, or other replies, if this one is a reply).
 
 * `title`
 
   In the case of topics, the topic title. In the case of replies, a descriptive string such as "John Q. replied to 'There's a green blob in my OJ.'"
   
 * `content`
 
   The content of the item, in HTML.
   
 * `author`
 
   A person record (see `get_person`, above) describing the author of the item.

 * `updated`, `updated_relative`, `updated_formatted`
 
   The timestamp when the item was last updated. The `updated` field is in seconds-since-the-epoch format; `updated_relative` is a human-readble string describing the approximate elapsed time since the update (such as, "2 weeks ago"); `updated_formatted` is a human-readable string giving the date of the update (such as, "December 8, 07"). 
   
   For a topic, the update time will reflect the latest replies under that topic.
 
 * `published`, `published_relative`, `published_formatted`
 
   The timestamp when the item was first published. The `published` field is in seconds-since-the-epoch format; `published_relative` is a human-readble string describing the approximate elapsed time since the publication (such as, "2 weeks ago"); `published_formatted` is a human-readable string giving the date of the publication (such as, "December 8, 07").
   
   The publication date of a topic is not affected by its replies.
 
 * `company_url`
 
   The company to which the topic pertains, represented as a URL. Not present for replies.
 
 * `at_sfn`
 
   A URL where the item can be found on the Get Satisfaction main site. This is a URL for a user interface to the item, as opposed to a machine-readable API resource.
 
 * `replies_url`

   The URL of the API resource where replies to the item should be posted. Not present for reply items.
 
 * `in_reply_to`
 
   For reply items, the ID (as a URI) of the item to which this one is a reply. For example, for top-level replies this would be a topic ID; for second-level replies this would be a reply ID. Not present for topic items.
   
 * `topic_style`
 
   For topic items, the style of the topic, one of the tokens `question`, `idea`, `problem`, or `talk`.
 
 * `reply_count`
 
   For topic items, the number of replies, whether direct or indirect. Not present for replies.
 
 * `follower_count`
 
   The number of people following this topic.
   
 * `star_count`
 
   The number of people who have starred this item.
   
 * `flag_count`
 
   The number of people who have flagged this item (as inappropriate).
   
 * `tags`
 
   A comma-separated list of tags on the item. Note that each comma may be immediately followed by whitespace which is not part of the tag, but whitespace following the next printing character is part of the tag.
   
 * `emotitag_face`
 
   A token identifying the face associated with the item, one of `happy`, `sad`, `silly` or `indifferent`.
 
 * `emotitag_severity`
 
   A number indicating the intensity of the associated emotion.
 
 * `emotitag_emotion`
 
   A string, the emotion entered by the author when posting the item. It is implicitly prefixed by the word "I'm": for example, if this field were "perplexed," it would normally be displayed as "I'm perplexed."
 
 * `star_promoted`
 
   For replies, a boolean indicating whether the reply has been promoted by the people, that is, through receiving a threshold number of stars from users.
 
 * `company_promoted`
  
   For replies, a boolean indicating whether the reply has been promoted by the owning company, which is performed through a separate administrative interface.

### Additional Feed Functions

Besides the above, which are included by default in the value returned by `topic` or `topics`, there are some available fields 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` and are described below.

 * `resolve_authors($company_sfnid, &$items)`
 
   Given a list of feed items (replies or topics), add to each author record the fields role and role_name, indicating the person's role at the company `$company_sfnid`. As elsewhere, role is a token, one of employee, `company_admin`, or `company_rep`, while `role_name` is a human-readable string.
   
   NOTE that the argument `$items` is destructively modified: `resolve_authors` has no return value but the necessary data is added to the argument array directly.
   
 * `resolve_companies(&$items)`
 
   Given a list of topic items, add to each one a field `company` which contains the hCard data of the corresponding company. This will fetch the `company_url` field and parse the resulting data.
   
   NOTE that the argument `$items` is destructively modified: `resolve_companies` has no return value but the necessary data is added to the argument array directly.
   
 * `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. This uses the `in-reply-to` field in the feed determine the threading structure.
   
   The `$root` parameter is the ID (and URL) of the root item in the feed, that is, the topic itself, the item which is not a reply to any other. 
   
   Presently, Get Satisfaction uses a two-level reply structure, so elements in the `replies` field do not themselves have replies. However, `thread_items` will handle deper nesting if it is given.
   
 * `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.

   For example, if the input held these four top-level items, each with a `replies` array as shown:
   
   * A's replies => []
   * B's replies => [B1, B2]
   * C's replies => [C1, C2, C3]
   * D's replies => [D1]
   
   then the result would be a flat list as follows:

   > A, B, B1, B2, C, C1, C2, C3, D, D1
   
   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-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.

 * `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)`.

Posting
-------

This section documents the routines used for posting data into Get Satisfaction.
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:

      'key' => $consumer_key
      'secret' => $consumer_secret

The routines for authorizing and posting through the API are as follows:

 * `oauthed_request($consumer_data, $method, $url,
                   $creds, $req_params, $query_params)`

   Make an API request, authenticated with OAuth.
   
   The `$consumer_data` argument is explained above. 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 (see docs for `HTTP_Request`). 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.
   
   OAuth credentials for a user are obtained through the OAuth authorization process (see the [Get Satisfaction API documentation](http://api.getsatisfaction.com/)).
   
 * `get_oauth_request_token($consumer_data)`

   Fetch an OAuth request token from the Get Satisfaction server, using consumer data from $consumer_data (formatted as above). 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.
 
 * `oauth_authorization_url($token, $callback_url)`
  
   Return 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, above) to fetch the OAuth access token, using the get_oauth_access_token, below. 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.
   
 * `get_oauth_access_token($consumer_data, $request_token, $request_token_secret)`
 
   Fetch an authorized access token for the given request token. The access token can be used for writing back to Get Satisfaction by passing it to the oauthed_request function (above).
   
   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.